From 5b56795d57ad79dcc4ce9070481101f28f737eda Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (l)" Date: Fri, 5 Oct 2018 15:23:15 +0200 Subject: Help: make the two signatures of command "project" orthogonal --- Help/command/project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Help/command/project.rst b/Help/command/project.rst index bd8b4ef..f91eed8 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -5,7 +5,7 @@ Sets project details such as name, version, etc. and enables languages. .. code-block:: cmake - project( [LANGUAGES] [...]) + project( [...]) project( [VERSION [.[.[.]]]] [DESCRIPTION ] -- cgit v0.12 From e3e5445d83c253c3ddc18b5b02b59e90aa0b9df9 Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (l)" Date: Fri, 5 Oct 2018 15:32:46 +0200 Subject: Help: Describe options of command project in a definition list. Also add section headers; explain default setting of optional argument variables. --- Help/command/project.rst | 123 +++++++++++++++++++++++++++-------------------- 1 file changed, 72 insertions(+), 51 deletions(-) diff --git a/Help/command/project.rst b/Help/command/project.rst index f91eed8..18420e4 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -1,7 +1,10 @@ project ------- -Sets project details such as name, version, etc. and enables languages. +Set the name of the project. + +Synopsis +^^^^^^^^ .. code-block:: cmake @@ -12,65 +15,83 @@ Sets project details such as name, version, etc. and enables languages. [HOMEPAGE_URL ] [LANGUAGES ...]) -Sets the name of the project and stores the name in the -:variable:`PROJECT_NAME` variable. Additionally this sets variables +Sets the name of the project, and stores it in the variable +:variable:`PROJECT_NAME`. Also sets the variables * :variable:`PROJECT_SOURCE_DIR`, :variable:`_SOURCE_DIR` * :variable:`PROJECT_BINARY_DIR`, :variable:`_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:`_VERSION` -* :variable:`PROJECT_VERSION_MAJOR`, - :variable:`_VERSION_MAJOR` -* :variable:`PROJECT_VERSION_MINOR`, - :variable:`_VERSION_MINOR` -* :variable:`PROJECT_VERSION_PATCH`, - :variable:`_VERSION_PATCH` -* :variable:`PROJECT_VERSION_TWEAK`, - :variable:`_VERSION_TWEAK` - -Variables corresponding to unspecified versions are set to the empty string -(if policy :policy:`CMP0048` is set to ``NEW``). - -If the optional ``DESCRIPTION`` is given, then :variable:`PROJECT_DESCRIPTION` -and :variable:`_DESCRIPTION` will be set to its argument. -These variables will be cleared if ``DESCRIPTION`` is not given. -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:`_HOMEPAGE_URL`. -When this option is given, the URL provided should be the canonical home for -the project. -These variables will be cleared if ``HOMEPAGE_URL`` is not given. - -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``, -``Fortran``, and ``ASM``. -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 enabling ``ASM``, list it last so that CMake can check whether -compilers for other languages like ``C`` work for assembly too. - -If a variable exists called :variable:`CMAKE_PROJECT__INCLUDE`, +Further variables are set by the optional arguments described in the following. +If any of these arguments is not used, then the corresponding variables are +set to the empty string. + +If the variable :variable:`CMAKE_PROJECT__INCLUDE` exists, the file pointed to by that variable will be included as the last step of the project command. +Options +^^^^^^^ + +The options are: + +``VERSION `` + Optional; may not be used unless policy :policy:`CMP0048` is + set to ``NEW``. + + Takes a ```` argument composed of non-negative integer components, + i.e. ``[.[.[.]]]``, + and sets the variables + + * :variable:`PROJECT_VERSION`, + :variable:`_VERSION` + * :variable:`PROJECT_VERSION_MAJOR`, + :variable:`_VERSION_MAJOR` + * :variable:`PROJECT_VERSION_MINOR`, + :variable:`_VERSION_MINOR` + * :variable:`PROJECT_VERSION_PATCH`, + :variable:`_VERSION_PATCH` + * :variable:`PROJECT_VERSION_TWEAK`, + :variable:`_VERSION_TWEAK`. + +``DESCRIPTION `` + Optional. + Sets the variables + + * :variable:`PROJECT_DESCRIPTION`, :variable:`_DESCRIPTION` + + to ````. + It is recommended that this description is a relatively short string, + usually no more than a few words. + +``HOMEPAGE_URL `` + Optional. + Sets the variables + + * :variable:`PROJECT_HOMEPAGE_URL`, :variable:`_HOMEPAGE_URL` + + to ````, which should be the canonical home URL for the project. + +``LANGUAGES ...`` + Optional. + Can also be specified without ``LANGUAGES`` keyword per the first, short signature. + + Selects which programming languages are needed to build the project. + Supported languages include ``C``, ``CXX`` (i.e. C++), ``CUDA``, ``Fortran``, and ``ASM``. + 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 enabling ``ASM``, list it last so that CMake can check whether + compilers for other languages like ``C`` work for assembly too. + +The variables set through the ``VERSION``, ``DESCRIPTION`` and ``HOMEPAGE_URL`` +options are intended for use as default values in package metadata and documentation. + +Usage +^^^^^ + 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 -- cgit v0.12 From 2f43bd3b6ca886b52fadae50a3bfbbf44029b9cd Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (o)" Date: Tue, 9 Oct 2018 15:28:53 +0200 Subject: Help: move description of CMAKE_PROJECT_* variables Describe these variables along with the other variables. --- Help/command/project.rst | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/Help/command/project.rst b/Help/command/project.rst index 18420e4..688e56c 100644 --- a/Help/command/project.rst +++ b/Help/command/project.rst @@ -16,7 +16,11 @@ Synopsis [LANGUAGES ...]) Sets the name of the project, and stores it in the variable -:variable:`PROJECT_NAME`. Also sets the variables +:variable:`PROJECT_NAME`. When called from the top-level +``CMakeLists.txt`` also stores the project name in the +variable :variable:`CMAKE_PROJECT_NAME`. + +Also sets the variables * :variable:`PROJECT_SOURCE_DIR`, :variable:`_SOURCE_DIR` @@ -55,6 +59,9 @@ The options are: * :variable:`PROJECT_VERSION_TWEAK`, :variable:`_VERSION_TWEAK`. + When the :command:`project()` command is called from the top-level ``CMakeLists.txt``, + then the version is also stored in the variable :variable:`CMAKE_PROJECT_VERSION`. + ``DESCRIPTION `` Optional. Sets the variables @@ -65,6 +72,9 @@ The options are: It is recommended that this description is a relatively short string, usually no more than a few words. + When the :command:`project()` command is called from the top-level ``CMakeLists.txt``, + then the description is also stored in the variable :variable:`CMAKE_PROJECT_DESCRIPTION`. + ``HOMEPAGE_URL `` Optional. Sets the variables @@ -73,6 +83,9 @@ The options are: to ````, which should be the canonical home URL for the project. + When the :command:`project()` command is called from the top-level ``CMakeLists.txt``, + then the URL also is stored in the variable :variable:`CMAKE_PROJECT_HOMEPAGE_URL`. + ``LANGUAGES ...`` Optional. Can also be specified without ``LANGUAGES`` keyword per the first, short signature. @@ -96,16 +109,11 @@ 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``). 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`, its homepage URL from -:variable:`CMAKE_PROJECT_HOMEPAGE_URL` and its version from -:variable:`CMAKE_PROJECT_VERSION`. +default languages (``C`` and ``CXX``). .. note:: Call the :command:`cmake_minimum_required` command at the beginning of the top-level ``CMakeLists.txt`` file even before calling the - ``project()`` command. It is important to establish version and + :command:`project()` command. It is important to establish version and policy settings before invoking other commands whose behavior they may affect. See also policy :policy:`CMP0000`. -- cgit v0.12