1project
2-------
3
4Set the name of the project.
5
6Synopsis
7^^^^^^^^
8
9.. code-block:: cmake
10
11 project(<PROJECT-NAME> [<language-name>...])
12 project(<PROJECT-NAME>
13         [VERSION <major>[.<minor>[.<patch>[.<tweak>]]]]
14         [DESCRIPTION <project-description-string>]
15         [HOMEPAGE_URL <url-string>]
16         [LANGUAGES <language-name>...])
17
18Sets the name of the project, and stores it in the variable
19:variable:`PROJECT_NAME`. When called from the top-level
20``CMakeLists.txt`` also stores the project name in the
21variable :variable:`CMAKE_PROJECT_NAME`.
22
23Also sets the variables:
24
25:variable:`PROJECT_SOURCE_DIR`, :variable:`<PROJECT-NAME>_SOURCE_DIR`
26  Absolute path to the source directory for the project.
27
28:variable:`PROJECT_BINARY_DIR`, :variable:`<PROJECT-NAME>_BINARY_DIR`
29  Absolute path to the binary directory for the project.
30
31:variable:`PROJECT_IS_TOP_LEVEL`, :variable:`<PROJECT-NAME>_IS_TOP_LEVEL`
32  .. versionadded:: 3.21
33
34  Boolean value indicating whether the project is top-level.
35
36Further variables are set by the optional arguments described in the following.
37If any of these arguments is not used, then the corresponding variables are
38set to the empty string.
39
40Options
41^^^^^^^
42
43The options are:
44
45``VERSION <version>``
46  Optional; may not be used unless policy :policy:`CMP0048` is
47  set to ``NEW``.
48
49  Takes a ``<version>`` argument composed of non-negative integer components,
50  i.e. ``<major>[.<minor>[.<patch>[.<tweak>]]]``,
51  and sets the variables
52
53  * :variable:`PROJECT_VERSION`,
54    :variable:`<PROJECT-NAME>_VERSION`
55  * :variable:`PROJECT_VERSION_MAJOR`,
56    :variable:`<PROJECT-NAME>_VERSION_MAJOR`
57  * :variable:`PROJECT_VERSION_MINOR`,
58    :variable:`<PROJECT-NAME>_VERSION_MINOR`
59  * :variable:`PROJECT_VERSION_PATCH`,
60    :variable:`<PROJECT-NAME>_VERSION_PATCH`
61  * :variable:`PROJECT_VERSION_TWEAK`,
62    :variable:`<PROJECT-NAME>_VERSION_TWEAK`.
63
64  .. versionadded:: 3.12
65    When the ``project()`` command is called from the top-level
66    ``CMakeLists.txt``, then the version is also stored in the variable
67    :variable:`CMAKE_PROJECT_VERSION`.
68
69``DESCRIPTION <project-description-string>``
70  .. versionadded:: 3.9
71
72  Optional.
73  Sets the variables
74
75  * :variable:`PROJECT_DESCRIPTION`, :variable:`<PROJECT-NAME>_DESCRIPTION`
76
77  to ``<project-description-string>``.
78  It is recommended that this description is a relatively short string,
79  usually no more than a few words.
80
81  When the ``project()`` command is called from the top-level ``CMakeLists.txt``,
82  then the description is also stored in the variable :variable:`CMAKE_PROJECT_DESCRIPTION`.
83
84  .. versionadded:: 3.12
85    Added the ``<PROJECT-NAME>_DESCRIPTION`` variable.
86
87``HOMEPAGE_URL <url-string>``
88  .. versionadded:: 3.12
89
90  Optional.
91  Sets the variables
92
93  * :variable:`PROJECT_HOMEPAGE_URL`, :variable:`<PROJECT-NAME>_HOMEPAGE_URL`
94
95  to ``<url-string>``, which should be the canonical home URL for the project.
96
97  When the ``project()`` command is called from the top-level ``CMakeLists.txt``,
98  then the URL also is stored in the variable :variable:`CMAKE_PROJECT_HOMEPAGE_URL`.
99
100``LANGUAGES <language-name>...``
101  Optional.
102  Can also be specified without ``LANGUAGES`` keyword per the first, short signature.
103
104  Selects which programming languages are needed to build the project.
105  Supported languages include ``C``, ``CXX`` (i.e.  C++), ``CUDA``,
106  ``OBJC`` (i.e. Objective-C), ``OBJCXX``, ``Fortran``, ``HIP``, ``ISPC``, and ``ASM``.
107  By default ``C`` and ``CXX`` are enabled if no language options are given.
108  Specify language ``NONE``, or use the ``LANGUAGES`` keyword and list no languages,
109  to skip enabling any languages.
110
111  .. versionadded:: 3.8
112    Added ``CUDA`` support.
113
114  .. versionadded:: 3.16
115    Added ``OBJC`` and ``OBJCXX`` support.
116
117  .. versionadded:: 3.18
118    Added ``ISPC`` support.
119
120  If enabling ``ASM``, list it last so that CMake can check whether
121  compilers for other languages like ``C`` work for assembly too.
122
123The variables set through the ``VERSION``, ``DESCRIPTION`` and ``HOMEPAGE_URL``
124options are intended for use as default values in package metadata and documentation.
125
126Code Injection
127^^^^^^^^^^^^^^
128
129If the :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` or
130:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE` variables are set,
131the files they point to will be included as the first step of the
132``project()`` command.
133If both are set, then :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` will be
134included before :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`.
135
136If the :variable:`CMAKE_PROJECT_INCLUDE` or
137:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE` variables are set, the files
138they point to will be included as the last step of the ``project()`` command.
139If both are set, then :variable:`CMAKE_PROJECT_INCLUDE` will be included before
140:variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`.
141
142.. versionadded:: 3.15
143  Added the ``CMAKE_PROJECT_INCLUDE`` and ``CMAKE_PROJECT_INCLUDE_BEFORE``
144  variables.
145
146.. versionadded:: 3.17
147  Added the ``CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE`` variable.
148
149Usage
150^^^^^
151
152The top-level ``CMakeLists.txt`` file for a project must contain a
153literal, direct call to the ``project()`` command; loading one
154through the :command:`include` command is not sufficient.  If no such
155call exists, CMake will issue a warning and pretend there is a
156``project(Project)`` at the top to enable the default languages
157(``C`` and ``CXX``).
158
159.. note::
160  Call the ``project()`` command near the top of the top-level
161  ``CMakeLists.txt``, but *after* calling :command:`cmake_minimum_required`.
162  It is important to establish version and policy settings before invoking
163  other commands whose behavior they may affect.
164  See also policy :policy:`CMP0000`.
165