project¶
Set the name of the project.
Synopsis¶
project(<PROJECT-NAME> [<language-name>...])
project(<PROJECT-NAME>
[VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
[DESCRIPTION <project-description-string>]
[HOMEPAGE_URL <url-string>]
[LANGUAGES <language-name>...])
Sets the name of the project, and stores it in the variable
PROJECT_NAME
. When called from the top-level
CMakeLists.txt
also stores the project name in the
variable CMAKE_PROJECT_NAME
.
Also sets the variables:
PROJECT_SOURCE_DIR
,<PROJECT-NAME>_SOURCE_DIR
Absolute path to the source directory for the project.
PROJECT_BINARY_DIR
,<PROJECT-NAME>_BINARY_DIR
Absolute path to the binary directory for the project.
PROJECT_IS_TOP_LEVEL
,<PROJECT-NAME>_IS_TOP_LEVEL
New in version 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
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.
Changed in version 3.30.4: If the variables <PROJECT-NAME>_SOURCE_DIR
,
<PROJECT-NAME>_BINARY_DIR
, or <PROJECT-NAME>_IS_TOP_LEVEL
are
already set as non-cache variables when project(<PROJECT-NAME> ...)
is called, the project()
command will overwrite the previous values.
Options¶
The options are:
VERSION <version>
Optional; may not be used unless policy
CMP0048
is set toNEW
.Takes a
<version>
argument composed of non-negative integer components, i.e.<major>[.<minor>[.<patch>[.<tweak>]]]
, and sets the variablesNew in version 3.12: When the
project()
command is called from the top-levelCMakeLists.txt
, then the version is also stored in the variableCMAKE_PROJECT_VERSION
.DESCRIPTION <project-description-string>
New in version 3.9.
Optional. Sets the variables
to
<project-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-levelCMakeLists.txt
, then the description is also stored in the variableCMAKE_PROJECT_DESCRIPTION
.New in version 3.12: Added the
<PROJECT-NAME>_DESCRIPTION
variable.HOMEPAGE_URL <url-string>
New in version 3.12.
Optional. Sets the variables
to
<url-string>
, which should be the canonical home URL for the project.When the
project()
command is called from the top-levelCMakeLists.txt
, then the URL also is stored in the variableCMAKE_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.
Supported languages are C
, CXX
(i.e. C++), CSharp
(i.e. C#), CUDA
,
OBJC
(i.e. Objective-C), OBJCXX
(i.e. Objective-C++), Fortran
, HIP
,
ISPC
, Swift
, ASM
, ASM_NASM
, ASM_MARMASM
, ASM_MASM
, and ASM-ATT
.
New in version 3.8: Added
CSharp
andCUDA
support.New in version 3.15: Added
Swift
support.New in version 3.16: Added
OBJC
andOBJCXX
support.New in version 3.18: Added
ISPC
support.New in version 3.21: Added
HIP
support.New in version 3.26: Added
ASM_MARMASM
support.
If enabling ASM
, list it last so that CMake can check whether
compilers for other languages like C
work for assembly too.
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
, DESCRIPTION
and HOMEPAGE_URL
options are intended for use as default values in package metadata and documentation.
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:
New in version 3.15: For every
project()
call regardless of the project name, include the file(s) and module(s) named byCMAKE_PROJECT_INCLUDE_BEFORE
, if set.New in version 3.17: If the
project()
command specifies<PROJECT-NAME>
as its project name, include the file(s) and module(s) named byCMAKE_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
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.
New in version 3.24: Include each file listed in
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.
New in version 3.15: For every
project()
call regardless of the project name, include the file(s) and module(s) named byCMAKE_PROJECT_INCLUDE
, if set.If the
project()
command specifies<PROJECT-NAME>
as its project name, include the file(s) and module(s) named byCMAKE_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 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 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 CMP0000
.