From 73f9b2974c80394564e6af5b808133cba48ccf34 Mon Sep 17 00:00:00 2001 From: Alex Turbov Date: Fri, 16 Mar 2018 07:29:31 +1100 Subject: project: Add HOMEPAGE_URL named parameter This sets variables like PROJECT_HOMEPAGE_URL, which can be used as default values for various things (packaging modules, doxygen defaults, etc.). Some packaging modules have been updated to do this as part of this commit. Co-Author: Craig Scott --- Help/command/project.rst | 16 ++++++-- Help/manual/cmake-variables.7.rst | 3 ++ Help/release/dev/project-homepage.rst | 7 ++++ Help/variable/CMAKE_PROJECT_HOMEPAGE_URL.rst | 35 ++++++++++++++++ Help/variable/PROJECT-NAME_HOMEPAGE_URL.rst | 5 +++ Help/variable/PROJECT_HOMEPAGE_URL.rst | 9 +++++ Modules/CPackDeb.cmake | 7 +++- Modules/CPackFreeBSD.cmake | 4 +- Modules/CPackRPM.cmake | 6 ++- Source/cmProjectCommand.cxx | 47 ++++++++++++++++++++-- Tests/RunCMake/project/ProjectHomepage-stdout.txt | 3 ++ Tests/RunCMake/project/ProjectHomepage.cmake | 14 +++++++ Tests/RunCMake/project/ProjectHomepage2-result.txt | 1 + Tests/RunCMake/project/ProjectHomepage2-stderr.txt | 4 ++ Tests/RunCMake/project/ProjectHomepage2.cmake | 2 + .../project/ProjectHomepageNoArg-stderr.txt | 5 +++ Tests/RunCMake/project/ProjectHomepageNoArg.cmake | 2 + Tests/RunCMake/project/RunCMakeTest.cmake | 3 ++ .../project/VersionMissingLanguages-stderr.txt | 4 +- 19 files changed, 166 insertions(+), 11 deletions(-) create mode 100644 Help/release/dev/project-homepage.rst create mode 100644 Help/variable/CMAKE_PROJECT_HOMEPAGE_URL.rst create mode 100644 Help/variable/PROJECT-NAME_HOMEPAGE_URL.rst create mode 100644 Help/variable/PROJECT_HOMEPAGE_URL.rst create mode 100644 Tests/RunCMake/project/ProjectHomepage-stdout.txt create mode 100644 Tests/RunCMake/project/ProjectHomepage.cmake create mode 100644 Tests/RunCMake/project/ProjectHomepage2-result.txt create mode 100644 Tests/RunCMake/project/ProjectHomepage2-stderr.txt create mode 100644 Tests/RunCMake/project/ProjectHomepage2.cmake create mode 100644 Tests/RunCMake/project/ProjectHomepageNoArg-stderr.txt create mode 100644 Tests/RunCMake/project/ProjectHomepageNoArg.cmake diff --git a/Help/command/project.rst b/Help/command/project.rst index 062e9ea..e46dd69 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -9,6 +9,7 @@ Sets project details such as name, version, etc. and enables languages. project( [VERSION [.[.[.]]]] [DESCRIPTION ] + [HOMEPAGE_URL ] [LANGUAGES ...]) Sets the name of the project and stores the name in the @@ -46,6 +47,14 @@ and :variable:`_DESCRIPTION` will be set to its argument. The description is expected to be a relatively short string, usually no more than a few words. +The optional ``HOMEPAGE_URL`` sets the analogous variables +:variable:`PROJECT_HOMEPAGE_URL` and :variable:`_HOMEPAGE_URL`. +When this option is given, the URL provided should be the canonical home for +the project. + +Note that the description and homepage URL may be used as defaults for +things like packaging meta-data, documentation, etc. + Optionally you can specify which languages your project supports. Example languages include ``C``, ``CXX`` (i.e. C++), ``CUDA``, ``Fortran``, and ``ASM``. @@ -65,9 +74,10 @@ literal, direct call to the :command:`project` command; loading one through the :command:`include` command is not sufficient. If no such call exists CMake will implicitly add one to the top that enables the default languages (``C`` and ``CXX``). The name of the project set in -the top level CMakeLists.txt file is available from the -:variable:`CMAKE_PROJECT_NAME` variable and its description from -:variable:`CMAKE_PROJECT_DESCRIPTION`. +the top level ``CMakeLists.txt`` file is available from the +:variable:`CMAKE_PROJECT_NAME` variable, its description from +:variable:`CMAKE_PROJECT_DESCRIPTION` and its homepage URL from +:variable:`CMAKE_PROJECT_HOMEPAGE_URL`. .. note:: Call the :command:`cmake_minimum_required` command at the beginning diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 2bf8c9c..0cb90d4 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -67,6 +67,7 @@ Variables that Provide Information /variable/CMAKE_PARENT_LIST_FILE /variable/CMAKE_PATCH_VERSION /variable/CMAKE_PROJECT_DESCRIPTION + /variable/CMAKE_PROJECT_HOMEPAGE_URL /variable/CMAKE_PROJECT_NAME /variable/CMAKE_RANLIB /variable/CMAKE_ROOT @@ -98,6 +99,7 @@ Variables that Provide Information /variable/CMAKE_XCODE_PLATFORM_TOOLSET /variable/PROJECT-NAME_BINARY_DIR /variable/PROJECT-NAME_DESCRIPTION + /variable/PROJECT-NAME_HOMEPAGE_URL /variable/PROJECT-NAME_SOURCE_DIR /variable/PROJECT-NAME_VERSION /variable/PROJECT-NAME_VERSION_MAJOR @@ -106,6 +108,7 @@ Variables that Provide Information /variable/PROJECT-NAME_VERSION_TWEAK /variable/PROJECT_BINARY_DIR /variable/PROJECT_DESCRIPTION + /variable/PROJECT_HOMEPAGE_URL /variable/PROJECT_NAME /variable/PROJECT_SOURCE_DIR /variable/PROJECT_VERSION diff --git a/Help/release/dev/project-homepage.rst b/Help/release/dev/project-homepage.rst new file mode 100644 index 0000000..25799a4 --- /dev/null +++ b/Help/release/dev/project-homepage.rst @@ -0,0 +1,7 @@ +project-homepage +---------------- + +* The :command:`project` command learned an optional ``HOMEPAGE_URL`` + parameter which has the effect of setting variables like + :variable:`PROJECT_HOMEPAGE_URL`, :variable:`_HOMEPAGE_URL` + and :variable:`CMAKE_PROJECT_HOMEPAGE_URL`. diff --git a/Help/variable/CMAKE_PROJECT_HOMEPAGE_URL.rst b/Help/variable/CMAKE_PROJECT_HOMEPAGE_URL.rst new file mode 100644 index 0000000..ee0bf7c --- /dev/null +++ b/Help/variable/CMAKE_PROJECT_HOMEPAGE_URL.rst @@ -0,0 +1,35 @@ +CMAKE_PROJECT_HOMEPAGE_URL +-------------------------- + +The homepage URL of the top level project. + +This variable holds the homepage URL 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_HOMEPAGE_URL`` contains. For example, consider +the following top level CMakeLists.txt: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.0) + project(First HOMEPAGE_URL "http://first.example.com") + project(Second HOMEPAGE_URL "http://second.example.com") + add_subdirectory(sub) + project(Third HOMEPAGE_URL "http://third.example.com") + +And ``sub/CMakeLists.txt`` with the following contents: + +.. code-block:: cmake + + project(SubProj HOMEPAGE_URL "http://subproj.example.com") + message("CMAKE_PROJECT_HOMEPAGE_URL = ${CMAKE_PROJECT_HOMEPAGE_URL}") + +The most recently seen :command:`project` command from the top level +CMakeLists.txt would be ``project(Second ...)``, so this will print:: + + CMAKE_PROJECT_HOMEPAGE_URL = http://second.example.com + +To obtain the homepage URL from the most recent call to :command:`project` in +the current directory scope or above, see the :variable:`PROJECT_HOMEPAGE_URL` +variable. diff --git a/Help/variable/PROJECT-NAME_HOMEPAGE_URL.rst b/Help/variable/PROJECT-NAME_HOMEPAGE_URL.rst new file mode 100644 index 0000000..22cc304 --- /dev/null +++ b/Help/variable/PROJECT-NAME_HOMEPAGE_URL.rst @@ -0,0 +1,5 @@ +_HOMEPAGE_URL +--------------------------- + +Value given to the ``HOMEPAGE_URL`` option of the most recent call to the +:command:`project` command with project name ````, if any. diff --git a/Help/variable/PROJECT_HOMEPAGE_URL.rst b/Help/variable/PROJECT_HOMEPAGE_URL.rst new file mode 100644 index 0000000..754c9e8 --- /dev/null +++ b/Help/variable/PROJECT_HOMEPAGE_URL.rst @@ -0,0 +1,9 @@ +PROJECT_HOMEPAGE_URL +-------------------- + +The homepage URL of the project. + +This is the homepage URL given to the most recently called :command:`project` +command in the current directory scope or above. To obtain the homepage URL +of the top level project, see the :variable:`CMAKE_PROJECT_HOMEPAGE_URL` +variable. diff --git a/Modules/CPackDeb.cmake b/Modules/CPackDeb.cmake index 35447c9..444f632 100644 --- a/Modules/CPackDeb.cmake +++ b/Modules/CPackDeb.cmake @@ -254,7 +254,7 @@ # upstream documentation or information may be found. # # * Mandatory : NO -# * Default : - +# * Default : :variable:`CMAKE_PROJECT_HOMEPAGE_URL` # # .. note:: # @@ -914,6 +914,11 @@ function(cpack_deb_prepare_package_vars) endif() endif() + # Homepage: (optional) + if(NOT CPACK_DEBIAN_PACKAGE_HOMEPAGE AND CMAKE_PROJECT_HOMEPAGE_URL) + set(CPACK_DEBIAN_PACKAGE_HOMEPAGE "${CMAKE_PROJECT_HOMEPAGE_URL}") + endif() + # Section: (recommended) if(NOT CPACK_DEBIAN_PACKAGE_SECTION) set(CPACK_DEBIAN_PACKAGE_SECTION "devel") diff --git a/Modules/CPackFreeBSD.cmake b/Modules/CPackFreeBSD.cmake index 7fec78a..b681d4f 100644 --- a/Modules/CPackFreeBSD.cmake +++ b/Modules/CPackFreeBSD.cmake @@ -80,7 +80,8 @@ the RPM information (e.g. package license). * Mandatory: YES * Default: - - :variable:`CPACK_DEBIAN_PACKAGE_HOMEPAGE` (this may be set already + - :variable:`CMAKE_PROJECT_HOMEPAGE_URL`, or if that is not set, + :variable:`CPACK_DEBIAN_PACKAGE_HOMEPAGE` (this may be set already for Debian packaging, so we may as well re-use it). .. variable:: CPACK_FREEBSD_PACKAGE_LICENSE @@ -208,6 +209,7 @@ _cpack_freebsd_fallback_var("CPACK_FREEBSD_PACKAGE_DESCRIPTION" # There's really only one homepage for a project, so # re-use the Debian setting if it's there. _cpack_freebsd_fallback_var("CPACK_FREEBSD_PACKAGE_WWW" + "CMAKE_PROJECT_HOMEPAGE_URL" "CPACK_DEBIAN_PACKAGE_HOMEPAGE" "_cpack_freebsd_fallback_www" ) diff --git a/Modules/CPackRPM.cmake b/Modules/CPackRPM.cmake index 258922c..87385de 100644 --- a/Modules/CPackRPM.cmake +++ b/Modules/CPackRPM.cmake @@ -191,7 +191,7 @@ # The projects URL. # # * Mandatory : NO -# * Default : - +# * Default : :variable:`CMAKE_PROJECT_HOMEPAGE_URL` # # .. variable:: CPACK_RPM_PACKAGE_DESCRIPTION # CPACK_RPM__PACKAGE_DESCRIPTION @@ -1787,6 +1787,10 @@ function(cpack_rpm_generate_package) endif() endif() + if(NOT CPACK_RPM_PACKAGE_URL AND CMAKE_PROJECT_HOMEPAGE_URL) + set(CPACK_RPM_PACKAGE_URL "${CMAKE_PROJECT_HOMEPAGE_URL}") + endif() + # CPACK_RPM_PACKAGE_NAME (mandatory) if(NOT CPACK_RPM_PACKAGE_NAME) string(TOLOWER "${CPACK_PACKAGE_NAME}" CPACK_RPM_PACKAGE_NAME) diff --git a/Source/cmProjectCommand.cxx b/Source/cmProjectCommand.cxx index 3470648..6ddb0b8 100644 --- a/Source/cmProjectCommand.cxx +++ b/Source/cmProjectCommand.cxx @@ -68,8 +68,10 @@ bool cmProjectCommand::InitialPass(std::vector const& args, bool haveVersion = false; bool haveLanguages = false; bool haveDescription = false; + bool haveHomepage = false; std::string version; std::string description; + std::string homepage; std::vector languages; std::function missedValueReporter; auto resetReporter = [&missedValueReporter]() { @@ -78,6 +80,7 @@ bool cmProjectCommand::InitialPass(std::vector const& args, enum Doing { DoingDescription, + DoingHomepage, DoingLanguages, DoingVersion }; @@ -141,6 +144,22 @@ bool cmProjectCommand::InitialPass(std::vector const& args, "by a value that expanded to nothing."); resetReporter(); }; + } else if (args[i] == "HOMEPAGE_URL") { + if (haveHomepage) { + this->Makefile->IssueMessage( + cmake::FATAL_ERROR, "HOMEPAGE_URL may be specified at most once."); + cmSystemTools::SetFatalErrorOccured(); + return true; + } + haveHomepage = true; + doing = DoingHomepage; + missedValueReporter = [this, &resetReporter]() { + this->Makefile->IssueMessage( + cmake::WARNING, + "HOMEPAGE_URL keyword not followed by a value or was followed " + "by a value that expanded to nothing."); + resetReporter(); + }; } else if (doing == DoingVersion) { doing = DoingLanguages; version = args[i]; @@ -149,6 +168,10 @@ bool cmProjectCommand::InitialPass(std::vector const& args, doing = DoingLanguages; description = args[i]; resetReporter(); + } else if (doing == DoingHomepage) { + doing = DoingLanguages; + homepage = args[i]; + resetReporter(); } else // doing == DoingLanguages { languages.push_back(args[i]); @@ -159,12 +182,12 @@ bool cmProjectCommand::InitialPass(std::vector const& args, missedValueReporter(); } - if ((haveVersion || haveDescription) && !haveLanguages && + if ((haveVersion || haveDescription || haveHomepage) && !haveLanguages && !languages.empty()) { this->Makefile->IssueMessage( cmake::FATAL_ERROR, - "project with VERSION or DESCRIPTION must use LANGUAGES before " - "language names."); + "project with VERSION, DESCRIPTION or HOMEPAGE_URL must " + "use LANGUAGES before language names."); cmSystemTools::SetFatalErrorOccured(); return true; } @@ -277,6 +300,24 @@ bool cmProjectCommand::InitialPass(std::vector const& args, } } + if (haveHomepage) { + this->Makefile->AddDefinition("PROJECT_HOMEPAGE_URL", homepage.c_str()); + this->Makefile->AddDefinition(projectName + "_HOMEPAGE_URL", + homepage.c_str()); + // Set the CMAKE_PROJECT_HOMEPAGE_URL variable to be the highest-level + // project name in the tree. If there are two project commands + // in the same CMakeLists.txt file, and it is the top level + // CMakeLists.txt file, then go with the last one. + if (!this->Makefile->GetDefinition("CMAKE_PROJECT_HOMEPAGE_URL") || + (this->Makefile->IsRootMakefile())) { + this->Makefile->AddDefinition("CMAKE_PROJECT_HOMEPAGE_URL", + homepage.c_str()); + this->Makefile->AddCacheDefinition( + "CMAKE_PROJECT_HOMEPAGE_URL", homepage.c_str(), + "Value Computed by CMake", cmStateEnums::STATIC); + } + } + if (languages.empty()) { // if no language is specified do c and c++ languages.push_back("C"); diff --git a/Tests/RunCMake/project/ProjectHomepage-stdout.txt b/Tests/RunCMake/project/ProjectHomepage-stdout.txt new file mode 100644 index 0000000..253990f --- /dev/null +++ b/Tests/RunCMake/project/ProjectHomepage-stdout.txt @@ -0,0 +1,3 @@ +-- PROJECT_HOMEPAGE_URL=http://example.com +-- CMAKE_PROJECT_HOMEPAGE_URL=http://example.com +-- ProjectHomepageTest_HOMEPAGE_URL=http://example.com diff --git a/Tests/RunCMake/project/ProjectHomepage.cmake b/Tests/RunCMake/project/ProjectHomepage.cmake new file mode 100644 index 0000000..3307f1f --- /dev/null +++ b/Tests/RunCMake/project/ProjectHomepage.cmake @@ -0,0 +1,14 @@ +cmake_policy(SET CMP0048 NEW) +project(ProjectHomepageTest VERSION 1.0.0 HOMEPAGE_URL "http://example.com" LANGUAGES) +if(NOT PROJECT_HOMEPAGE_URL) + message(FATAL_ERROR "PROJECT_HOMEPAGE_URL expected to be set") +endif() +if(NOT CMAKE_PROJECT_HOMEPAGE_URL) + message(FATAL_ERROR "CMAKE_PROJECT_HOMEPAGE_URL expected to be set") +endif() +if(NOT ProjectHomepageTest_HOMEPAGE_URL) + message(FATAL_ERROR "ProjectHomepageTest_HOMEPAGE_URL expected to be set") +endif() +message(STATUS "PROJECT_HOMEPAGE_URL=${PROJECT_HOMEPAGE_URL}") +message(STATUS "CMAKE_PROJECT_HOMEPAGE_URL=${CMAKE_PROJECT_HOMEPAGE_URL}") +message(STATUS "ProjectHomepageTest_HOMEPAGE_URL=${ProjectHomepageTest_HOMEPAGE_URL}") diff --git a/Tests/RunCMake/project/ProjectHomepage2-result.txt b/Tests/RunCMake/project/ProjectHomepage2-result.txt new file mode 100644 index 0000000..d00491f --- /dev/null +++ b/Tests/RunCMake/project/ProjectHomepage2-result.txt @@ -0,0 +1 @@ +1 diff --git a/Tests/RunCMake/project/ProjectHomepage2-stderr.txt b/Tests/RunCMake/project/ProjectHomepage2-stderr.txt new file mode 100644 index 0000000..4a0adc2 --- /dev/null +++ b/Tests/RunCMake/project/ProjectHomepage2-stderr.txt @@ -0,0 +1,4 @@ +^CMake Error at ProjectHomepage2.cmake:2 \(project\): + HOMEPAGE_URL may be specified at most once. +Call Stack \(most recent call first\): + CMakeLists.txt:[0-9]+ \(include\)$ diff --git a/Tests/RunCMake/project/ProjectHomepage2.cmake b/Tests/RunCMake/project/ProjectHomepage2.cmake new file mode 100644 index 0000000..184c392 --- /dev/null +++ b/Tests/RunCMake/project/ProjectHomepage2.cmake @@ -0,0 +1,2 @@ +cmake_policy(SET CMP0048 NEW) +project(ProjectDescriptionTest VERSION 1.0.0 HOMEPAGE_URL "http://example.com" HOMEPAGE_URL "http://example.com" LANGUAGES) diff --git a/Tests/RunCMake/project/ProjectHomepageNoArg-stderr.txt b/Tests/RunCMake/project/ProjectHomepageNoArg-stderr.txt new file mode 100644 index 0000000..c9503b7 --- /dev/null +++ b/Tests/RunCMake/project/ProjectHomepageNoArg-stderr.txt @@ -0,0 +1,5 @@ +^CMake Warning at ProjectHomepageNoArg.cmake:2 \(project\): + HOMEPAGE_URL keyword not followed by a value or was followed by a value + that expanded to nothing. +Call Stack \(most recent call first\): + CMakeLists.txt:[0-9]+ \(include\)$ diff --git a/Tests/RunCMake/project/ProjectHomepageNoArg.cmake b/Tests/RunCMake/project/ProjectHomepageNoArg.cmake new file mode 100644 index 0000000..4605541 --- /dev/null +++ b/Tests/RunCMake/project/ProjectHomepageNoArg.cmake @@ -0,0 +1,2 @@ +cmake_policy(SET CMP0048 NEW) +project(ProjectDescriptionTest VERSION 1.0.0 LANGUAGES NONE HOMEPAGE_URL) diff --git a/Tests/RunCMake/project/RunCMakeTest.cmake b/Tests/RunCMake/project/RunCMakeTest.cmake index f77c15d..e9fb929 100644 --- a/Tests/RunCMake/project/RunCMakeTest.cmake +++ b/Tests/RunCMake/project/RunCMakeTest.cmake @@ -12,6 +12,9 @@ run_cmake(ProjectDescription) run_cmake(ProjectDescription2) run_cmake(ProjectDescriptionNoArg) run_cmake(ProjectDescriptionNoArg2) +run_cmake(ProjectHomepage) +run_cmake(ProjectHomepage2) +run_cmake(ProjectHomepageNoArg) run_cmake(VersionAndLanguagesEmpty) run_cmake(VersionEmpty) run_cmake(VersionInvalid) diff --git a/Tests/RunCMake/project/VersionMissingLanguages-stderr.txt b/Tests/RunCMake/project/VersionMissingLanguages-stderr.txt index 1139df7..576ac69 100644 --- a/Tests/RunCMake/project/VersionMissingLanguages-stderr.txt +++ b/Tests/RunCMake/project/VersionMissingLanguages-stderr.txt @@ -1,5 +1,5 @@ CMake Error at VersionMissingLanguages.cmake:2 \(project\): - project with VERSION or DESCRIPTION must use LANGUAGES before language - names. + project with VERSION, DESCRIPTION or HOMEPAGE_URL must use LANGUAGES before + language names. Call Stack \(most recent call first\): CMakeLists.txt:3 \(include\)$ -- cgit v0.12