Merge topic 'feature/cpack-default-package-version'

af1c48871c CPack: Use project version as default for `CPACK_PACKAGE_VERSION`

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Harry Mallon <hjmallon@gmail.com>
Merge-request: !2020

8 files changed, 89 insertions, 2 deletions

diff --git a/Help/command/project.rst b/Help/command/project.rst
index e46dd69..c1de057 100644
--- a/Help/command/project.rst
+++ b/Help/command/project.rst
@@ -76,8 +76,9 @@ 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, its description from
-:variable:`CMAKE_PROJECT_DESCRIPTION` and its homepage URL from
-:variable:`CMAKE_PROJECT_HOMEPAGE_URL`.
+:variable:`CMAKE_PROJECT_DESCRIPTION`, its homepage URL from
+:variable:`CMAKE_PROJECT_HOMEPAGE_URL` and its version from
+:variable:`CMAKE_PROJECT_VERSION`.
 
 .. 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 44271c1..7636305 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -69,6 +69,11 @@ Variables that Provide Information
    /variable/CMAKE_PROJECT_DESCRIPTION
    /variable/CMAKE_PROJECT_HOMEPAGE_URL
    /variable/CMAKE_PROJECT_NAME
+   /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_RANLIB
    /variable/CMAKE_ROOT
    /variable/CMAKE_SCRIPT_MODE_FILE
diff --git a/Help/release/dev/cpack-use-project-version.rst b/Help/release/dev/cpack-use-project-version.rst
new file mode 100644
index 0000000..b17754a
--- /dev/null
+++ b/Help/release/dev/cpack-use-project-version.rst
@@ -0,0 +1,10 @@
+cpack-use-project-version
+-------------------------
+
+* Introduce :variable:`CMAKE_PROJECT_VERSION` and the corresponding components:
+  :variable:`CMAKE_PROJECT_VERSION_MAJOR`, :variable:`CMAKE_PROJECT_VERSION_MINOR`,
+  :variable:`CMAKE_PROJECT_VERSION_PATCH` and :variable:`CMAKE_PROJECT_VERSION_TWEAK`.
+
+* :module:`CPack` module use :variable:`CMAKE_PROJECT_VERSION_MAJOR`,
+  :variable:`CMAKE_PROJECT_VERSION_MINOR` and :variable:`CMAKE_PROJECT_VERSION_PATCH`
+  to initialize corresponding CPack variables.
diff --git a/Help/variable/CMAKE_PROJECT_VERSION.rst b/Help/variable/CMAKE_PROJECT_VERSION.rst
new file mode 100644
index 0000000..4f8f556
--- /dev/null
+++ b/Help/variable/CMAKE_PROJECT_VERSION.rst
@@ -0,0 +1,35 @@
+CMAKE_PROJECT_VERSION
+---------------------
+
+The version of the top level project.
+
+This variable holds the version 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_VERSION`` contains.  For example, consider
+the following top level CMakeLists.txt:
+
+.. code-block:: cmake
+
+  cmake_minimum_required(VERSION 3.0)
+  project(First VERSION 1.2.3)
+  project(Second VERSION 3.4.5)
+  add_subdirectory(sub)
+  project(Third VERSION 6.7.8)
+
+And ``sub/CMakeLists.txt`` with the following contents:
+
+.. code-block:: cmake
+
+  project(SubProj VERSION 1)
+  message("CMAKE_PROJECT_VERSION = ${CMAKE_PROJECT_VERSION}")
+
+The most recently seen :command:`project` command from the top level
+CMakeLists.txt would be ``project(Second ...)``, so this will print::
+
+  CMAKE_PROJECT_VERSION = 3.4.5
+
+To obtain the version from the most recent call to :command:`project` in
+the current directory scope or above, see the :variable:`PROJECT_VERSION`
+variable.
diff --git a/Help/variable/CMAKE_PROJECT_VERSION_MAJOR.rst b/Help/variable/CMAKE_PROJECT_VERSION_MAJOR.rst
new file mode 100644
index 0000000..f1001ac
--- /dev/null
+++ b/Help/variable/CMAKE_PROJECT_VERSION_MAJOR.rst
@@ -0,0 +1,9 @@
+CMAKE_PROJECT_VERSION_MAJOR
+---------------------------
+
+The major version of the top level project.
+
+This variable holds the major version of the project as specified in the top
+level CMakeLists.txt file by a :command:`project` command. Please see
+:variable:`CMAKE_PROJECT_VERSION` documentation for the behavior when
+multiple :command:`project` commands are used in the sources.
diff --git a/Help/variable/CMAKE_PROJECT_VERSION_MINOR.rst b/Help/variable/CMAKE_PROJECT_VERSION_MINOR.rst
new file mode 100644
index 0000000..13202be
--- /dev/null
+++ b/Help/variable/CMAKE_PROJECT_VERSION_MINOR.rst
@@ -0,0 +1,9 @@
+CMAKE_PROJECT_VERSION_MINOR
+---------------------------
+
+The minor version of the top level project.
+
+This variable holds the minor version of the project as specified in the top
+level CMakeLists.txt file by a :command:`project` command. Please see
+:variable:`CMAKE_PROJECT_VERSION` documentation for the behavior when
+multiple :command:`project` commands are used in the sources.
diff --git a/Help/variable/CMAKE_PROJECT_VERSION_PATCH.rst b/Help/variable/CMAKE_PROJECT_VERSION_PATCH.rst
new file mode 100644
index 0000000..b8570d9
--- /dev/null
+++ b/Help/variable/CMAKE_PROJECT_VERSION_PATCH.rst
@@ -0,0 +1,9 @@
+CMAKE_PROJECT_VERSION_PATCH
+---------------------------
+
+The patch version of the top level project.
+
+This variable holds the patch version of the project as specified in the top
+level CMakeLists.txt file by a :command:`project` command. Please see
+:variable:`CMAKE_PROJECT_VERSION` documentation for the behavior when
+multiple :command:`project` commands are used in the sources.
diff --git a/Help/variable/CMAKE_PROJECT_VERSION_TWEAK.rst b/Help/variable/CMAKE_PROJECT_VERSION_TWEAK.rst
new file mode 100644
index 0000000..e1ad4be
--- /dev/null
+++ b/Help/variable/CMAKE_PROJECT_VERSION_TWEAK.rst
@@ -0,0 +1,9 @@
+CMAKE_PROJECT_VERSION_TWEAK
+---------------------------
+
+The tweak version of the top level project.
+
+This variable holds the tweak version of the project as specified in the top
+level CMakeLists.txt file by a :command:`project` command. Please see
+:variable:`CMAKE_PROJECT_VERSION` documentation for the behavior when
+multiple :command:`project` commands are used in the sources.