project

Задаёт имя проекта.

Синопсис

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>...])

Задаёт имя проекта и сохраняет его в переменной PROJECT_NAME. При вызове из корневого CMakeLists.txt также сохраняет имя проекта в переменной CMAKE_PROJECT_NAME.

Также задаёт переменные:

PROJECT_SOURCE_DIR, <PROJECT-NAME>_SOURCE_DIR

Абсолютный путь к исходному каталогу проекта.

PROJECT_BINARY_DIR, <PROJECT-NAME>_BINARY_DIR

Абсолютный путь к каталогу сборки проекта.

PROJECT_IS_TOP_LEVEL, <PROJECT-NAME>_IS_TOP_LEVEL

Добавлено в версии 3.21.

Логическое значение, указывающее, является ли проект корневым.

Дополнительные переменные задаются необязательными аргументами, описанными ниже в разделе Параметры. Если параметр не указан, соответствующая переменная устанавливается в пустую строку.

Обратите внимание, что переменные вида <name>_SOURCE_DIR и <name>_BINARY_DIR могут задаваться и другими командами до вызова project() (например, см. команду FetchContent_MakeAvailable()). Проектам не следует рассчитывать на то, что <PROJECT-NAME>_SOURCE_DIR или <PROJECT-NAME>_BINARY_DIR будут иметь определённое значение вне области видимости вызова project() или одной из его дочерних областей видимости.

Параметры

Доступны следующие параметры:

VERSION <version>

Необязательный параметр; его можно использовать только при условии, что политика CMP0048 установлена в NEW.

Принимает аргумент <version>, состоящий из неотрицательных целочисленных компонентов, например <major>[.<minor>[.<patch>[.<tweak>]]], и задаёт переменные

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

Добавлено в версии 3.12: Если команда project() вызывается из корневого CMakeLists.txt, версия также сохраняется в переменной CMAKE_PROJECT_VERSION.

COMPAT_VERSION <version>

Добавлено в версии 4.3.

Необязательный параметр; также требуется задать VERSION.

Принимает аргумент <version>, состоящий из неотрицательных целочисленных компонентов, например <major>[.<minor>[.<patch>[.<tweak>]]], и задаёт переменные

• PROJECT_COMPAT_VERSION, <PROJECT-NAME>_COMPAT_VERSION.

Если команда project() вызывается из корневого CMakeLists.txt, версия совместимости также сохраняется в переменной CMAKE_PROJECT_COMPAT_VERSION.

SPDX_LICENSE <license-string>

Добавлено в версии 4.3.

Необязательный параметр. Задаёт переменные

• PROJECT_SPDX_LICENSE, <PROJECT-NAME>_SPDX_LICENSE

в значение <license-string>, которое должно быть System Package Data Exchange (SPDX) выражением лицензии, описывающим лицензию или лицензии проекта в целом, включая документацию, ресурсы и другие материалы, распространяемые вместе с проектом, помимо программных артефактов. Список часто используемых лицензий и их идентификаторов см. в списке лицензий SPDX. Сведения о задании лицензии или лицензий для отдельных программных артефактов см. в свойстве SPDX_LICENSE.

Примечание

Лицензия проекта не используется для инициализации свойства SPDX_LICENSE отдельных целей. Это позволяет использовать лицензию пакета и лицензию компонента по умолчанию, задаваемые при экспорте сведений о пакете. Эти сведения используются только при экспорте в формате Common Package Specification.

В некоторых случаях лицензия проекта наследуется как лицензия пакета. Дополнительные сведения см. в описании параметра PROJECT и соответствующей документации команд export() и install().

DESCRIPTION <description-string>

Добавлено в версии 3.9.

Необязательный параметр. Задаёт переменные

• PROJECT_DESCRIPTION, <PROJECT-NAME>_DESCRIPTION

в значение <description-string>. Рекомендуется, чтобы это описание было относительно коротким — обычно не более нескольких слов.

Если команда project() вызывается из корневого CMakeLists.txt, описание также сохраняется в переменной CMAKE_PROJECT_DESCRIPTION.

Добавлено в версии 3.12: Добавлена переменная <PROJECT-NAME>_DESCRIPTION.

HOMEPAGE_URL <url-string>

Добавлено в версии 3.12.

Необязательный параметр. Задаёт переменные

• PROJECT_HOMEPAGE_URL, <PROJECT-NAME>_HOMEPAGE_URL

в значение <url-string>, которое должно быть каноническим URL-адресом домашней страницы проекта.

Если команда project() вызывается из корневого CMakeLists.txt, URL-адрес также сохраняется в переменной CMAKE_PROJECT_HOMEPAGE_URL.

LANGUAGES <language-name>...

Необязательный параметр. В соответствии с первой, краткой формой записи его можно указать и без ключевого слова LANGUAGES.

Выбирает языки программирования, необходимые для сборки проекта.

Поддерживаются следующие языки:

C

CXX

C++

CSharp

Добавлено в версии 3.8.

C#

CUDA

Добавлено в версии 3.8.

OBJC

Добавлено в версии 3.16.

Objective-C

OBJCXX

Добавлено в версии 3.16.

Objective-C++

Fortran

HIP

Добавлено в версии 3.21.

ISPC

Добавлено в версии 3.18.

Swift

Добавлено в версии 3.15.

ASM

Язык ассемблера, поддерживаемый компилятором C.

Если включается ASM, укажите его последним, чтобы CMake мог проверить, поддерживает ли компилятор C или CXX язык ассемблера.

ASM_NASM

Netwide Assembler

ASM_MARMASM

Добавлено в версии 3.26.

Ассемблер Microsoft (ARM, ARM64)

ASM_MASM

Ассемблер Microsoft (x86, x64)

ASM_POASM

Добавлено в версии 4.4.

Ассемблер из набора инструментов Pelles C.

ASM-ATT

По умолчанию включаются C и CXX, если параметры языков не заданы. Укажите язык NONE или используйте ключевое слово LANGUAGES без перечисления языков, чтобы не включать ни один язык.

Переменные, задаваемые параметрами VERSION, COMPAT_VERSION, SPDX_LICENSE, DESCRIPTION и HOMEPAGE_URL, предназначены для использования в качестве значений по умолчанию в метаданных пакета и документации. Команды export() и install() используют их соответствующим образом при создании описаний пакетов в формате Common Package Specification.

Внедрение кода

Пользователь может задать ряд переменных, чтобы указать файлы для подключения на разных этапах выполнения команды project(). Ниже перечислены шаги, выполняемые при вызове project():

• Добавлено в версии 3.15: При каждом вызове project(), независимо от имени проекта, подключаются файлы и модули, указанные в CMAKE_PROJECT_INCLUDE_BEFORE, если переменная задана.

• Добавлено в версии 3.17: Если в команде project() в качестве имени проекта указано <PROJECT-NAME>, подключаются файлы и модули, указанные в CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE, если переменная задана.

• Задаются различные переменные проекта, описанные выше в разделах Синопсис и Параметры.

• Только при первом вызове project():

  • Если задана переменная CMAKE_TOOLCHAIN_FILE, её содержимое считывается как минимум один раз. Файл может считываться несколько раз, а также повторно при последующем включении языков (см. ниже).
  • Задаются переменные, описывающие платформы хоста и целевую платформу. Переменные, относящиеся к языкам, на этом этапе могут быть заданы, а могут и не быть. При первом запуске могут быть определены только те переменные, относящиеся к языкам, которые заданы файлом цепочки инструментов. При последующих запусках могут быть заданы переменные, относящиеся к языкам, сохранённые в кэше при предыдущем запуске.

  • Добавлено в версии 3.24: Подключается каждый файл из списка CMAKE_PROJECT_TOP_LEVEL_INCLUDES, если переменная задана. В дальнейшем CMake игнорирует эту переменную.

• Включаются языки, указанные при вызове, либо языки по умолчанию, если ни один язык не задан. При первом включении языка файл цепочки инструментов может быть считан повторно.

• Добавлено в версии 3.15: При каждом вызове project(), независимо от имени проекта, подключаются файлы и модули, указанные в CMAKE_PROJECT_INCLUDE, если переменная задана.

• Если в команде project() в качестве имени проекта указано <PROJECT-NAME>, подключаются файлы и модули, указанные в CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE, если переменная задана.

Использование

Файл CMakeLists.txt верхнего уровня проекта должен содержать явный непосредственный вызов команды project(); загрузки через команду include() недостаточно. Если такого вызова нет, CMake выдаст предупреждение и будет считать, что в начале файла находится project(Project), чтобы включить языки по умолчанию (C и CXX).