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"