mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-07 06:09:52 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge topic 'docs-project-code-injection'

Browse Source 
42294f43bd Help: move code injection vars to their own section
9e0775cb6a Help: Remove self-references from project() docs

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !3494
This commit is contained in:
Craig Scott
2019-07-01 11:42:31 +00:00
committed by Kitware Robot
parent 56f5310112 42294f43bd
commit 7ea18c02c3
1 changed files with 18 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
Help/command/project.rst
View File

@@ -31,14 +31,6 @@ 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_BEFORE` exists, the file
pointed to by that variable will be included as the first step of the project
command.
If the variable :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`
or :variable:`CMAKE_PROJECT_INCLUDE` exists, the file pointed to by that
variable will be included as the last step of the project command.
Options
^^^^^^^
@@ -63,7 +55,7 @@ The options are:
* :variable:`PROJECT_VERSION_TWEAK`,
:variable:`<PROJECT-NAME>_VERSION_TWEAK`.
When the :command:`project()` command is called from the top-level ``CMakeLists.txt``,
When the ``project()`` command is called from the top-level ``CMakeLists.txt``,
then the version is also stored in the variable :variable:`CMAKE_PROJECT_VERSION`.
``DESCRIPTION <project-description-string>``
@@ -76,7 +68,7 @@ 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``,
When the ``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 <url-string>``
@@ -87,7 +79,7 @@ The options are:
to ``<url-string>``, which should be the canonical home URL for the project.
When the :command:`project()` command is called from the top-level ``CMakeLists.txt``,
When the ``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 <language-name>...``
@@ -106,18 +98,31 @@ The options are:
The variables set through the ``VERSION``, ``DESCRIPTION`` and ``HOMEPAGE_URL``
options are intended for use as default values in package metadata and documentation.
Code Injection
^^^^^^^^^^^^^^
If the :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` variable is set, the file
pointed to by that variable will be included as the first step of the
``project()`` command.
If the :variable:`CMAKE_PROJECT_INCLUDE` or
:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` variables are set, the files
they point to will be included as the last step of the ``project()`` command.
If both are set, then :variable:`CMAKE_PROJECT_INCLUDE` will be included before
:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`.
Usage
^^^^^
The top-level ``CMakeLists.txt`` file for a project must contain a
literal, direct call to the :command:`project` command; loading one
literal, direct call to the ``project()`` command; loading one
through the :command:`include` command is not sufficient. If no such
call exists, CMake will issue a warning and pretend there is a
``project(Project)`` at the top to enable the default languages
(``C`` and ``CXX``).
.. note::
Call the :command:`project()` command near the top of the top-level
Call the ``project()`` command near the top of the top-level
``CMakeLists.txt``, but *after* calling :command:`cmake_minimum_required`.
It is important to establish version and policy settings before invoking
other commands whose behavior they may affect.