20 files changed, 160 insertions, 28 deletions
diff --git a/Help/command/project.rst b/Help/command/project.rst
index 9b9f93f..c601a01 100644
--- a/Help/command/project.rst
+++ b/Help/command/project.rst
@@ -1,27 +1,57 @@
 project
 -------
 
-Set a name for the entire project.
+Set a name, version, and enable languages for the entire project.
 
-::
+.. code-block:: cmake
 
-  project(<projectname> [languageName1 languageName2 ... ] )
+ project(<PROJECT-NAME> [LANGUAGES] [<language-name>...])
+ project(<PROJECT-NAME>
+         [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
+         [LANGUAGES <language-name>...])
 
-Sets the name of the project.  Additionally this sets the variables
-<projectName>_BINARY_DIR and <projectName>_SOURCE_DIR to the
-respective values.
+Sets the name of the project and stores the name in the
+:variable:`PROJECT_NAME` variable.  Additionally this sets variables
+
+* :variable:`PROJECT_SOURCE_DIR`,
+  :variable:`<PROJECT-NAME>_SOURCE_DIR`
+* :variable:`PROJECT_BINARY_DIR`,
+  :variable:`<PROJECT-NAME>_BINARY_DIR`
+
+If ``VERSION`` is specified, given components must be non-negative integers.
+If ``VERSION`` is not specified, the default version is the empty string.
+The ``VERSION`` option may not be used unless policy :policy:`CMP0048` is
+set to ``NEW``.
+
+The :command:`project()` command stores the version number and its components
+in variables
+
+* :variable:`PROJECT_VERSION`,
+  :variable:`<PROJECT-NAME>_VERSION`
+* :variable:`PROJECT_VERSION_MAJOR`,
+  :variable:`<PROJECT-NAME>_VERSION_MAJOR`
+* :variable:`PROJECT_VERSION_MINOR`,
+  :variable:`<PROJECT-NAME>_VERSION_MINOR`
+* :variable:`PROJECT_VERSION_PATCH`,
+  :variable:`<PROJECT-NAME>_VERSION_PATCH`
+* :variable:`PROJECT_VERSION_TWEAK`,
+  :variable:`<PROJECT-NAME>_VERSION_TWEAK`
+
+Variables corresponding to unspecified versions are set to the empty string
+(if policy :policy:`CMP0048` is set to ``NEW``).
 
 Optionally you can specify which languages your project supports.
-Example languages are CXX (i.e.  C++), C, Fortran, etc.  By default C
-and CXX are enabled.  E.g.  if you do not have a C++ compiler, you can
-disable the check for it by explicitly listing the languages you want
-to support, e.g.  C.  By using the special language "NONE" all checks
-for any language can be disabled.  If a variable exists called
-CMAKE_PROJECT_<projectName>_INCLUDE, the file pointed to by that
-variable will be included as the last step of the project command.
-
-The top-level CMakeLists.txt file for a project must contain a
-literal, direct call to the project() command; loading one through the
-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).
+Example languages are ``C``, ``CXX`` (i.e.  C++), ``Fortran``, etc.
+By default ``C`` and ``CXX`` are enabled if no language options are
+given.  Specify language ``NONE``, or use the ``LANGUAGES`` keyword
+and list no languages, to skip enabling any languages.
+
+If a variable exists called :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`,
+the file pointed to by that variable will be included as the last step of the
+project command.
+
+The top-level ``CMakeLists.txt`` file for a project must contain a
+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``).
diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index 02f596b..5a9ec95 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -99,3 +99,4 @@ All Policies
    /policy/CMP0045
    /policy/CMP0046
    /policy/CMP0047
+   /policy/CMP0048
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 832bd99..c4ae193 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -79,7 +79,17 @@ Variables that Provide Information
    /variable/PROJECT-NAME_BINARY_DIR
    /variable/PROJECT_NAME
    /variable/PROJECT-NAME_SOURCE_DIR
+   /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_SOURCE_DIR
+   /variable/PROJECT_VERSION
+   /variable/PROJECT_VERSION_MAJOR
+   /variable/PROJECT_VERSION_MINOR
+   /variable/PROJECT_VERSION_PATCH
+   /variable/PROJECT_VERSION_TWEAK
 
 Variables that Change Behavior
 ==============================
@@ -121,6 +131,7 @@ Variables that Change Behavior
    /variable/CMAKE_POLICY_DEFAULT_CMPNNNN
    /variable/CMAKE_PREFIX_PATH
    /variable/CMAKE_PROGRAM_PATH
+   /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE
    /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY
    /variable/CMAKE_STAGING_PREFIX
    /variable/CMAKE_SYSTEM_IGNORE_PATH
diff --git a/Help/policy/CMP0048.rst b/Help/policy/CMP0048.rst
new file mode 100644
index 0000000..ae51329
--- /dev/null
+++ b/Help/policy/CMP0048.rst
@@ -0,0 +1,22 @@
+CMP0048
+-------
+
+The :command:`project` command manages VERSION variables.
+
+CMake version 3.0.0 introduced the ``VERSION`` option of the :command:`project`
+command to specify a project version as well as the name.  In order to keep
+:variable:`PROJECT_VERSION` and related variables consistent with variable
+:variable:`PROJECT_NAME` it is necessary to set the VERSION variables
+to the empty string when no ``VERSION`` is given to :command:`project`.
+However, this can change behavior for existing projects that set VERSION
+variables themselves since :command:`project` may now clear them.
+This policy controls the behavior for compatibility with such projects.
+
+The OLD behavior for this policy is to leave VERSION variables untouched.
+The NEW behavior for this policy is to set VERSION as documented by the
+:command:`project` command.
+
+This policy was introduced in CMake version 3.0.0.
+CMake version |release| warns when the policy is not set and uses
+OLD behavior.  Use the cmake_policy command to set it to OLD or
+NEW explicitly.
diff --git a/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst
new file mode 100644
index 0000000..ba9df5a
--- /dev/null
+++ b/Help/variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE.rst
@@ -0,0 +1,6 @@
+CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE
+------------------------------------
+
+A CMake language file or module to be included by the :command:`project`
+command.  This is is intended for injecting custom code into project
+builds without modifying their source.
diff --git a/Help/variable/PROJECT-NAME_BINARY_DIR.rst b/Help/variable/PROJECT-NAME_BINARY_DIR.rst
index a19940f..49bc558 100644
--- a/Help/variable/PROJECT-NAME_BINARY_DIR.rst
+++ b/Help/variable/PROJECT-NAME_BINARY_DIR.rst
@@ -3,6 +3,6 @@
 
 Top level binary directory for the named project.
 
-A variable is created with the name used in the PROJECT command, and
-is the binary directory for the project.  This can be useful when
-SUBDIR is used to connect several projects.
+A variable is created with the name used in the :command:`project` command,
+and is the binary directory for the project.  This can be useful when
+:command:`add_subdirectory` is used to connect several projects.
diff --git a/Help/variable/PROJECT-NAME_SOURCE_DIR.rst b/Help/variable/PROJECT-NAME_SOURCE_DIR.rst
index f2f5caf..4df3e22 100644
--- a/Help/variable/PROJECT-NAME_SOURCE_DIR.rst
+++ b/Help/variable/PROJECT-NAME_SOURCE_DIR.rst
@@ -3,6 +3,6 @@
 
 Top level source directory for the named project.
 
-A variable is created with the name used in the PROJECT command, and
-is the source directory for the project.  This can be useful when
-add_subdirectory is used to connect several projects.
+A variable is created with the name used in the :command:`project` command,
+and is the source directory for the project.  This can be useful when
+:command:`add_subdirectory` is used to connect several projects.
diff --git a/Help/variable/PROJECT-NAME_VERSION.rst b/Help/variable/PROJECT-NAME_VERSION.rst
new file mode 100644
index 0000000..0f6ed51
--- /dev/null
+++ b/Help/variable/PROJECT-NAME_VERSION.rst
@@ -0,0 +1,11 @@
+<PROJECT-NAME>_VERSION
+----------------------
+
+Value given to the ``VERSION`` option of the most recent call to the
+:command:`project` command with project name ``<PROJECT-NAME>``, if any.
+
+See also the component-wise version variables
+:variable:`<PROJECT-NAME>_VERSION_MAJOR`,
+:variable:`<PROJECT-NAME>_VERSION_MINOR`,
+:variable:`<PROJECT-NAME>_VERSION_PATCH`, and
+:variable:`<PROJECT-NAME>_VERSION_TWEAK`.
diff --git a/Help/variable/PROJECT-NAME_VERSION_MAJOR.rst b/Help/variable/PROJECT-NAME_VERSION_MAJOR.rst
new file mode 100644
index 0000000..9e2d755
--- /dev/null
+++ b/Help/variable/PROJECT-NAME_VERSION_MAJOR.rst
@@ -0,0 +1,5 @@
+<PROJECT-NAME>_VERSION_MAJOR
+----------------------------
+
+First version number component of the :variable:`<PROJECT-NAME>_VERSION`
+variable as set by the :command:`project` command.
diff --git a/Help/variable/PROJECT-NAME_VERSION_MINOR.rst b/Help/variable/PROJECT-NAME_VERSION_MINOR.rst
new file mode 100644
index 0000000..fa2cdab
--- /dev/null
+++ b/Help/variable/PROJECT-NAME_VERSION_MINOR.rst
@@ -0,0 +1,5 @@
+<PROJECT-NAME>_VERSION_MINOR
+----------------------------
+
+Second version number component of the :variable:`<PROJECT-NAME>_VERSION`
+variable as set by the :command:`project` command.
diff --git a/Help/variable/PROJECT-NAME_VERSION_PATCH.rst b/Help/variable/PROJECT-NAME_VERSION_PATCH.rst
new file mode 100644
index 0000000..85b5e6b
--- /dev/null
+++ b/Help/variable/PROJECT-NAME_VERSION_PATCH.rst
@@ -0,0 +1,5 @@
+<PROJECT-NAME>_VERSION_PATCH
+----------------------------
+
+Third version number component of the :variable:`<PROJECT-NAME>_VERSION`
+variable as set by the :command:`project` command.
diff --git a/Help/variable/PROJECT-NAME_VERSION_TWEAK.rst b/Help/variable/PROJECT-NAME_VERSION_TWEAK.rst
new file mode 100644
index 0000000..65c4044
--- /dev/null
+++ b/Help/variable/PROJECT-NAME_VERSION_TWEAK.rst
@@ -0,0 +1,5 @@
+<PROJECT-NAME>_VERSION_TWEAK
+----------------------------
+
+Fourth version number component of the :variable:`<PROJECT-NAME>_VERSION`
+variable as set by the :command:`project` command.
diff --git a/Help/variable/PROJECT_BINARY_DIR.rst b/Help/variable/PROJECT_BINARY_DIR.rst
index e506bdd..09e9ef2 100644
--- a/Help/variable/PROJECT_BINARY_DIR.rst
+++ b/Help/variable/PROJECT_BINARY_DIR.rst
@@ -3,4 +3,4 @@ PROJECT_BINARY_DIR
 
 Full path to build directory for project.
 
-This is the binary directory of the most recent PROJECT command.
+This is the binary directory of the most recent :command:`project` command.
diff --git a/Help/variable/PROJECT_NAME.rst b/Help/variable/PROJECT_NAME.rst
index 7559af6..61aa8bc 100644
--- a/Help/variable/PROJECT_NAME.rst
+++ b/Help/variable/PROJECT_NAME.rst
@@ -3,4 +3,4 @@ PROJECT_NAME
 
 Name of the project given to the project command.
 
-This is the name given to the most recent PROJECT command.
+This is the name given to the most recent :command:`project` command.
diff --git a/Help/variable/PROJECT_SOURCE_DIR.rst b/Help/variable/PROJECT_SOURCE_DIR.rst
index c9ba132..27f2838 100644
--- a/Help/variable/PROJECT_SOURCE_DIR.rst
+++ b/Help/variable/PROJECT_SOURCE_DIR.rst
@@ -3,4 +3,4 @@ PROJECT_SOURCE_DIR
 
 Top level source directory for the current project.
 
-This is the source directory of the most recent PROJECT command.
+This is the source directory of the most recent :command:`project` command.
diff --git a/Help/variable/PROJECT_VERSION.rst b/Help/variable/PROJECT_VERSION.rst
new file mode 100644
index 0000000..234558d
--- /dev/null
+++ b/Help/variable/PROJECT_VERSION.rst
@@ -0,0 +1,11 @@
+PROJECT_VERSION
+---------------
+
+Value given to the ``VERSION`` option of the most recent call to the
+:command:`project` command, if any.
+
+See also the component-wise version variables
+:variable:`PROJECT_VERSION_MAJOR`,
+:variable:`PROJECT_VERSION_MINOR`,
+:variable:`PROJECT_VERSION_PATCH`, and
+:variable:`PROJECT_VERSION_TWEAK`.
diff --git a/Help/variable/PROJECT_VERSION_MAJOR.rst b/Help/variable/PROJECT_VERSION_MAJOR.rst
new file mode 100644
index 0000000..4b6072c
--- /dev/null
+++ b/Help/variable/PROJECT_VERSION_MAJOR.rst
@@ -0,0 +1,5 @@
+PROJECT_VERSION_MAJOR
+---------------------
+
+First version number component of the :variable:`PROJECT_VERSION`
+variable as set by the :command:`project` command.
diff --git a/Help/variable/PROJECT_VERSION_MINOR.rst b/Help/variable/PROJECT_VERSION_MINOR.rst
new file mode 100644
index 0000000..5f31220
--- /dev/null
+++ b/Help/variable/PROJECT_VERSION_MINOR.rst
@@ -0,0 +1,5 @@
+PROJECT_VERSION_MINOR
+---------------------
+
+Second version number component of the :variable:`PROJECT_VERSION`
+variable as set by the :command:`project` command.
diff --git a/Help/variable/PROJECT_VERSION_PATCH.rst b/Help/variable/PROJECT_VERSION_PATCH.rst
new file mode 100644
index 0000000..ac72ec0
--- /dev/null
+++ b/Help/variable/PROJECT_VERSION_PATCH.rst
@@ -0,0 +1,5 @@
+PROJECT_VERSION_PATCH
+---------------------
+
+Third version number component of the :variable:`PROJECT_VERSION`
+variable as set by the :command:`project` command.
diff --git a/Help/variable/PROJECT_VERSION_TWEAK.rst b/Help/variable/PROJECT_VERSION_TWEAK.rst
new file mode 100644
index 0000000..d7f96d6
--- /dev/null
+++ b/Help/variable/PROJECT_VERSION_TWEAK.rst
@@ -0,0 +1,5 @@
+PROJECT_VERSION_TWEAK
+---------------------
+
+Fourth version number component of the :variable:`PROJECT_VERSION`
+variable as set by the :command:`project` command.