project: Add `DESCRIPTION` parameter

It is quite often the project description has used in a real world software.
Examples include:

* part of a help screen of the application
* builtin resources (`*.rc` files, data for "About" dialog of a GUI app, & etc)
* most generators for CPack can use it
* it could be used by documentary software (Doxygen, Sphinx) which is usually
  integrated to CMake based projects via `add_custom_target()`

Now `project()` call learned an optional `DESCRIPTION` parameter with a
short string describing a project. Being specified, it would set the
`PROJECT_DESCRIPTION` variable which could be used in `configure_file()`
or whatever user wants.  Also `PROJECT_DESCRIPTION` is a default value
for `CPACK_PACKAGE_DESCRIPTION_SUMMARY`.

13 files changed, 82 insertions, 3 deletions

diff --git a/Help/command/project.rst b/Help/command/project.rst
index 6c5ace7..139f69c 100644
--- a/Help/command/project.rst
+++ b/Help/command/project.rst
@@ -8,6 +8,7 @@ Set a name, version, and enable languages for the entire project.
  project(<PROJECT-NAME> [LANGUAGES] [<language-name>...])
  project(<PROJECT-NAME>
          [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
+         [DESCRIPTION <project-description-string>]
          [LANGUAGES <language-name>...])
 
 Sets the name of the project and stores the name in the
@@ -40,6 +41,10 @@ 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).
+
 Optionally you can specify which languages your project supports.
 Example languages are ``C``, ``CXX`` (i.e.  C++), ``Fortran``, etc.
 By default ``C`` and ``CXX`` are enabled if no language options are
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 9d8d596..038d6e0 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -60,6 +60,7 @@ Variables that Provide Information
    /variable/CMAKE_MINOR_VERSION
    /variable/CMAKE_PARENT_LIST_FILE
    /variable/CMAKE_PATCH_VERSION
+   /variable/CMAKE_PROJECT_DESCRIPTION
    /variable/CMAKE_PROJECT_NAME
    /variable/CMAKE_RANLIB
    /variable/CMAKE_ROOT
@@ -97,6 +98,7 @@ Variables that Provide Information
    /variable/PROJECT-NAME_VERSION_PATCH
    /variable/PROJECT-NAME_VERSION_TWEAK
    /variable/PROJECT_BINARY_DIR
+   /variable/PROJECT_DESCRIPTION
    /variable/PROJECT_NAME
    /variable/PROJECT_SOURCE_DIR
    /variable/PROJECT_VERSION
diff --git a/Help/release/dev/project_description.rst b/Help/release/dev/project_description.rst
new file mode 100644
index 0000000..baf0045
--- /dev/null
+++ b/Help/release/dev/project_description.rst
@@ -0,0 +1,5 @@
+project-description
+-------------------
+
+* The :command:`project` command learned an optional ``DESCRIPTION`` parameter.
+  See :command:`project` command and :variable:`PROJECT_DESCRIPTION` variable.
diff --git a/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst b/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst
new file mode 100644
index 0000000..f1911ec
--- /dev/null
+++ b/Help/variable/CMAKE_PROJECT_DESCRIPTION.rst
@@ -0,0 +1,7 @@
+CMAKE_PROJECT_DESCRIPTION
+-------------------------
+
+The description of the current project.
+
+This specifies description of the current project from the closest inherited
+:command:`project` command.
diff --git a/Help/variable/PROJECT_DESCRIPTION.rst b/Help/variable/PROJECT_DESCRIPTION.rst
new file mode 100644
index 0000000..05ede8f
--- /dev/null
+++ b/Help/variable/PROJECT_DESCRIPTION.rst
@@ -0,0 +1,6 @@
+PROJECT_DESCRIPTION
+-------------------
+
+Short project description given to the project command.
+
+This is the description given to the most recent :command:`project` command.
diff --git a/Modules/CPack.cmake b/Modules/CPack.cmake
index 4e7546b..a63fc83 100644
--- a/Modules/CPack.cmake
+++ b/Modules/CPack.cmake
@@ -98,7 +98,12 @@
 #
 # .. variable:: CPACK_PACKAGE_DESCRIPTION_SUMMARY
 #
-#  Short description of the project (only a few words).
+#  Short description of the project (only a few words). Default value is::
+#
+#    ${PROJECT_DESCRIPTION}
+#
+#  if DESCRIPTION has given to the project() call or
+#  CMake generated string with PROJECT_NAME otherwise.
 #
 # .. variable:: CPACK_PACKAGE_FILE_NAME
 #
@@ -360,8 +365,13 @@ _cpack_set_default(CPACK_PACKAGE_VERSION_PATCH "1")
 _cpack_set_default(CPACK_PACKAGE_VERSION
   "${CPACK_PACKAGE_VERSION_MAJOR}.${CPACK_PACKAGE_VERSION_MINOR}.${CPACK_PACKAGE_VERSION_PATCH}")
 _cpack_set_default(CPACK_PACKAGE_VENDOR "Humanity")
-_cpack_set_default(CPACK_PACKAGE_DESCRIPTION_SUMMARY
-  "${CMAKE_PROJECT_NAME} built using CMake")
+if(CMAKE_PROJECT_DESCRIPTION)
+  _cpack_set_default(CPACK_PACKAGE_DESCRIPTION_SUMMARY
+    "${CMAKE_PROJECT_DESCRIPTION}")
+else()
+  _cpack_set_default(CPACK_PACKAGE_DESCRIPTION_SUMMARY
+    "${CMAKE_PROJECT_NAME} built using CMake")
+endif()
 
 _cpack_set_default(CPACK_PACKAGE_DESCRIPTION_FILE
   "${CMAKE_ROOT}/Templates/CPack.GenericDescription.txt")
diff --git a/Source/cmProjectCommand.cxx b/Source/cmProjectCommand.cxx
index 4e0fa57..66f324a 100644
--- a/Source/cmProjectCommand.cxx
+++ b/Source/cmProjectCommand.cxx
@@ -62,10 +62,13 @@ bool cmProjectCommand::InitialPass(std::vector<std::string> const& args,
 
   bool haveVersion = false;
   bool haveLanguages = false;
+  bool haveDescription = false;
   std::string version;
+  std::string description;
   std::vector<std::string> languages;
   enum Doing
   {
+    DoingDescription,
     DoingLanguages,
     DoingVersion
   };
@@ -89,9 +92,21 @@ bool cmProjectCommand::InitialPass(std::vector<std::string> const& args,
       }
       haveVersion = true;
       doing = DoingVersion;
+    } else if (args[i] == "DESCRIPTION") {
+      if (haveDescription) {
+        this->Makefile->IssueMessage(
+          cmake::FATAL_ERROR, "DESCRITPION may be specified at most once.");
+        cmSystemTools::SetFatalErrorOccured();
+        return true;
+      }
+      haveDescription = true;
+      doing = DoingDescription;
     } else if (doing == DoingVersion) {
       doing = DoingLanguages;
       version = args[i];
+    } else if (doing == DoingDescription) {
+      doing = DoingLanguages;
+      description = args[i];
     } else // doing == DoingLanguages
     {
       languages.push_back(args[i]);
@@ -197,6 +212,22 @@ bool cmProjectCommand::InitialPass(std::vector<std::string> const& args,
     }
   }
 
+  if (haveDescription) {
+    this->Makefile->AddDefinition("PROJECT_DESCRIPTION", description.c_str());
+    // Set the CMAKE_PROJECT_DESCRIPTION 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_DESCRIPTION") ||
+        (this->Makefile->IsRootMakefile())) {
+      this->Makefile->AddDefinition("CMAKE_PROJECT_DESCRIPTION",
+                                    description.c_str());
+      this->Makefile->AddCacheDefinition(
+        "CMAKE_PROJECT_DESCRIPTION", description.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/ProjectDescription-stdout.txt b/Tests/RunCMake/project/ProjectDescription-stdout.txt
new file mode 100644
index 0000000..ffa9092
--- /dev/null
+++ b/Tests/RunCMake/project/ProjectDescription-stdout.txt
@@ -0,0 +1 @@
+PROJECT_DESCRIPTION=Test Project
diff --git a/Tests/RunCMake/project/ProjectDescription.cmake b/Tests/RunCMake/project/ProjectDescription.cmake
new file mode 100644
index 0000000..3a47362
--- /dev/null
+++ b/Tests/RunCMake/project/ProjectDescription.cmake
@@ -0,0 +1,6 @@
+cmake_policy(SET CMP0048 NEW)
+project(ProjectDescriptionTest VERSION 1.0.0 DESCRIPTION "Test Project" LANGUAGES)
+if(NOT PROJECT_DESCRIPTION)
+  message(FATAL_ERROR "PROJECT_DESCRIPTION expected to be set")
+endif()
+message(STATUS "PROJECT_DESCRIPTION=${PROJECT_DESCRIPTION}")
diff --git a/Tests/RunCMake/project/ProjectDescription2-result.txt b/Tests/RunCMake/project/ProjectDescription2-result.txt
new file mode 100644
index 0000000..d00491f
--- /dev/null
+++ b/Tests/RunCMake/project/ProjectDescription2-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/project/ProjectDescription2-stderr.txt b/Tests/RunCMake/project/ProjectDescription2-stderr.txt
new file mode 100644
index 0000000..558e2df
--- /dev/null
+++ b/Tests/RunCMake/project/ProjectDescription2-stderr.txt
@@ -0,0 +1 @@
+  DESCRITPION may be specified at most once.
diff --git a/Tests/RunCMake/project/ProjectDescription2.cmake b/Tests/RunCMake/project/ProjectDescription2.cmake
new file mode 100644
index 0000000..3f186ba
--- /dev/null
+++ b/Tests/RunCMake/project/ProjectDescription2.cmake
@@ -0,0 +1,2 @@
+cmake_policy(SET CMP0048 NEW)
+project(ProjectDescriptionTest VERSION 1.0.0 DESCRIPTION "Test Project" DESCRIPTION "Only once allowed" LANGUAGES)
diff --git a/Tests/RunCMake/project/RunCMakeTest.cmake b/Tests/RunCMake/project/RunCMakeTest.cmake
index dba97d2..3d13e2e 100644
--- a/Tests/RunCMake/project/RunCMakeTest.cmake
+++ b/Tests/RunCMake/project/RunCMakeTest.cmake
@@ -7,6 +7,8 @@ run_cmake(LanguagesImplicit)
 run_cmake(LanguagesEmpty)
 run_cmake(LanguagesNONE)
 run_cmake(LanguagesTwice)
+run_cmake(ProjectDescription)
+run_cmake(ProjectDescription2)
 run_cmake(VersionAndLanguagesEmpty)
 run_cmake(VersionEmpty)
 run_cmake(VersionInvalid)