cmake-language(7)

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

Организация

Файлы ввода CMake написаны на языке «CMake Language» в исходных файлах с именем CMakeLists.txt или с расширением имени файла .cmake.

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

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

Директории

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

Скрипты

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

Модули

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

Синтаксис

Кодировка

Файл исходного кода CMake Language можно записать в текстовом формате 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 Language состоит из нуля или более вызовов команд, разделённых символами новой строки и, необязательно, пробелами и комментариями:

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     ::=  '[' '='{len} '['
bracket_content  ::=  <any text not containing a bracket_close
                       of the same {len} as the bracket_open>
bracket_close    ::=  ']' '='{len} ']'

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

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

Например:

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"