Merge topic 'project-homepage-url'

73f9b2974c project: Add HOMEPAGE_URL named parameter
fd28c382b4 project: Add <PROJECT-NAME>_DESCRIPTION
9b57cb62ea Help: Fix minor typo in docs for CMAKE_PROJECT_DESCRIPTION
c89993d529 Tests: Avoid enabling languages unnecessarily in RunCMake.project

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !1816

8 files changed, 83 insertions, 7 deletions

diff --git a/Help/command/project.rst b/Help/command/project.rst
index ac71d7a..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(<PROJECT-NAME>
          [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
          [DESCRIPTION <project-description-string>]
+         [HOMEPAGE_URL <url-string>]
          [LANGUAGES <language-name>...])
 
 Sets the name of the project and stores the name in the
@@ -41,9 +42,18 @@ in variables
 Variables corresponding to unspecified versions are set to the empty string
 (if policy :policy:`CMP0048` is set to ``NEW``).
 
-If optional ``DESCRIPTION`` is given, then additional :variable:`PROJECT_DESCRIPTION`
-variable will be set to its argument. The argument must be a string with short
-description of the project (only a few words).
+If the optional ``DESCRIPTION`` is given, then :variable:`PROJECT_DESCRIPTION`
+and :variable:`<PROJECT-NAME>_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:`<PROJECT-NAME>_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``,
@@ -64,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 13a72df..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
@@ -97,6 +98,8 @@ Variables that Provide Information
    /variable/CMAKE_XCODE_GENERATE_SCHEME
    /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
@@ -105,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:`<PROJECT-NAME>_HOMEPAGE_URL`
+  and :variable:`CMAKE_PROJECT_HOMEPAGE_URL`.
diff --git a/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst b/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst
index 6db5b9e..51b0592 100644
--- a/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst
+++ b/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst
@@ -7,7 +7,7 @@ This variable holds the description 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 name that ``CMAKE_PROJECT_DESCRIPTION`` contains.  For example, consider
+the value that ``CMAKE_PROJECT_DESCRIPTION`` contains.  For example, consider
 the following top level CMakeLists.txt:
 
 .. code-block:: cmake
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_DESCRIPTION.rst b/Help/variable/PROJECT-NAME_DESCRIPTION.rst
new file mode 100644
index 0000000..2b88b1a
--- /dev/null
+++ b/Help/variable/PROJECT-NAME_DESCRIPTION.rst
@@ -0,0 +1,5 @@
+<PROJECT-NAME>_DESCRIPTION
+--------------------------
+
+Value given to the ``DESCRIPTION`` option of the most recent call to the
+:command:`project` command with project name ``<PROJECT-NAME>``, if any.
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 @@
+<PROJECT-NAME>_HOMEPAGE_URL
+---------------------------
+
+Value given to the ``HOMEPAGE_URL`` option of the most recent call to the
+:command:`project` command with project name ``<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.