ContextQMD
Back to Cmake

project

Help/command/project.rst

4.3.29.6 KB
Original Source

project

Set the name of the project.

Synopsis ^^^^^^^^

.. code-block:: cmake

project(<PROJECT-NAME> [<language-name>...]) project(<PROJECT-NAME> [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]] [COMPAT_VERSION <major>[.<minor>[.<patch>[.<tweak>]]]] [SPDX_LICENSE <license-string>] [DESCRIPTION <description-string>] [HOMEPAGE_URL <url-string>] [LANGUAGES <language-name>...])

Sets the name of the project, and stores it in the variable :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:<PROJECT-NAME>_SOURCE_DIR Absolute path to the source directory for the project.

:variable:PROJECT_BINARY_DIR, :variable:<PROJECT-NAME>_BINARY_DIR Absolute path to the binary directory for the project.

:variable:PROJECT_IS_TOP_LEVEL, :variable:<PROJECT-NAME>_IS_TOP_LEVEL .. versionadded:: 3.21

Boolean value indicating whether the project is top-level.

Further variables are set by the optional arguments described in Options_ further below. Where an option is not given, its corresponding variable is set to the empty string.

Note that variables of the form <name>_SOURCE_DIR and <name>_BINARY_DIR may also be set by other commands before project() is called (see the :command:FetchContent_MakeAvailable command for one example). Projects should not rely on <PROJECT-NAME>_SOURCE_DIR or <PROJECT-NAME>_BINARY_DIR holding a particular value outside of the scope of the call to project() or one of its child scopes.

.. versionchanged:: 3.30 <PROJECT-NAME>_SOURCE_DIR, <PROJECT-NAME>_BINARY_DIR, and <PROJECT-NAME>_IS_TOP_LEVEL, if already set as normal variables when project(<PROJECT-NAME> ...) is called, are updated by the call. Cache entries by the same names are always set as before. See release notes for 3.30.3, 3.30.4, and 3.30.5 for details.

.. versionchanged:: 3.31 <PROJECT-NAME>_SOURCE_DIR, <PROJECT-NAME>_BINARY_DIR, and <PROJECT-NAME>_IS_TOP_LEVEL are always set as normal variables by project(<PROJECT-NAME> ...). See policy :policy:CMP0180. Cache entries by the same names are always set as before.

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.

.. versionadded:: 3.12 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.

COMPAT_VERSION <version> .. versionadded:: 4.3

Optional; requires VERSION also be set.

Takes a <version> argument composed of non-negative integer components, i.e. <major>[.<minor>[.<patch>[.<tweak>]]], and sets the variables

  • :variable:PROJECT_COMPAT_VERSION, :variable:<PROJECT-NAME>_COMPAT_VERSION.

When the project() command is called from the top-level CMakeLists.txt, then the compatibility version is also stored in the variable :variable:CMAKE_PROJECT_COMPAT_VERSION.

SPDX_LICENSE <license-string> .. versionadded:: 4.3

Optional. Sets the variables

  • :variable:PROJECT_SPDX_LICENSE, :variable:<PROJECT-NAME>_SPDX_LICENSE

to <license-string>, which shall be a |SPDX|_ (SPDX) License Expression_ that describes the license(s) of the project as a whole, including documentation, resources, or other materials distributed with the project, in addition to software artifacts. See the SPDX License List_ for a list of commonly used licenses and their identifiers. See the :prop_tgt:SPDX_LICENSE property for specifying the license(s) on individual software artifacts.

.. note:: The project license is not used to initialize the :prop_tgt:SPDX_LICENSE property of individual targets. This allows the package license and default component license, which are specified when exporting package information, to be meaningful. Only |CPS| exports make use of this information.

The project license *is* inherited as the package license in some cases.
Refer to the ``PROJECT`` option and related documentation of the
:command:`export` and :command:`install` commands for more information.

.. _SPDX: https://spdx.dev/ .. |SPDX| replace:: System Package Data Exchange

.. _License Expression: https://spdx.github.io/spdx-spec/v3.0.1/annexes/spdx-license-expressions/ .. _License List: https://spdx.org/licenses/

DESCRIPTION <description-string> .. versionadded:: 3.9

Optional. Sets the variables

  • :variable:PROJECT_DESCRIPTION, :variable:<PROJECT-NAME>_DESCRIPTION

to <description-string>. It is recommended that this description is a relatively short string, usually no more than a few words.

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.

.. versionadded:: 3.12 Added the <PROJECT-NAME>_DESCRIPTION variable.

HOMEPAGE_URL <url-string> .. versionadded:: 3.12

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.

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>... Optional. Can also be specified without LANGUAGES keyword per the first, short signature.

Selects which programming languages are needed to build the project.

.. include:: include/SUPPORTED_LANGUAGES.rst

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.

The variables set through the VERSION, COMPAT_VERSION, SPDX_LICENSE, DESCRIPTION and HOMEPAGE_URL options are intended for use as default values in package metadata and documentation. The :command:export and :command:install commands use these accordingly when generating |CPS| package descriptions.

.. _Code Injection:

Code Injection ^^^^^^^^^^^^^^

A number of variables can be defined by the user to specify files to include at different points during the execution of the project() command. The following outlines the steps performed during a project() call:

  • .. versionadded:: 3.15 For every project() call regardless of the project name, include the file(s) and module(s) named by :variable:CMAKE_PROJECT_INCLUDE_BEFORE, if set.

  • .. versionadded:: 3.17 If the project() command specifies <PROJECT-NAME> as its project name, include the file(s) and module(s) named by :variable:CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE, if set.

  • Set the various project-specific variables detailed in the Synopsis_ and Options_ sections above.

  • For the very first project() call only:

    • If :variable:CMAKE_TOOLCHAIN_FILE is set, read it at least once. It may be read multiple times and it may also be read again when enabling languages later (see below).

    • Set the variables describing the host and target platforms. Language-specific variables might or might not be set at this point. On the first run, the only language-specific variables that might be defined are those a toolchain file may have set. On subsequent runs, language-specific variables cached from a previous run may be set.

    • .. versionadded:: 3.24 Include each file listed in :variable:CMAKE_PROJECT_TOP_LEVEL_INCLUDES, if set. The variable is ignored by CMake thereafter.

  • Enable any languages specified in the call, or the default languages if none were provided. The toolchain file may be re-read when enabling a language for the first time.

  • .. versionadded:: 3.15 For every project() call regardless of the project name, include the file(s) and module(s) named by :variable:CMAKE_PROJECT_INCLUDE, if set.

  • If the project() command specifies <PROJECT-NAME> as its project name, include the file(s) and module(s) named by :variable:CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE, if set.

Usage ^^^^^

The top-level CMakeLists.txt file for a project must contain a 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 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 and for this reason the project() command will issue a warning if this order is not kept. See also policy :policy:CMP0000.

.. |CPS| replace:: Common Package Specification