project: Add SPDX_LICENSE argument

Add an argument to the `project` command to allow specifying a license for a project as a whole. This is in addition to specifying licenses on individual targets, and will be used to set the license(s) on exported packages. Also, move listing of `COMPAT_VERSION` variables to follow lexicographical order.
2025-10-14 02:08:27 +08:00 · 2025-06-13 12:07:02 -04:00
parent f0b419c473
commit fba540daf6
18 changed files with 122 additions and 8 deletions
--- a/Help/command/project.rst
+++ b/Help/command/project.rst
@@ -12,6 +12,7 @@ Synopsis
 project(<PROJECT-NAME>
         [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
         [COMPAT_VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
+         [SPDX_LICENSE <license-string>]
         [DESCRIPTION <description-string>]
         [HOMEPAGE_URL <url-string>]
         [LANGUAGES <language-name>...])
@@ -106,6 +107,29 @@ The options are:
    ``CMakeLists.txt``, then the compatibility version is also stored in the
    variable :variable:`CMAKE_PROJECT_COMPAT_VERSION`.

+``SPDX_LICENSE <license-string>``
+  .. versionadded:: 4.2
+
+  Optional.
+  Sets the variables
+
+  * :variable:`PROJECT_SPDX_LICENSE`,
+    :variable:`<PROJECT-NAME>_SPDX_LICENSE`
+
+  to ``<license-string>``, which shall be a |SPDX|_ (SPDX)
+  `License Expression`_ that describes the license(s) of the project as a
+  whole, including documentation, resources, or other materials distributed
+  with the project, in addition to software artifacts. See the SPDX
+  `License List`_ for a list of commonly used licenses and their identifiers.
+  See the :prop_tgt:`SPDX_LICENSE` property for specifying the license(s) on
+  individual software artifacts.
+
+.. _SPDX: https://spdx.dev/
+.. |SPDX| replace:: System Package Data Exchange
+
+.. _License Expression: https://spdx.github.io/spdx-spec/v3.0.1/annexes/spdx-license-expressions/
+.. _License List: https://spdx.org/licenses/
+
 ``DESCRIPTION <description-string>``
  .. versionadded:: 3.9

--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -98,15 +98,16 @@ Variables that Provide Information
   /variable/CMAKE_OBJDUMP
   /variable/CMAKE_PARENT_LIST_FILE
   /variable/CMAKE_PATCH_VERSION
+   /variable/CMAKE_PROJECT_COMPAT_VERSION
   /variable/CMAKE_PROJECT_DESCRIPTION
   /variable/CMAKE_PROJECT_HOMEPAGE_URL
   /variable/CMAKE_PROJECT_NAME
+   /variable/CMAKE_PROJECT_SPDX_LICENSE
   /variable/CMAKE_PROJECT_VERSION
   /variable/CMAKE_PROJECT_VERSION_MAJOR
   /variable/CMAKE_PROJECT_VERSION_MINOR
   /variable/CMAKE_PROJECT_VERSION_PATCH
   /variable/CMAKE_PROJECT_VERSION_TWEAK
-   /variable/CMAKE_PROJECT_COMPAT_VERSION
   /variable/CMAKE_RANLIB
   /variable/CMAKE_ROOT
   /variable/CMAKE_RULE_MESSAGES
@@ -154,28 +155,30 @@ Variables that Provide Information
   /variable/CMAKE_XCODE_BUILD_SYSTEM
   /variable/CMAKE_XCODE_PLATFORM_TOOLSET
   /variable/PROJECT-NAME_BINARY_DIR
+   /variable/PROJECT-NAME_COMPAT_VERSION
   /variable/PROJECT-NAME_DESCRIPTION
   /variable/PROJECT-NAME_HOMEPAGE_URL
   /variable/PROJECT-NAME_IS_TOP_LEVEL
   /variable/PROJECT-NAME_SOURCE_DIR
+   /variable/PROJECT-NAME_SPDX_LICENSE
   /variable/PROJECT-NAME_VERSION
   /variable/PROJECT-NAME_VERSION_MAJOR
   /variable/PROJECT-NAME_VERSION_MINOR
   /variable/PROJECT-NAME_VERSION_PATCH
   /variable/PROJECT-NAME_VERSION_TWEAK
-   /variable/PROJECT-NAME_COMPAT_VERSION
   /variable/PROJECT_BINARY_DIR
+   /variable/PROJECT_COMPAT_VERSION
   /variable/PROJECT_DESCRIPTION
   /variable/PROJECT_HOMEPAGE_URL
   /variable/PROJECT_IS_TOP_LEVEL
   /variable/PROJECT_NAME
   /variable/PROJECT_SOURCE_DIR
+   /variable/PROJECT_SPDX_LICENSE
   /variable/PROJECT_VERSION
   /variable/PROJECT_VERSION_MAJOR
   /variable/PROJECT_VERSION_MINOR
   /variable/PROJECT_VERSION_PATCH
   /variable/PROJECT_VERSION_TWEAK
-   /variable/PROJECT_COMPAT_VERSION

 Variables that Change Behavior
 ==============================
--- a/Help/prop_tgt/SPDX_LICENSE.rst
+++ b/Help/prop_tgt/SPDX_LICENSE.rst
@@ -3,9 +3,9 @@ SPDX_LICENSE

 .. versionadded:: 4.1

-Specify the license of a target using a |SPDX|_ (SPDX) `License Expression`_.
-See the SPDX `License List`_ for a list of commonly used licenses and their
-identifiers.
+Specify the license(s) of a target using a |SPDX|_ (SPDX)
+`License Expression`_. See the SPDX `License List`_ for a list of commonly used
+licenses and their identifiers.

 .. _SPDX: https://spdx.dev/
 .. |SPDX| replace:: System Package Data Exchange
--- a/Help/variable/CMAKE_PROJECT_SPDX_LICENSE.rst
+++ b/Help/variable/CMAKE_PROJECT_SPDX_LICENSE.rst
@@ -0,0 +1,41 @@
+CMAKE_PROJECT_SPDX_LICENSE
+--------------------------
+
+.. versionadded:: 4.2
+
+.. note::
+
+  Experimental. Gated by ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_INFO``.
+
+The license(s) of the top level project.
+
+This variable holds the license expression of the project as specified in the
+top level CMakeLists.txt file by a :command:`project` command.  In the event
+that the top level CMakeLists.txt contains multiple :command:`project` calls,
+the most recently called one from that top level CMakeLists.txt will determine
+the value that ``CMAKE_PROJECT_SPDX_LICENSE`` contains.  For example, consider
+the following top level CMakeLists.txt:
+
+.. code-block:: cmake
+
+  cmake_minimum_required(VERSION 4.2)
+  project(First SPDX_LICENSE "BSD-3-Clause")
+  project(Second SPDX_LICENSE "BSD-3-Clause AND CC-BY-SA-4.0")
+  add_subdirectory(sub)
+  project(Third SPDX_LICENSE "BSD-3-Clause AND CC0-1.0")
+
+And ``sub/CMakeLists.txt`` with the following contents:
+
+.. code-block:: cmake
+
+  project(SubProj SPDX_LICENSE Apache-2.0)
+  message("CMAKE_PROJECT_SPDX_LICENSE = ${CMAKE_PROJECT_SPDX_LICENSE}")
+
+The most recently seen :command:`project` command from the top level
+CMakeLists.txt would be ``project(Second ...)``, so this will print::
+
+  CMAKE_PROJECT_SPDX_LICENSE = BSD-3-Clause AND CC-BY-SA-4.0
+
+To obtain the version from the most recent call to :command:`project` in
+the current directory scope or above, see the :variable:`PROJECT_SPDX_LICENSE`
+variable.
--- a/Help/variable/PROJECT-NAME_SPDX_LICENSE.rst
+++ b/Help/variable/PROJECT-NAME_SPDX_LICENSE.rst
@@ -0,0 +1,11 @@
+<PROJECT-NAME>_SPDX_LICENSE
+---------------------------
+
+.. versionadded:: 4.2
+
+.. note::
+
+  Experimental. Gated by ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_INFO``.
+
+Value given to the ``SPDX_LICENSE`` option of the most recent call to the
+:command:`project` command with project name ``<PROJECT-NAME>``, if any.
--- a/Help/variable/PROJECT_SPDX_LICENSE.rst
+++ b/Help/variable/PROJECT_SPDX_LICENSE.rst
@@ -0,0 +1,12 @@
+PROJECT_SPDX_LICENSE
+--------------------
+
+.. versionadded:: 4.2
+
+.. note::
+
+  Experimental. Gated by ``CMAKE_EXPERIMENTAL_EXPORT_PACKAGE_INFO``.
+
+Value given to the ``SPDX_LICENSE`` option of the most recent call to the
+:command:`project` command, if any. To obtain the compatibility version of the
+top level project, see the :variable:`CMAKE_PROJECT_SPDX_LICENSE` variable.
--- a/Source/cmProjectCommand.cxx
+++ b/Source/cmProjectCommand.cxx
@@ -38,6 +38,7 @@ struct ProjectArguments : ArgumentParser::ParseResult
  cm::optional<std::string> ProjectName;
  cm::optional<std::string> Version;
  cm::optional<std::string> CompatVersion;
+  cm::optional<std::string> License;
  cm::optional<std::string> Description;
  cm::optional<std::string> HomepageURL;
  cm::optional<ArgumentParser::MaybeEmpty<std::vector<std::string>>> Languages;
@@ -73,11 +74,12 @@ bool cmProjectCommand(std::vector<std::string> const& args,
    .Bind("LANGUAGES"_s, prArgs.Languages);

  cmMakefile& mf = status.GetMakefile();
-  bool enableCompatVersion = cmExperimental::HasSupportEnabled(
+  bool enablePackageInfo = cmExperimental::HasSupportEnabled(
    mf, cmExperimental::Feature::ExportPackageInfo);

-  if (enableCompatVersion) {
+  if (enablePackageInfo) {
    parser.Bind("COMPAT_VERSION"_s, prArgs.CompatVersion);
+    parser.Bind("SPDX_LICENSE"_s, prArgs.License);
  }

  parser.Parse(args, &unparsedArgs, 0);
@@ -263,6 +265,7 @@ bool cmProjectCommand(std::vector<std::string> const& args,
  createVariables("VERSION_PATCH"_s, version_components[2]);
  createVariables("VERSION_TWEAK"_s, version_components[3]);
  createVariables("COMPAT_VERSION"_s, prArgs.CompatVersion.value_or(""));
+  createVariables("SPDX_LICENSE"_s, prArgs.License.value_or(""));
  createVariables("DESCRIPTION"_s, prArgs.Description.value_or(""));
  createVariables("HOMEPAGE_URL"_s, prArgs.HomepageURL.value_or(""));

--- a/Tests/RunCMake/project/Omissions.cmake
+++ b/Tests/RunCMake/project/Omissions.cmake
@@ -20,5 +20,6 @@ expect_empty(VERSION_MINOR)
 expect_empty(VERSION_PATCH)
 expect_empty(VERSION_TWEAK)
 expect_empty(COMPAT_VERSION)
+expect_empty(SPDX_LICENSE)
 expect_empty(DESCRIPTION)
 expect_empty(HOMEPAGE_URL)
--- a/Tests/RunCMake/project/ProjectLicense-stdout.txt
+++ b/Tests/RunCMake/project/ProjectLicense-stdout.txt
@@ -0,0 +1 @@
+PROJECT_SPDX_LICENSE=BSD-3-Clause
--- a/Tests/RunCMake/project/ProjectLicense.cmake
+++ b/Tests/RunCMake/project/ProjectLicense.cmake
@@ -0,0 +1,5 @@
+project(ProjectLicenseTest SPDX_LICENSE "BSD-3-Clause" LANGUAGES)
+if(NOT PROJECT_SPDX_LICENSE)
+  message(FATAL_ERROR "PROJECT_SPDX_LICENSE expected to be set")
+endif()
+message(STATUS "PROJECT_SPDX_LICENSE=${PROJECT_SPDX_LICENSE}")
--- a/Tests/RunCMake/project/ProjectLicense2-result.txt
+++ b/Tests/RunCMake/project/ProjectLicense2-result.txt
@@ -0,0 +1 @@
+1
--- a/Tests/RunCMake/project/ProjectLicense2-stderr.txt
+++ b/Tests/RunCMake/project/ProjectLicense2-stderr.txt
@@ -0,0 +1 @@
+  SPDX_LICENSE may be specified at most once.
--- a/Tests/RunCMake/project/ProjectLicense2.cmake
+++ b/Tests/RunCMake/project/ProjectLicense2.cmake
@@ -0,0 +1 @@
+project(ProjectLicenseTest SPDX_LICENSE "BSD-3-Clause" SPDX_LICENSE "Apache-2.0" LANGUAGES)
--- a/Tests/RunCMake/project/ProjectLicenseNoArg-stderr.txt
+++ b/Tests/RunCMake/project/ProjectLicenseNoArg-stderr.txt
@@ -0,0 +1,2 @@
+  SPDX_LICENSE keyword not followed by a value or was followed by a value
+  that expanded to nothing.
--- a/Tests/RunCMake/project/ProjectLicenseNoArg.cmake
+++ b/Tests/RunCMake/project/ProjectLicenseNoArg.cmake
@@ -0,0 +1 @@
+project(ProjectLicenseTest LANGUAGES NONE SPDX_LICENSE)
--- a/Tests/RunCMake/project/ProjectLicenseNoArg2-stderr.txt
+++ b/Tests/RunCMake/project/ProjectLicenseNoArg2-stderr.txt
@@ -0,0 +1,2 @@
+  SPDX_LICENSE keyword not followed by a value or was followed by a value
+  that expanded to nothing.
--- a/Tests/RunCMake/project/ProjectLicenseNoArg2.cmake
+++ b/Tests/RunCMake/project/ProjectLicenseNoArg2.cmake
@@ -0,0 +1 @@
+project(ProjectLicenseTest SPDX_LICENSE LANGUAGES NONE)
--- a/Tests/RunCMake/project/RunCMakeTest.cmake
+++ b/Tests/RunCMake/project/RunCMakeTest.cmake
@@ -66,6 +66,10 @@ run_cmake_with_options(ProjectCompatVersionInvalid ${opts})
 run_cmake_with_options(ProjectCompatVersionMissingVersion ${opts})
 run_cmake_with_options(ProjectCompatVersionNewer ${opts})
 run_cmake_with_options(ProjectCompatVersionNoArg ${opts})
+run_cmake_with_options(ProjectLicense ${opts})
+run_cmake_with_options(ProjectLicense2 ${opts})
+run_cmake_with_options(ProjectLicenseNoArg ${opts})
+run_cmake_with_options(ProjectLicenseNoArg2 ${opts})

 run_cmake(CMP0048-NEW)
				`@@ -0,0 +1 @@`
				`SPDX_LICENSE may be specified at most once.`
				`@@ -0,0 +1 @@`
				`project(ProjectLicenseTest SPDX_LICENSE "BSD-3-Clause" SPDX_LICENSE "Apache-2.0" LANGUAGES)`
				`@@ -0,0 +1 @@`
				`project(ProjectLicenseTest LANGUAGES NONE SPDX_LICENSE)`