mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-03-03 05:08:47 -06:00
Code Issues Packages Projects Releases Wiki Activity

Help: Describe options of command project in a definition list.

Browse Source 
Also add section headers;
explain default setting of optional argument variables.
This commit is contained in:
Joachim Wuttke (l)
2018-10-05 15:32:46 +02:00
committed by Joachim Wuttke (o)
parent 5b56795d57
commit e3e5445d83
1 changed files with 71 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files

121
Help/command/project.rst
View File

@@ -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 <url-string>]
[LANGUAGES <language-name>...])
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:`<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``.
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.
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``).
If the optional ``DESCRIPTION`` is given, then :variable:`PROJECT_DESCRIPTION`
and :variable:`<PROJECT-NAME>_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:`<PROJECT-NAME>_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_<PROJECT-NAME>_INCLUDE`,
If the variable :variable:`CMAKE_PROJECT_<PROJECT-NAME>_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 <version>``
Optional; may not be used unless policy :policy:`CMP0048` is
set to ``NEW``.
Takes a ``<version>`` argument composed of non-negative integer components,
i.e. ``<major>[.<minor>[.<patch>[.<tweak>]]]``,
and sets the 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`.
``DESCRIPTION <project-description-string>``
Optional.
Sets the variables
* :variable:`PROJECT_DESCRIPTION`, :variable:`<PROJECT-NAME>_DESCRIPTION`
to ``<project-description-string>``.
It is recommended that this description is a relatively short string,
usually no more than a few words.
``HOMEPAGE_URL <url-string>``
Optional.
Sets the variables
* :variable:`PROJECT_HOMEPAGE_URL`, :variable:`<PROJECT-NAME>_HOMEPAGE_URL`
to ``<url-string>``, which should be the canonical home URL for the project.
``LANGUAGES <language-name>...``
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