If a project() call does not have DESCRIPTION or HOMEPAGE_URL
options, it must still set the relevant variables or else those variables will
inherit values from an earlier project() call. That is inconsistent with how
VERSION is handled and is likely to be unexpected. The docs were also
ambiguous about what should happen in such cases.
* Introduce `CMAKE_PROJECT_VERSION` and the corresponsing components:
`CMAKE_PROJECT_VERSION_MAJOR`, `CMAKE_PROJECT_VERSION_MINOR`,
`CMAKE_PROJECT_VERSION_PATCH` and `CMAKE_PROJECT_VERSION_TWEAK`.
* `CPack` module use `CMAKE_PROJECT_VERSION_MAJOR`,
`CMAKE_PROJECT_VERSION_MINOR` and `CMAKE_PROJECT_VERSION_PATCH`
to initialize corresponsing CPack variables.
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 <craig.scott@crascit.com>
The docs for CMAKE_PROJECT_NAME and CMAKE_PROJECT_DESCRIPTION
were erroneously documenting the behavior of PROJECT_NAME and
PROJECT_DESCRIPTION respectively. Fix these and update the
project() docs to also mention CMAKE_PROJECT_NAME and
CMAKE_PROJECT_DESCRIPTION.
Fixes: #17815
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`.
Many projects put their project() call first, but the actions taken
by this command can be influenced by policies and other information
set by a call to cmake_minimum_required. Document in each of these
two commands that cmake_minimum_required should be called first.
Suggested-by: Alan W. Irwin
Teach the project() command to set variables
{PROJECT,<PROJECT-NAME>}_VERSION{,_MAJOR,_MINOR,_PATCH,_TWEAK}
holding the project version number and its components. Add project()
command option "VERSION" to specify the version explicitly, and default
to the empty string when it is not given.
Since this clears variables when no VERSION is given, this may change
behavior for existing projects that set the version variables themselves
prior to calling project(). Add policy CMP0048 for compatibility.
Suggested-by: Alex Neundorf <neundorf@kde.org>
Teach the project() command to recognize an optional "LANGUAGES"
keyword after the project name and prior to the list of languages.
Do not allow multiple copies of the keyword. If the keyword is
specified and no languages are listed, imply NONE.
