CMake-команда project

Сигнатура і опис

project(<PROJECT-NAME> [<language-name>...])
project(<PROJECT-NAME>
        [VERSION <головна версія>[.<другорядна версія>[.<версія патчу>[.<версія варіації>]]]]
        [DESCRIPTION <рядок опису проекту>]
        [HOMEPAGE_URL <url-string>]
        [LANGUAGES <language-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) змінна містить булеве значення, яке вказує чи даний проект являє собою проект найвищого рівня.

Подальші змінні встановлюються необов’язковими аргументами які описані далі. Якщо будь-який з цих аргументів не використовується, тоді відповідна змінна буде містити пустий рядок символів.

Параметри

• VERSION <версія> необов’язковий параметр. Можна не вказувати, якщо тільки не встановлена політика https://cmake.org/cmake/help/latest/policy/CMP0048.html#policy:CMP0048 у значення NEW.

  Впровадження починаючи з версії 3.12: Коли команда project() викликається з файлу CMakeLists.txt найвищого рівня, тоді версія також зберігається у змінній CMAKE_PROJECT_VERSION.

  Приймає значення <версія> компоненти якого складаються з позитивних цілих чисел, тобто <головна версія>[.<другорядна версія>[.<версія патчу>[.<версія варіації>]]] і встановлює наступні змінні

  • 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
• DESCRIPTION <рядок опису проекту> нововведення у версії 3.9.

  Необов’язковий параметр. Встановлює наступні змінні: PROJECT_DESCRIPTION і <PROJECT-NAME>_DESCRIPTION у передане значення <рядок опису проекту> даного параметру. Рекомендується, щоб передане значення опису проекту являло собою невеликий рядок символів, зазвичай не більше кількох слів.

  Якщо команда project() викликається з файлу CMakeLists.txt найвищого рівня, тоді опис також зберігається у змінній CMAKE_PROJECT_DESCRIPTION.

  Нововведення починаючи з версії 3.12: Додано змінну <PROJECT-NAME>_DESCRIPTION.

• HOMEPAGE_URL <рядок з URL> нововведення у версії 3.12. Необов’язковий параметр. Встановлює змінні PROJECT_HOMEPAGE_URL, <PROJECT-NAME>_HOMEPAGE_URL у передане значення параметру <рядок з URL>, яке повинно містити канонічний URL домашньої сторінки проекту. Коли команда project() викликається з файлу CMakeLists.txt найвищого рівня у директорії проекту, тоді значення даного URL також зберігається у змінній CMAKE_PROJECT_HMEPAGE_URL.
• LANGUAGES <назва використаної мови> необов’язковий параметр. Також може бути вказаним без ключового слова LANGUAGES з першою скороченою сигнатурою команди project().

  Обирає, які мови програмування необхідні для побудови проекту. Підтримувані мови включають у себе: C, CXX (тобто C++), CSharp (тобто C#), CUDA, OBJC (тобто Objective-C), OBJCXX (тобто Objective-C++), Fortran, HIP, ISPC, Swift, ASM, ASM_NASM, ASM_MARMASM, ASM_MASM і ASM_ATT.

  Нововведення у версії 3.8: Додано підтримку CSharp і CUDA

  Нововведення у версії 3.15: Додано підтримку Swift

  Нововведення у версії 3.16: Додано підтримку OBJC і OBJCXX

  Нововведення у версії 3.18: Додано підтримку ISPC

  Нововведення у версії 3.21: Додано підтримку HIP

  Нововведення у версії 3.26: Додано підтримку ASM_MARMASM

Під час використання ASM, необхідно вказувати дану мову останньою у списку отож CMake може перевірити чи компілятори для інших мов на подобі C працюють з асемблером також.

За умовчанням використовується значення C і CXX якщо не вказано жодної мови. Необхідно вказати значення NONE, або використати ключове слово LANGUAGES без списку мов щоб запобігти використанню компіляторів і/або інтерпретаторів будь-якої мови.

Змінні які встановлюються через параметри VERSION, DESCRIPTION і HOMEAGE_URL призначені для використання як значення за умовчанням для метаданих пакету і документації.

Ін’єкція коду

Множина змінних може бути визначеною користувачем для вказуванням файлів для підключення до різних файлів під час виклику команди project(). Наступний список відображає виконувані кроки під час виклику команди project().

• Нововведення у версії 3.13: Для кожного виклику команди project() незвадаючи на назву проекту, підключайте файл незва якого міститься у змінній CMAKE_PROJECT_INCLUDE_BEFORE, якщо така встановлена.
• Нововведення у версії 3.17: Якщо команда project() визначає <PROJECT-NAME> у якості назву проекту, підключайте файл назва якого міститься у змінній CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE_BEFORE, якщо така встановлена.
• Встановіть необхідні змінні які відносяться до проекту як попередньо описано у секції Сигнатура і опис і Параметри.
• Для найпершого виклику команди project():
  • Якщо встановлена змінна CMAKE_TOOLCHAIN_FILE, прочитай її хоча-б один раз. Вона може зчитуватись багато разів і також після увімкнення використання мов (детально описано нижче).
  • Встановіть змінні які описують цільову і платформу розробки. Змінні які відносяться до певних мов можуть бути встановленими або ні до цього моменту. Під час першого запуску, єдина специфічна для мови змінна, яка може бути визначеною файлом інструментарію (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() не є достатнім. Якщо виклику команди project() не існує в проекті, CMake згенерує відповідне попередження і опосередковано викличе команду project(Project) у файлі скрипта найвищого рівня, щоб увімкнути мови за умовчанням (C і CXX).

Зверніть увагу. Викликай команду project() поблизу верху скрипта CMakeLists.txt найвищого рівня, але після виклику cmake_minimum_required(). Важливо визначати версію і політику налаштувань перед викликом інших команд на поведінку яких може визначатись за допомогою неї і для цією цілі команда project() згенерує відповідне попередження якщо цей порядок не дотримано. Детальніше у політиці https://cmake.org/cmake/help/latest/policy/CMP0000.html#policy:CMP0000.

Приклад

Оригінал