# 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`

  Added in version 3.21.

  Boolean value indicating whether the project is top-level.

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.

## Options

The options are:

`VERSION <version>`

  Optional; may not be used unless 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

  - `PROJECT_VERSION`, `<PROJECT-NAME>_VERSION`

  - `PROJECT_VERSION_MAJOR`, `<PROJECT-NAME>_VERSION_MAJOR`

  - `PROJECT_VERSION_MINOR`, `<PROJECT-NAME>_VERSION_MINOR`

  - `PROJECT_VERSION_PATCH`, `<PROJECT-NAME>_VERSION_PATCH`

  - `PROJECT_VERSION_TWEAK`, `<PROJECT-NAME>_VERSION_TWEAK`.

  Added in version 3.12: When the `project()` command is called from the top-level `CMakeLists.txt`, then the version is also stored in the variable `CMAKE_PROJECT_VERSION`.

`DESCRIPTION <project-description-string>`

  Added in version 3.9.

  Optional. Sets the variables

  - `PROJECT_DESCRIPTION`, `<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.

  When the `project()` command is called from the top-level `CMakeLists.txt`, then the description is also stored in the variable `CMAKE_PROJECT_DESCRIPTION`.

  Added in version 3.12: Added the `<PROJECT-NAME>_DESCRIPTION` variable.

`HOMEPAGE_URL <url-string>`

  Added in version 3.12.

  Optional. Sets the variables

  - `PROJECT_HOMEPAGE_URL`, `<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 `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.

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`.

> Added in version 3.8: Added `CSharp` and `CUDA` support.

> Added in version 3.15: Added `Swift` support.

> Added in version 3.16: Added `OBJC` and `OBJCXX` support.

> Added in version 3.18: Added `ISPC` support.

> Added in version 3.21: Added `HIP` support.

> Added 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:

- Added in version 3.15: For every `project()` call regardless of the project name, include the file(s) and module(s) named by `CMAKE_PROJECT_INCLUDE_BEFORE`, if set.

- Added in version 3.17: If the `project()` command specifies `<PROJECT-NAME>` as its project name, include the file(s) and module(s) named by `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 `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.

  - Added 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.

- Added in version 3.15: For every `project()` call regardless of the project name, include the file(s) and module(s) named by `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 `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 `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`.