cmake-language(7)

• Организация
  • Директории
  • Скрипты
  • Модули
• Синтаксис
  • Кодировка
  • Файлы исходного кода
  • Вызовы команд
  • Аргументы команд
    • Аргумент в скобках
    • Аргумент в кавычках
    • Необработанный аргумент
  • Последовательности экранирования
  • Ссылок на переменные
  • Комментарии
    • Комментарий в скобках
    • Однострочный комментарий
• Структуры управления
  • Условные блоки
  • Циклы
  • Определения команд
• Переменные
• Списки

Организация

Файлы входных данных CMake написаны на языке CMake в файлах исходного кода, имеющих имена CMakeLists.txt или заканчивающихся на .cmake.

Файлы исходного кода языка CMake в проекте организованы в:

• Директории (CMakeLists.txt),
• Скрипты (<script>.cmake), и
• Модули (<module>.cmake).

Директории

При обработке CMake дерева исходного кода проекта, точкой входа является файл исходного кода, называемый CMakeLists.txt в директории исходного кода верхнего уровня. Этот файл может содержать полное описание сборки или использовать команду add_subdirectory() для добавления поддиректорий в процесс сборки. Каждая поддиректория, добавленная с помощью этой команды, должна также содержать файл CMakeLists.txt в качестве точки входа в эту директорию. Для каждой директории исходного кода, чей файл CMakeLists.txt обрабатывается, CMake генерирует соответствующую директорию в дереве сборки, которая будет служить рабочей и выходной директорией по умолчанию.

Скрипты

Индивидуальный файл исходного кода <script>.cmake может быть обработан в режиме скрипта, используя утилиту командной строки cmake(1) с параметром -P. Режим скрипта просто выполняет команды в заданном файле исходного кода языка CMake и не генерирует систему сборки. Он не допускает команд CMake, которые определяют цели сборки или действия.

Модули

Код языка CMake в директориях Директории или скриптах Скрипты может использовать команду include() для загрузки файла исходного кода <module>.cmake в область видимости включающего контекста. См. руководство cmake-modules(7) для документации модулей, включённых в дистрибутив CMake. Деревья исходного кода проектов также могут предоставлять свои собственные модули и указывать их расположение(я) в переменной CMAKE_MODULE_PATH.

Синтаксис

Кодировка

Файл исходного кода языка CMake может быть написан в текстовом формате 7-битного ASCII для максимальной переносимости на всех поддерживаемых платформах. Разделители строк могут быть закодированы как \n или \r\n, но будут преобразованы в \n при чтении файлов.

Обратите внимание, что реализация поддерживает 8-битные символы, поэтому файлы исходного кода могут быть закодированы в UTF-8 на платформах с поддержкой этой кодировки в системных API. Кроме того, CMake 3.2 и выше поддерживают файлы исходного кода, закодированные в UTF-8 в Windows (используя UTF-16 для вызовов системных API). Более того, CMake 3.0 и выше поддерживают ведущий UTF-8 Byte-Order Mark в файлах исходного кода.

Файлы исходного кода

Файл исходного кода языка CMake состоит из нуля или более вызовов команд, разделенных символами новой строки и необязательными пробелами и комментариями:

file         ::=  file_element*
file_element ::=  command_invocation line_ending |
                  (bracket_comment|space)* line_ending
line_ending  ::=  line_comment? newline
space        ::=  <match '[ \t]+'>
newline      ::=  <match '\n'>

Обратите внимание, что любая строка исходного файла, не находящаяся внутри аргументов команд или комментария в скобках, может заканчиваться однострочным комментарием.

Вызовы команд

Вызов команды — это имя, за которым следуют заключённые в скобки аргументы, разделенные пробелами:

command_invocation  ::=  space* identifier space* '(' arguments ')'
identifier          ::=  <match '[A-Za-z_][A-Za-z0-9_]*'>
arguments           ::=  argument? separated_arguments*
separated_arguments ::=  separation+ argument? |
                         separation* '(' arguments ')'
separation          ::=  space | line_ending

Например:

add_executable(hello world.c)

Имена команд нечувствительны к регистру. Вложенные необработанные скобки в аргументах должны быть сбалансированы. Каждый ( или ) передается вызову команды как буквальный необработанный аргумент. Это может быть использовано в вызовах команды if() для заключения условий. Например:

if(FALSE AND (FALSE OR TRUE)) # evaluates to FALSE

Аргументы команд

Существует три типа аргументов в вызовах команд:

argument ::=  bracket_argument | quoted_argument | unquoted_argument

Аргумент в скобках

Аргумент в скобках, вдохновлённый синтаксисом длинных скобок Lua, заключает содержимое в открывающие и закрывающие скобки одинаковой длины:

bracket_argument ::=  bracket_open bracket_content bracket_close
bracket_open     ::=  '[' '='* '['
bracket_content  ::=  <any text not containing a bracket_close with
                       the same number of '=' as the bracket_open>
bracket_close    ::=  ']' '='* ']'

Открывающая скобка записывается как [ , за которой следуют нуль или более =, а затем [. Соответствующая закрывающая скобка записывается как ] , за которой следуют такое же количество = и ]. Скобки не вложены. Всегда может быть выбран уникальный размер открывающей и закрывающей скобок, чтобы содержать закрывающие скобки других размеров.

Содержимое аргумента в скобках состоит из всего текста между открывающей и закрывающей скобками, за исключением того, что одна строка, следующая непосредственно за открывающей скобкой, если она есть, игнорируется. Никакой оценки заключённого содержимого, например последовательностей экранирования или ссылок на переменные, не выполняется. Аргумент в скобках всегда передается в вызов команды ровно как один аргумент.

Например:

message([=[
This is the first line in a bracket argument with bracket length 1.
No \-escape sequences or ${variable} references are evaluated.
This is always one argument even though it contains a ; character.
The text does not end on a closing bracket of length 0 like ]].
It does end in a closing bracket of length 1.
]=])

Аргумент в кавычках

Аргумент в кавычках заключает содержимое в открывающие и закрывающие двойные кавычки:

quoted_argument     ::=  '"' quoted_element* '"'
quoted_element      ::=  <any character except '\' or '"'> |
                         escape_sequence |
                         quoted_continuation
quoted_continuation ::=  '\' newline

Содержимое аргумента в кавычках состоит из всего текста между открывающими и закрывающими кавычками. Оба экранирования и ссылки на переменные оцениваются. Аргумент в кавычках всегда передается в вызов команды ровно как один аргумент.

Например:

message("This is a quoted argument containing multiple lines.
This is always one argument even though it contains a ; character.
Both \\-escape sequences and ${variable} references are evaluated.
The text does not end on an escaped double-quote like \".
It does end in an unescaped double quote.
")

Последний \ в любой строке, оканчивающейся нечетным количеством обратных слэшей, обрабатывается как продолжение строки и игнорируется вместе со следующим символом новой строки. Например:

message("\
This is the first line of a quoted argument. \
In fact it is the only line but since it is long \
the source code uses line continuation.\
")

Необработанный аргумент

Необработанный аргумент не заключён в никакой синтаксис. Он не может содержать пробелов, (, ), #, ", или \ , за исключением случаев, когда они экранированы обратным слэшем:

unquoted_argument ::=  unquoted_element+ | unquoted_legacy
unquoted_element  ::=  <any character except whitespace or one of '()#"\'> |
                       escape_sequence
unquoted_legacy   ::=  <see note in text>

Содержимое необработанного аргумента состоит из всего текста в непрерывном блоке разрешённых или экранированных символов. Оба экранирования и ссылки на переменные оцениваются. Результирующее значение делится таким же образом, как списки делятся на элементы. Каждый непустой элемент передается вызову команды как аргумент. Следовательно, необработанный аргумент может быть передан вызову команды как ноль или более аргументов.

Например:

foreach(arg
    NoSpace
    Escaped\ Space
    This;Divides;Into;Five;Arguments
    Escaped\;Semicolon
    )
  message("${arg}")
endforeach()

Последовательности экранирования

Последовательность экранирования — это \ за которым следует один символ:

escape_sequence  ::=  escape_identity | escape_encoded | escape_semicolon
escape_identity  ::=  '\' <match '[^A-Za-z0-9;]'>
escape_encoded   ::=  '\t' | '\r' | '\n'
escape_semicolon ::=  '\;'

\ за которым следует не буквенно-цифровой символ, просто кодирует буквенный символ без интерпретации его как синтаксиса. \t, \r, или \n кодируют, соответственно, символ табуляции, возврата каретки или новой строки. \; вне любых Ссылок на переменные кодирует себя, но может использоваться в Необработанном аргументе для кодирования ; без разделения значения аргумента на нём. \; внутри Ссылок на переменные кодирует буквенный символ ;. (См. также политику CMP0053 документацию для исторических соображений.)

Ссылки на переменные

Ссылка на переменную имеет вид ${variable_name} и вычисляется внутри Аргумента в кавычках или Необработанного аргумента. Ссылка на переменную заменяется значением переменной или пустой строкой, если переменная не задана. Ссылки на переменные могут быть вложенными и вычисляются изнутри наружу, например, ${outer_${inner_variable}_variable}.

Буквальные ссылки на переменные могут состоять из буквенно-цифровых символов, символов /_.+-, и Последовательностей экранирования. Вложенные ссылки могут использоваться для вычисления переменных любого имени. (См. также политику CMP0053 документацию для исторических соображений.)

Раздел Переменные описывает область имен переменных и как их значения устанавливаются.

Ссылка на переменную среды имеет вид $ENV{VAR} и вычисляется в тех же контекстах, что и обычная ссылка на переменную.

Комментарии

Комментарий начинается с символа #, который не находится внутри Аргумента в скобках, Аргумента в кавычках, или экранирован с помощью \ как часть Необработанного аргумента. Существует два типа комментариев: Комментарий в скобках и Комментарий в строке.

Комментарий в скобках

# сразу за Аргументом в скобках образует комментарий в скобках, состоящий из всего содержимого скобок:

bracket_comment ::=  '#' bracket_argument

Например:

#[[This is a bracket comment.
It runs until the close bracket.]]
message("First Argument\n" #[[Bracket Comment]] "Second Argument")

Комментарий в строке

# не непосредственно за Аргументом в скобках образует комментарий в строке, который продолжается до конца строки:

line_comment ::=  '#' <any text not starting in a bracket_argument
                       and not containing a newline>

Например:

# This is a line comment.
message("First Argument\n" # This is a line comment :)
        "Second Argument") # This is a line comment.

Структуры управления

Условные блоки

Команды if()/elseif()/else()/endif() разделяют блоки кода, которые будут выполняться условно.

Циклы

Команды foreach()/endforeach() и while()/endwhile() разделяют блоки кода, которые будут выполняться в цикле. Внутри таких блоков команда break() может использоваться для преждевременного завершения цикла, а команда continue() может использоваться для немедленного перехода к следующей итерации.

Определения команд

Команды macro()/endmacro() и function()/endfunction() разделяют блоки кода, которые будут записаны для последующего вызова в качестве команд.

Переменные

Переменные — это базовая единица хранения в языке CMake. Их значения всегда являются строкового типа, хотя некоторые команды могут интерпретировать строки как значения других типов. Команды set() и unset() явно устанавливают или сбрасывают переменную, но и другие команды имеют семантику, которая изменяет переменные. Имена переменных регистрозависимые и могут состоять из почти любого текста, но мы рекомендуем использовать только буквенно-цифровые символы плюс _ и -.

Переменные имеют динамическую область действия. Каждое «установление» или «сброс» переменной создает привязку в текущей области видимости:

Область действия функции

Определения команд, созданные командой function(), создают команды, которые при вызове обрабатывают записанные команды в новой области видимости привязки переменных. Переменная «установление» или «сброс» привязывается в этой области видимости и видна для текущей функции и любых вложенных вызовов в ней, но не после возврата функции.

Область действия каталога

Каждый из каталогов в дереве исходных файлов имеет свои привязки переменных. Перед обработкой файла CMakeLists.txt для каталога CMake копирует все привязки переменных, в настоящее время определенные в родительском каталоге, если таковые имеются, для инициализации новой области видимости каталога. CMake скрипты при обработке с помощью cmake -P привязывают переменные в одной области видимости «каталога».

Переменная «установка» или «сброс», не находящаяся внутри вызова функции, привязывается к текущей области видимости каталога.

Постоянный кэш

CMake хранит отдельный набор переменных «кэша» или «записей кэша», значения которых сохраняются при многократных запусках в дереве сборки проекта. У записей кэша изолированная область видимости, изменяемая только по явным запросам, например, с помощью опции CACHE команд set() и unset().

При вычислении ссылок на переменные CMake сначала ищет привязку в стеке вызовов функций, если таковой имеется, а затем возвращается к привязке в текущей области видимости каталога, если таковая имеется. Если найдена привязка «установка», используется её значение. Если найдена привязка «сброс» или привязка не найдена, CMake затем ищет запись кэша. Если запись кэша найдена, используется её значение. В противном случае ссылка на переменную вычисляется как пустая строка.

Руководство cmake-variables(7) описывает множество переменных, предоставляемых CMake или имеющих значение для CMake при установке кодом проекта.

Списки

Хотя все значения в CMake хранятся как строки, строка может обрабатываться как список в определенных контекстах, например, при вычислении Необработанного аргумента. В таких контекстах строка делится на элементы списка путем разделения на символы ;, не следующие за нечётным числом символов [ и ], и не предшествующих сразу символом \. Последовательность \; не разделяет значение, а заменяется на ; в результирующем элементе.

Список элементов представлен строкой, полученной путём конкатенации элементов, разделённых ;. Например, команда set() сохраняет несколько значений в целевую переменную в виде списка:

set(srcs a.c b.c c.c) # sets "srcs" to "a.c;b.c;c.c"

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

set(x a "b;c") # sets "x" to "a;b;c", not "a;b\;c"