CPS: Support additional metadata

Add support for specifying CPS's supplemental `description` and `website` attributes. Add ability to inherit these from the `project()`, similar to how version information can be inherited.
2025-10-20 04:24:36 +08:00 · 2025-06-03 16:24:13 -04:00
parent f224e131a5
commit da97747dac
18 changed files with 89 additions and 6 deletions
--- a/Help/command/export.rst
+++ b/Help/command/export.rst
@@ -140,7 +140,9 @@ Exporting Targets to the |CPS|
          [COMPAT_VERSION <version>]
          [VERSION_SCHEMA <string>]]
         [DEFAULT_TARGETS <target>...]
-         [DEFAULT_CONFIGURATIONS <config>...])
+         [DEFAULT_CONFIGURATIONS <config>...]
+         [DESCRIPTION <project-description-string>]
+         [HOMEPAGE_URL <url-string>])

 .. versionadded:: 4.1
 .. note::
--- a/Help/command/install.rst
+++ b/Help/command/install.rst
@@ -1001,6 +1001,8 @@ Signatures
             [VERSION_SCHEMA <string>]]
            [DEFAULT_TARGETS <target>...]
            [DEFAULT_CONFIGURATIONS <config>...]
+            [DESCRIPTION <project-description-string>]
+            [HOMEPAGE_URL <url-string>]
            [PERMISSIONS <permission>...]
            [CONFIGURATIONS <config>...]
            [COMPONENT <component>]
@@ -1057,6 +1059,17 @@ Signatures
    configurations exists.  If not specified, CMake will fall back to the
    package's available configurations in an unspecified order.

+  ``DESCRIPTION <project-description-string>``
+    .. versionadded:: 4.1
+
+    An informational description of the project.  It is recommended that this
+    description is a relatively short string, usually no more than a few words.
+
+  ``HOMEPAGE_URL <url-string>``
+    .. versionadded:: 4.1
+
+    An informational canonical home URL for the project.
+
  By default, if the specified ``<package-name>`` matches the current CMake
  :variable:`PROJECT_NAME`, package metadata will be inherited from the
  project.  The ``PROJECT <project-name>`` option may be used to specify a
--- a/Source/cmExportPackageInfoGenerator.cxx
+++ b/Source/cmExportPackageInfoGenerator.cxx
@@ -37,6 +37,8 @@ cmExportPackageInfoGenerator::cmExportPackageInfoGenerator(
  , PackageVersion(std::move(arguments.Version))
  , PackageVersionCompat(std::move(arguments.VersionCompat))
  , PackageVersionSchema(std::move(arguments.VersionSchema))
+  , PackageDescription(std::move(arguments.Description))
+  , PackageWebsite(std::move(arguments.Website))
  , DefaultTargets(std::move(arguments.DefaultTargets))
  , DefaultConfigurations(std::move(arguments.DefaultConfigs))
 {
@@ -123,7 +125,9 @@ Json::Value cmExportPackageInfoGenerator::GeneratePackageInfo() const
  BuildArray(package, "default_components", this->DefaultTargets);
  BuildArray(package, "configurations", this->DefaultConfigurations);

-  // TODO: description, website, license
+  SetProperty(package, "description", this->PackageDescription);
+  SetProperty(package, "website", this->PackageWebsite);
+  // TODO: license

  return package;
 }
--- a/Source/cmExportPackageInfoGenerator.h
+++ b/Source/cmExportPackageInfoGenerator.h
@@ -108,6 +108,8 @@ private:
  std::string const PackageVersion;
  std::string const PackageVersionCompat;
  std::string const PackageVersionSchema;
+  std::string const PackageDescription;
+  std::string const PackageWebsite;
  std::vector<std::string> DefaultTargets;
  std::vector<std::string> DefaultConfigurations;

--- a/Source/cmPackageInfoArguments.cxx
+++ b/Source/cmPackageInfoArguments.cxx
@@ -136,6 +136,14 @@ bool cmPackageInfoArguments::SetMetadataFromProject(cmExecutionStatus& status)
    }
  }

+  if (this->Description.empty()) {
+    mapProjectValue(this->Description, "DESCRIPTION"_s);
+  }
+
+  if (this->Website.empty()) {
+    mapProjectValue(this->Website, "HOMEPAGE_URL"_s);
+  }
+
  return true;
 }

--- a/Source/cmPackageInfoArguments.h
+++ b/Source/cmPackageInfoArguments.h
@@ -56,6 +56,8 @@ public:
  ArgumentParser::NonEmpty<std::string> Version;
  ArgumentParser::NonEmpty<std::string> VersionCompat;
  ArgumentParser::NonEmpty<std::string> VersionSchema;
+  ArgumentParser::NonEmpty<std::string> Description;
+  ArgumentParser::NonEmpty<std::string> Website;
  ArgumentParser::NonEmpty<std::vector<std::string>> DefaultTargets;
  ArgumentParser::NonEmpty<std::vector<std::string>> DefaultConfigs;
  bool LowerCase = false;
@@ -82,6 +84,8 @@ private:
         &cmPackageInfoArguments::DefaultTargets);
    Bind(self, parser, "DEFAULT_CONFIGURATIONS"_s,
         &cmPackageInfoArguments::DefaultConfigs);
+    Bind(self, parser, "DESCRIPTION"_s, &cmPackageInfoArguments::Description);
+    Bind(self, parser, "HOMEPAGE_URL"_s, &cmPackageInfoArguments::Website);

    Bind(self, parser, "PROJECT"_s, &cmPackageInfoArguments::ProjectName);
    Bind(self, parser, "NO_PROJECT_METADATA"_s,
--- a/Tests/RunCMake/ExportPackageInfo/Metadata-check.cmake
+++ b/Tests/RunCMake/ExportPackageInfo/Metadata-check.cmake
@@ -14,3 +14,6 @@ expect_value("${content}" "foo" "default_components" 0)
 expect_array("${content}" 2 "configurations")
 expect_value("${content}" "release" "configurations" 0)
 expect_value("${content}" "debug" "configurations" 1)
+
+expect_value("${content}" "Sample package" "description")
+expect_value("${content}" "https://www.example.com/package/foo" "website")
--- a/Tests/RunCMake/ExportPackageInfo/Metadata.cmake
+++ b/Tests/RunCMake/ExportPackageInfo/Metadata.cmake
@@ -8,4 +8,6 @@ export(
  COMPAT_VERSION 1.2.0
  DEFAULT_TARGETS foo
  DEFAULT_CONFIGURATIONS release debug
+  DESCRIPTION "Sample package"
+  HOMEPAGE_URL "https://www.example.com/package/foo"
  )
--- a/Tests/RunCMake/ExportPackageInfo/NoProjectMetadata-check.cmake
+++ b/Tests/RunCMake/ExportPackageInfo/NoProjectMetadata-check.cmake
@@ -6,3 +6,5 @@ file(READ "${out_dir}/foo.cps" content)
 expect_value("${content}" "foo" "name")
 expect_missing("${content}" "version")
 expect_missing("${content}" "compat_version")
+expect_missing("${content}" "description")
+expect_missing("${content}" "website")
--- a/Tests/RunCMake/ExportPackageInfo/NoProjectMetadata.cmake
+++ b/Tests/RunCMake/ExportPackageInfo/NoProjectMetadata.cmake
@@ -1,4 +1,9 @@
-project(foo VERSION 1.2.3 COMPAT_VERSION 1.1.0)
+project(foo
+  VERSION 1.2.3
+  COMPAT_VERSION 1.1.0
+  DESCRIPTION "Sample package"
+  HOMEPAGE_URL "https://www.example.com/package/foo"
+  )

 add_library(foo INTERFACE)
 install(TARGETS foo EXPORT foo DESTINATION .)
--- a/Tests/RunCMake/ExportPackageInfo/ProjectMetadata-check.cmake
+++ b/Tests/RunCMake/ExportPackageInfo/ProjectMetadata-check.cmake
@@ -6,13 +6,19 @@ file(READ "${out_dir}/foo.cps" content)
 expect_value("${content}" "foo" "name")
 expect_value("${content}" "1.2.3" "version")
 expect_value("${content}" "1.1.0" "compat_version")
+expect_value("${content}" "Sample package" "description")
+expect_value("${content}" "https://www.example.com/package/foo" "website")

 file(READ "${out_dir}/test1.cps" content)
 expect_value("${content}" "test1" "name")
 expect_value("${content}" "1.2.3" "version")
 expect_value("${content}" "1.1.0" "compat_version")
+expect_value("${content}" "Sample package" "description")
+expect_value("${content}" "https://www.example.com/package/foo" "website")

 file(READ "${out_dir}/test2.cps" content)
 expect_value("${content}" "test2" "name")
 expect_value("${content}" "1.4.7" "version")
 expect_missing("${content}" "compat_version")
+expect_value("${content}" "Don't inherit" "description")
+expect_value("${content}" "https://www.example.com/package/bar" "website")
--- a/Tests/RunCMake/ExportPackageInfo/ProjectMetadata.cmake
+++ b/Tests/RunCMake/ExportPackageInfo/ProjectMetadata.cmake
@@ -1,4 +1,9 @@
-project(foo VERSION 1.2.3 COMPAT_VERSION 1.1.0)
+project(foo
+  VERSION 1.2.3
+  COMPAT_VERSION 1.1.0
+  DESCRIPTION "Sample package"
+  HOMEPAGE_URL "https://www.example.com/package/foo"
+  )

 add_library(foo INTERFACE)
 install(TARGETS foo EXPORT foo DESTINATION .)
@@ -22,4 +27,6 @@ export(
  PROJECT foo
  PACKAGE_INFO test2
  VERSION 1.4.7
+  DESCRIPTION "Don't inherit"
+  HOMEPAGE_URL "https://www.example.com/package/bar"
  )
--- a/Tests/RunCMake/InstallPackageInfo/Metadata-check.cmake
+++ b/Tests/RunCMake/InstallPackageInfo/Metadata-check.cmake
@@ -14,3 +14,6 @@ expect_value("${content}" "foo" "default_components" 0)
 expect_array("${content}" 2 "configurations")
 expect_value("${content}" "release" "configurations" 0)
 expect_value("${content}" "debug" "configurations" 1)
+
+expect_value("${content}" "Sample package" "description")
+expect_value("${content}" "https://www.example.com/package/foo" "website")
--- a/Tests/RunCMake/InstallPackageInfo/Metadata.cmake
+++ b/Tests/RunCMake/InstallPackageInfo/Metadata.cmake
@@ -9,4 +9,6 @@ install(
  COMPAT_VERSION 1.2.0
  DEFAULT_TARGETS foo
  DEFAULT_CONFIGURATIONS release debug
+  DESCRIPTION "Sample package"
+  HOMEPAGE_URL "https://www.example.com/package/foo"
  )
--- a/Tests/RunCMake/InstallPackageInfo/NoProjectMetadata-check.cmake
+++ b/Tests/RunCMake/InstallPackageInfo/NoProjectMetadata-check.cmake
@@ -6,3 +6,5 @@ file(READ "${out_dir}/foo.cps" content)
 expect_value("${content}" "foo" "name")
 expect_missing("${content}" "version")
 expect_missing("${content}" "compat_version")
+expect_missing("${content}" "description")
+expect_missing("${content}" "website")
--- a/Tests/RunCMake/InstallPackageInfo/NoProjectMetadata.cmake
+++ b/Tests/RunCMake/InstallPackageInfo/NoProjectMetadata.cmake
@@ -1,4 +1,9 @@
-project(foo VERSION 1.2.3 COMPAT_VERSION 1.1.0)
+project(foo
+  VERSION 1.2.3
+  COMPAT_VERSION 1.1.0
+  DESCRIPTION "Sample package"
+  HOMEPAGE_URL "https://www.example.com/package/foo"
+  )

 add_library(foo INTERFACE)
 install(TARGETS foo EXPORT foo DESTINATION .)
--- a/Tests/RunCMake/InstallPackageInfo/ProjectMetadata-check.cmake
+++ b/Tests/RunCMake/InstallPackageInfo/ProjectMetadata-check.cmake
@@ -6,13 +6,19 @@ file(READ "${out_dir}/foo.cps" content)
 expect_value("${content}" "foo" "name")
 expect_value("${content}" "1.2.3" "version")
 expect_value("${content}" "1.1.0" "compat_version")
+expect_value("${content}" "Sample package" "description")
+expect_value("${content}" "https://www.example.com/package/foo" "website")

 file(READ "${out_dir}/test1.cps" content)
 expect_value("${content}" "test1" "name")
 expect_value("${content}" "1.2.3" "version")
 expect_value("${content}" "1.1.0" "compat_version")
+expect_value("${content}" "Sample package" "description")
+expect_value("${content}" "https://www.example.com/package/foo" "website")

 file(READ "${out_dir}/test2.cps" content)
 expect_value("${content}" "test2" "name")
 expect_value("${content}" "1.4.7" "version")
 expect_missing("${content}" "compat_version")
+expect_value("${content}" "Don't inherit" "description")
+expect_value("${content}" "https://www.example.com/package/bar" "website")
--- a/Tests/RunCMake/InstallPackageInfo/ProjectMetadata.cmake
+++ b/Tests/RunCMake/InstallPackageInfo/ProjectMetadata.cmake
@@ -1,4 +1,9 @@
-project(foo VERSION 1.2.3 COMPAT_VERSION 1.1.0)
+project(foo
+  VERSION 1.2.3
+  COMPAT_VERSION 1.1.0
+  DESCRIPTION "Sample package"
+  HOMEPAGE_URL "https://www.example.com/package/foo"
+  )

 add_library(foo INTERFACE)
 install(TARGETS foo EXPORT foo DESTINATION .)
@@ -25,4 +30,6 @@ install(
  EXPORT foo
  PROJECT foo
  VERSION 1.4.7
+  DESCRIPTION "Don't inherit"
+  HOMEPAGE_URL "https://www.example.com/package/bar"
  )