Adopt mise toolchain, extend CMake 3.30 support, update CI and docs

.github/workflows/docs.yml

@@ -4,6 +4,8 @@ on:
   push:
     branches:
       - main
+permissions:
+  contents: write
 jobs:
   latest:
     name: Generate

.github/workflows/test.yml

@@ -7,11 +7,15 @@ on:
     - '!pr/**'
     - '!dependabot/**'
   pull_request:
+permissions:
+  contents: read
 jobs:
   main:
     strategy:
       matrix:
         cmake:
+        - '3.31'
+        - '3.30'
         - '3.29'
         - '3.28'
         - '3.27'

.gitignore

@@ -1 +1,2 @@
 __pycache__
+build/

CHANGELOG.rst

@@ -6,6 +6,20 @@ Changelog
 Unreleased **v1.1.0** 2021-xx-xx
 ================================
 
+Changed
+-------
+
+* Policy range of the build scripts is now ``3.15...3.30``.
+  The minimum required CMake version stays at 3.15.
+
+New
+---
+
+* CI tests CMake 3.30 and 3.31.
+* The developer toolchain can be installed with `mise <https://mise.jdx.dev>`_.
+  See ``mise.toml``.
+* Document how to provide a fallback value for
+  :variable:`<prefix>_GIT_VERSION`.
 
 **v1.0.0** 2021-09-08
 =====================

CMakeLists.txt

@@ -7,7 +7,7 @@
 ################################################################################
 
 cmake_minimum_required(VERSION 3.15 FATAL_ERROR)
-cmake_policy(VERSION 3.15...3.23)
+cmake_policy(VERSION 3.15...3.30)
 
 project(FairCMakeModules VERSION 1.0.0 LANGUAGES CXX
         HOMEPAGE_URL "https://github.com/FairRootGroup/FairCMakeModules")

FairCMakeModules_test.cmake

@@ -7,7 +7,7 @@
 ################################################################################
 
 cmake_minimum_required(VERSION 3.15 FATAL_ERROR)
-cmake_policy(VERSION 3.15...3.20)
+cmake_policy(VERSION 3.15...3.30)
 
 if(NOT STEPS)
   list(APPEND STEPS clean configure build install test)

docs/development.rst

@@ -26,6 +26,18 @@ Source Tree Structure
     CTest in ``tests/CMakeLists.txt``.
 
 
+Toolchain
+=========
+
+Install `mise <https://mise.jdx.dev>`_ and run ``mise install`` to get CMake
+and Python as pinned in ``mise.toml``. A C++ compiler and Git must come from
+the system. Then use:
+
+``mise run test``
+    Configure, build, install and test.
+``mise run docs``
+    Install the Sphinx requirements and build the documentation.
+
 Git
 ===
 

mise.toml

@@ -0,0 +1,24 @@
+[tools]
+cmake = "3.30"
+python = "3.12"
+
+[tasks.configure]
+description = "Configure the project"
+run = 'ctest -VV -D "STEPS=clean;configure" -S FairCMakeModules_test.cmake'
+
+[tasks.build]
+description = "Build the project"
+run = 'ctest -VV -D "STEPS=build" -S FairCMakeModules_test.cmake'
+
+[tasks.test]
+description = "Configure, build, install and test"
+run = 'ctest -VV -S FairCMakeModules_test.cmake'
+
+[tasks.docs-deps]
+description = "Install the documentation requirements"
+run = "python -m pip install -r docs/requirements.txt"
+
+[tasks.docs]
+description = "Build the documentation"
+depends = ["docs-deps"]
+run = 'ctest -VV -D "STEPS=clean;configure;docs" -S FairCMakeModules_test.cmake'

src/modules/FairProjectConfig.cmake

@@ -63,6 +63,23 @@ Output variables:
     A version string that is created from the output of
     ``git describe``.
 
+.. note::
+
+   The function sets the output variables with ``set(... PARENT_SCOPE)``
+   and only if it detected a version. Standard CMake variable scoping
+   rules apply.
+
+   A project can therefore let its users provide a fallback version
+   (for example when building from a tarball without Git metadata) by
+   documenting its ``<prefix>`` and accepting
+
+   .. code-block:: shell
+
+      cmake -D<prefix>_GIT_VERSION=3.1.4 ...
+
+   The fallback does not work together with the ``REQUIRED`` option.
+   A detected Git version takes precedence over the fallback.
+
 #]=======================================================================]
 find_package(Git QUIET)
 function(fair_get_git_version)

tests/project_mode_include/CMakeLists.txt

@@ -1,4 +1,4 @@
-cmake_minimum_required(VERSION 3.10...3.20)
+cmake_minimum_required(VERSION 3.10...3.30)
 project(project_mode VERSION 1.2.3 LANGUAGES NONE)
 include(CMakePrintHelpers)
 

tests/test_module.cmake

@@ -6,7 +6,7 @@
 #              GNU Lesser General Public Licence (LGPL) version 3,             #
 #                  copied verbatim in the file "LICENSE"                       #
 ################################################################################
-cmake_minimum_required(VERSION 3.15...3.20)
+cmake_minimum_required(VERSION 3.15...3.30)
 include(CMakePrintHelpers)
 include(TestLib)
 include(${MODULE})