cmake_path

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

Синтаксис

Conventions

Path Structure And Terminology

Normalization

Decomposition
  cmake_path(GET <path-var> ROOT_NAME <out-var>)
  cmake_path(GET <path-var> ROOT_DIRECTORY <out-var>)
  cmake_path(GET <path-var> ROOT_PATH <out-var>)
  cmake_path(GET <path-var> FILENAME <out-var>)
  cmake_path(GET <path-var> EXTENSION [LAST_ONLY] <out-var>)
  cmake_path(GET <path-var> STEM [LAST_ONLY] <out-var>)
  cmake_path(GET <path-var> RELATIVE_PART <out-var>)
  cmake_path(GET <path-var> PARENT_PATH <out-var>)

Query
  cmake_path(HAS_ROOT_NAME <path-var> <out-var>)
  cmake_path(HAS_ROOT_DIRECTORY <path-var> <out-var>)
  cmake_path(HAS_ROOT_PATH <path-var> <out-var>)
  cmake_path(HAS_FILENAME <path-var> <out-var>)
  cmake_path(HAS_EXTENSION <path-var> <out-var>)
  cmake_path(HAS_STEM <path-var> <out-var>)
  cmake_path(HAS_RELATIVE_PART <path-var> <out-var>)
  cmake_path(HAS_PARENT_PATH <path-var> <out-var>)
  cmake_path(IS_ABSOLUTE <path-var> <out-var>)
  cmake_path(IS_RELATIVE <path-var> <out-var>)
  cmake_path(IS_PREFIX <path-var> <input> [NORMALIZE] <out-var>)

Comparison
  cmake_path(COMPARE <input1> <op> <input2> <out-var>)

Modification
  cmake_path(SET <path-var> [NORMALIZE] <input>)
  cmake_path(APPEND <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
  cmake_path(APPEND_STRING <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])
  cmake_path(REMOVE_FILENAME <path-var> [OUTPUT_VARIABLE <out-var>])
  cmake_path(REPLACE_FILENAME <path-var> <input> [OUTPUT_VARIABLE <out-var>])
  cmake_path(REMOVE_EXTENSION <path-var> [LAST_ONLY] [OUTPUT_VARIABLE <out-var>])
  cmake_path(REPLACE_EXTENSION <path-var> [LAST_ONLY] <input> [OUTPUT_VARIABLE <out-var>])

Generation
  cmake_path(NORMAL_PATH <path-var> [OUTPUT_VARIABLE <out-var>])
  cmake_path(RELATIVE_PATH <path-var> [BASE_DIRECTORY <input>] [OUTPUT_VARIABLE <out-var>])
  cmake_path(ABSOLUTE_PATH <path-var> [BASE_DIRECTORY <input>] [NORMALIZE] [OUTPUT_VARIABLE <out-var>])

Native Conversion
  cmake_path(NATIVE_PATH <path-var> [NORMALIZE] <out-var>)
  cmake_path(CONVERT <input> TO_CMAKE_PATH_LIST <out-var> [NORMALIZE])
  cmake_path(CONVERT <input> TO_NATIVE_PATH_LIST <out-var> [NORMALIZE])

Hashing
  cmake_path(HASH <path-var> <out-var>)

Условные обозначения

В документации этой команды используются следующие условные обозначения:

<path-var>

Всегда является именем переменной. Для команд, принимающих <path-var> в качестве входных данных, переменная должна существовать и содержать один путь.

<input>

Строковый литерал, который может содержать путь, часть пути или несколько путей, разделённых специальным разделителем, в зависимости от команды. О том, как он интерпретируется, см. описание каждой команды.

<input>...

Ноль или более строковых аргументов-литералов.

<out-var>

Имя переменной, в которую будет записан результат команды.

Структура пути и терминология

Путь имеет следующую структуру (все компоненты необязательны, с некоторыми ограничениями):

root-name root-directory-separator (item-name directory-separator)* filename

root-name

Определяет корень в файловой системе с несколькими корнями (например, "C:" или "//myserver"). Необязателен.

root-directory-separator

Разделитель каталогов, который, если присутствует, указывает на то, что путь абсолютный. Если он отсутствует, а первый элемент, отличный от root-name, является item-name, путь относительный.

item-name

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

• Имя элемента, состоящее из одной точки ., — это имя каталога, обозначающее текущий каталог.
• Имя элемента, состоящее из двух точек .., — это имя каталога, обозначающее родительский каталог.

Приведённый выше шаблон (...)* указывает на то, что элементов может быть ноль или более, а несколько элементов разделяются символом directory-separator. Символы ()* не являются частью пути.

directory-separator

Единственный распознаваемый разделитель каталогов — символ косой черты /. Если этот символ повторяется, он рассматривается как один разделитель каталогов. Иными словами, /usr///////lib эквивалентно /usr/lib.

filename

У пути есть filename, если он не заканчивается на directory-separator. По сути, filename — это последний item-name пути, поэтому он также может быть жёсткой ссылкой, символической ссылкой или каталогом.

У filename может быть расширение. По умолчанию расширение определяется как подстрока, начинающаяся с самой левой точки (включая её) и продолжающаяся до конца filename. В командах, принимающих ключевое слово LAST_ONLY, LAST_ONLY изменяет интерпретацию: подстрока начинается с самой правой точки.

К указанной выше интерпретации применяются следующие исключения:

• Если первый символ в filename — точка, она игнорируется (то есть считается, что у filename, например ".profile", нет расширения).
• Если filename — это . или .., у него нет расширения.

Основа имени — это часть filename перед расширением.

Некоторые команды используют root-path. Это конкатенация root-name и root-directory-separator, один или оба компонента могут быть пустыми. relative-part обозначает полный путь без root-path.

Создание переменной пути

Хотя путь можно аккуратно создать с помощью обычной команды set(), рекомендуется использовать вместо неё cmake_path(SET), поскольку при необходимости она автоматически преобразует путь в требуемый формат. Подкоманда cmake_path(APPEND) также может подойти, если путь нужно построить, объединив фрагменты. В следующем примере сравниваются три способа построения одного и того же пути:

set(path1 "${CMAKE_CURRENT_SOURCE_DIR}/data")

cmake_path(SET path2 "${CMAKE_CURRENT_SOURCE_DIR}/data")

cmake_path(APPEND path3 "${CMAKE_CURRENT_SOURCE_DIR}" "data")

Подкоманды изменения и формирования могут сохранять результат непосредственно в исходной переменной или в отдельной переменной, имя которой указывается после ключевого слова OUTPUT_VARIABLE. Все остальные подкоманды сохраняют результат в обязательной переменной <out-var>.

Нормализация

Некоторые подкоманды поддерживают нормализацию пути. Алгоритм нормализации пути выглядит следующим образом:

1. Если путь пуст, остановиться (нормализованная форма пустого пути также является пустым путём).
2. Заменить каждую последовательность directory-separator, которая может состоять из нескольких разделителей, одним / (/a///b  --> /a/b).
3. Удалить каждую отдельную точку (.) и все следующие за ней directory-separator (/a/./b/. --> /a/b).
4. Удалить каждый item-name (кроме ..), за которым непосредственно следуют directory-separator и .., а также все следующие за ними directory-separator (/a/b/../c --> a/c).
5. Если имеется root-directory, удалить все .. и все непосредственно следующие за ними directory-separators. Родительский каталог корневого каталога считается самим корневым каталогом (/../a --> /a).
6. Если последний item-name — это .., удалить все завершающие directory-separator (../ --> ..).
7. Если на этом этапе путь пуст, добавить dot (нормальная форма ./ — .).

Разбиение пути

Каждая из следующих форм подкоманды GET извлекает из пути отдельный компонент или группу компонентов. Значение каждого компонента пути см. в разделе Структура пути и терминология.

cmake_path(GET <path-var> ROOT_NAME <out-var>)

cmake_path(GET <path-var> ROOT_DIRECTORY <out-var>)

cmake_path(GET <path-var> ROOT_PATH <out-var>)

cmake_path(GET <path-var> FILENAME <out-var>)

cmake_path(GET <path-var> EXTENSION [LAST_ONLY] <out-var>)

cmake_path(GET <path-var> STEM [LAST_ONLY] <out-var>)

cmake_path(GET <path-var> RELATIVE_PART <out-var>)

cmake_path(GET <path-var> PARENT_PATH <out-var>)

Если запрошенный компонент отсутствует в пути, в <out-var> будет сохранена пустая строка. Например, понятие root-name существует только в Windows, поэтому на компьютерах с другими операционными системами подкоманда ROOT_NAME всегда возвращает пустую строку.

Для PARENT_PATH, если подкоманда HAS_RELATIVE_PART возвращает false, результатом будет копия <path-var>. Это означает, что у корневого каталога есть родительский каталог, которым является он сам. Если HAS_RELATIVE_PART возвращает true, результатом по существу будет <path-var> без одного элемента.

Примеры корневых компонентов

set(path "c:/a")

cmake_path(GET path ROOT_NAME rootName)
cmake_path(GET path ROOT_DIRECTORY rootDir)
cmake_path(GET path ROOT_PATH rootPath)

message("Root name is \"${rootName}\"")
message("Root directory is \"${rootDir}\"")
message("Root path is \"${rootPath}\"")

Root name is "c:"
Root directory is "/"
Root path is "c:/"

Примеры имён файлов

set(path "/a/b")
cmake_path(GET path FILENAME filename)
message("First filename is \"${filename}\"")

# Trailing slash means filename is empty
set(path "/a/b/")
cmake_path(GET path FILENAME filename)
message("Second filename is \"${filename}\"")

First filename is "b"
Second filename is ""

Примеры расширений и основ имён

set(path "name.ext1.ext2")

cmake_path(GET path EXTENSION fullExt)
cmake_path(GET path STEM fullStem)
message("Full extension is \"${fullExt}\"")
message("Full stem is \"${fullStem}\"")

# Effect of LAST_ONLY
cmake_path(GET path EXTENSION LAST_ONLY lastExt)
cmake_path(GET path STEM LAST_ONLY lastStem)
message("Last extension is \"${lastExt}\"")
message("Last stem is \"${lastStem}\"")

# Special cases
set(dotPath "/a/.")
set(dotDotPath "/a/..")
set(someMorePath "/a/.some.more")
cmake_path(GET dotPath EXTENSION dotExt)
cmake_path(GET dotPath STEM dotStem)
cmake_path(GET dotDotPath EXTENSION dotDotExt)
cmake_path(GET dotDotPath STEM dotDotStem)
cmake_path(GET someMorePath EXTENSION someMoreExt)
cmake_path(GET someMorePath STEM someMoreStem)
message("Dot extension is \"${dotExt}\"")
message("Dot stem is \"${dotStem}\"")
message("Dot-dot extension is \"${dotDotExt}\"")
message("Dot-dot stem is \"${dotDotStem}\"")
message(".some.more extension is \"${someMoreExt}\"")
message(".some.more stem is \"${someMoreStem}\"")

Full extension is ".ext1.ext2"
Full stem is "name"
Last extension is ".ext2"
Last stem is "name.ext1"
Dot extension is ""
Dot stem is "."
Dot-dot extension is ""
Dot-dot stem is ".."
.some.more extension is ".more"
.some.more stem is ".some"

Примеры относительных частей

set(path "c:/a/b")
cmake_path(GET path RELATIVE_PART result)
message("Relative part is \"${result}\"")

set(path "c/d")
cmake_path(GET path RELATIVE_PART result)
message("Relative part is \"${result}\"")

set(path "/")
cmake_path(GET path RELATIVE_PART result)
message("Relative part is \"${result}\"")

Relative part is "a/b"
Relative part is "c/d"
Relative part is ""

Примеры обхода пути

set(path "c:/a/b")
cmake_path(GET path PARENT_PATH result)
message("Parent path is \"${result}\"")

set(path "c:/")
cmake_path(GET path PARENT_PATH result)
message("Parent path is \"${result}\"")

Parent path is "c:/a"
Parent path is "c:/"

Проверка

Для каждой из подкоманд GET существует соответствующая подкоманда HAS_..., с помощью которой можно определить, присутствует ли в пути определённый компонент. Значение каждого компонента пути см. в разделе Структура пути и терминология.

cmake_path(HAS_ROOT_NAME <path-var> <out-var>)

cmake_path(HAS_ROOT_DIRECTORY <path-var> <out-var>)

cmake_path(HAS_ROOT_PATH <path-var> <out-var>)

cmake_path(HAS_FILENAME <path-var> <out-var>)

cmake_path(HAS_EXTENSION <path-var> <out-var>)

cmake_path(HAS_STEM <path-var> <out-var>)

cmake_path(HAS_RELATIVE_PART <path-var> <out-var>)

cmake_path(HAS_PARENT_PATH <path-var> <out-var>)

Каждая из перечисленных выше команд работает предсказуемо: устанавливает <out-var> в true, если путь содержит соответствующий компонент, и в false в противном случае. Обратите внимание на следующие особые случаи:

• Для HAS_ROOT_PATH результат true возвращается, только если root-name или root-directory не пуст.
• Для HAS_PARENT_PATH родительским каталогом корневого каталога также считается он сам. Результат будет true, кроме случая, когда путь состоит только из имени файла.

cmake_path(IS_ABSOLUTE <path-var> <out-var>)

Устанавливает <out-var> в true, если <path-var> является абсолютным. Абсолютный путь однозначно определяет расположение файла без указания дополнительного начального расположения. В Windows путь считается абсолютным, только если он содержит и root-name, и root-directory-separator. На других платформах достаточно одного root-directory-separator. Обратите внимание: в Windows IS_ABSOLUTE может иметь значение false, а HAS_ROOT_DIRECTORY — true.

cmake_path(IS_RELATIVE <path-var> <out-var>)

Сохраняет в <out-var> противоположное значение результата IS_ABSOLUTE.

cmake_path(IS_PREFIX <path-var> <input> [NORMALIZE] <out-var>)

Проверяет, является ли <path-var> префиксом <input>.

Если указан параметр NORMALIZE, перед проверкой выполняется нормализация <path-var> и <input>.

set(path "/a/b/c")
cmake_path(IS_PREFIX path "/a/b/c/d" result) # result = true
cmake_path(IS_PREFIX path "/a/b" result)     # result = false
cmake_path(IS_PREFIX path "/x/y/z" result)   # result = false

set(path "/a/b")
cmake_path(IS_PREFIX path "/a/c/../b" NORMALIZE result)   # result = true

Сравнение путей

cmake_path(COMPARE <input1> EQUAL <input2> <out-var>)

cmake_path(COMPARE <input1> NOT_EQUAL <input2> <out-var>)

Сравнивает лексические представления двух путей, заданных строковыми литералами. Нормализация путей не выполняется, однако несколько последовательных разделителей каталогов фактически сводятся к одному. Равенство определяется согласно следующей логике псевдокода:

if(NOT <input1>.root_name() STREQUAL <input2>.root_name())
  return FALSE

if(<input1>.has_root_directory() XOR <input2>.has_root_directory())
  return FALSE

Return FALSE if a relative portion of <input1> is not lexicographically
equal to the relative portion of <input2>. This comparison is performed path
component-wise. If all of the components compare equal, then return TRUE.

Примечание

В отличие от большинства других подкоманд cmake_path(), подкоманда COMPARE принимает на вход строковые литералы, а не имена переменных.

Изменение пути

cmake_path(SET <path-var> [NORMALIZE] <input>)

Присваивает путь <input> переменной <path-var>. Если <input> — путь в нативном формате, он преобразуется в путь в стиле CMake с прямыми косыми чертами (/). В Windows учитывается маркер длинного имени файла.

Если указан параметр NORMALIZE, путь нормализуется после преобразования.

Например:

set(native_path "c:\\a\\b/..\\c")
cmake_path(SET path "${native_path}")
message("CMake path is \"${path}\"")

cmake_path(SET path NORMALIZE "${native_path}")
message("Normalized CMake path is \"${path}\"")

Вывод:

CMake path is "c:/a/b/../c"
Normalized CMake path is "c:/a/c"

cmake_path(APPEND <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])

Добавляет все аргументы <input> к <path-var>, используя / в качестве directory-separator. В зависимости от <input>, предыдущее содержимое <path-var> может быть отброшено. Для каждого аргумента <input> применяется следующий алгоритм (псевдокод):

# <path> is the contents of <path-var>

if(<input>.is_absolute() OR
  (<input>.has_root_name() AND
    NOT <input>.root_name() STREQUAL <path>.root_name()))
  replace <path> with <input>
  return()
endif()

if(<input>.has_root_directory())
  remove any root-directory and the entire relative path from <path>
elseif(<path>.has_filename() OR
      (NOT <path-var>.has_root_directory() OR <path>.is_absolute()))
  append directory-separator to <path>
endif()

append <input> omitting any root-name to <path>

Подробнее о выходной переменной см. в разделе Создание переменной пути.

cmake_path(APPEND_STRING <path-var> [<input>...] [OUTPUT_VARIABLE <out-var>])

Добавляет все аргументы <input> к <path-var>, не добавляя directory-separator.

Подробнее о выходной переменной см. в разделе Создание переменной пути.

cmake_path(REMOVE_FILENAME <path-var> [OUTPUT_VARIABLE <out-var>])

Удаляет компонент имени файла (возвращаемый командой GET ... FILENAME) из <path-var>. После удаления завершающий directory-separator, если он есть, остаётся без изменений.

HAS_FILENAME вернёт false для результата независимо от того, сохранён ли он в <out-var> или <path-var>.

Например:

set(path "/a/b")
cmake_path(REMOVE_FILENAME path)
message("First path is \"${path}\"")

# filename is now already empty, the following removes nothing
cmake_path(REMOVE_FILENAME path)
message("Second path is \"${path}\"")

Вывод:

First path is "/a/"
Second path is "/a/"

Подробнее о выходной переменной см. в разделе Создание переменной пути.

cmake_path(REPLACE_FILENAME <path-var> <input> [OUTPUT_VARIABLE <out-var>])

Заменяет компонент имени файла в <path-var> на <input>. Если в <path-var> нет компонента имени файла (то есть HAS_FILENAME возвращает false), путь не изменяется. Операция эквивалентна следующему:

cmake_path(HAS_FILENAME path has_filename)
if(has_filename)
  cmake_path(REMOVE_FILENAME path)
  cmake_path(APPEND path "${input}")
endif()

Подробнее о выходной переменной см. в разделе Создание переменной пути.

cmake_path(REMOVE_EXTENSION <path-var> [LAST_ONLY] [OUTPUT_VARIABLE <out-var>])

Удаляет расширение файла, если оно есть, из <path-var>.

Подробнее о выходной переменной см. в разделе Создание переменной пути.

cmake_path(REPLACE_EXTENSION <path-var> [LAST_ONLY] <input> [OUTPUT_VARIABLE <out-var>])

Заменяет расширение на <input>. Результат эквивалентен следующему:

cmake_path(REMOVE_EXTENSION path)
if(NOT input MATCHES "^\\.")
  cmake_path(APPEND_STRING path ".")
endif()
cmake_path(APPEND_STRING path "${input}")

Подробнее о выходной переменной см. в разделе Создание переменной пути.

Формирование пути

cmake_path(NORMAL_PATH <path-var> [OUTPUT_VARIABLE <out-var>])

Нормализует <path-var> согласно шагам, описанным в разделе Нормализация.

Подробнее о выходной переменной см. в разделе Создание переменной пути.

cmake_path(RELATIVE_PATH <path-var> [BASE_DIRECTORY <input>] [OUTPUT_VARIABLE <out-var>])

Изменяет <path-var>, чтобы сделать его относительным к аргументу BASE_DIRECTORY. Если BASE_DIRECTORY не указан, в качестве базового каталога по умолчанию используется CMAKE_CURRENT_SOURCE_DIR.

Для справки: алгоритм вычисления относительного пути совпадает с алгоритмом, используемым в C++ функцией std::filesystem::path::lexically_relative.

Подробнее о выходной переменной см. в разделе Создание переменной пути.

cmake_path(ABSOLUTE_PATH <path-var> [BASE_DIRECTORY <input>] [NORMALIZE] [OUTPUT_VARIABLE <out-var>])

Если <path-var> — относительный путь (IS_RELATIVE имеет значение true), он интерпретируется относительно базового каталога, заданного параметром BASE_DIRECTORY. Если BASE_DIRECTORY не указан, в качестве базового каталога по умолчанию используется CMAKE_CURRENT_SOURCE_DIR.

Если указан параметр NORMALIZE, путь нормализуется после вычисления.

Поскольку cmake_path() не обращается к файловой системе, символические ссылки не разрешаются, а начальная тильда не раскрывается. Чтобы вычислить реальный путь с разрешёнными символическими ссылками и раскрытыми начальными тильдами, используйте команду file(REAL_PATH).

Подробнее о выходной переменной см. в разделе Создание переменной пути.

Преобразование в нативный формат

В командах этого раздела слово нативный относится к платформе хоста, а не к целевой платформе при кросс-компиляции.

cmake_path(NATIVE_PATH <path-var> [NORMALIZE] <out-var>)

Преобразует путь в стиле CMake <path-var> в нативный путь с разделителями, специфичными для платформы (\ на хостах Windows и / на остальных платформах).

Если указан параметр NORMALIZE, путь нормализуется перед преобразованием.

Подробнее о выходной переменной см. в разделе Создание переменной пути.

cmake_path(CONVERT <input> TO_CMAKE_PATH_LIST <out-var> [NORMALIZE])

Преобразует нативный путь <input> в путь в стиле CMake с прямыми косыми чертами (/).

На хостах Windows учитывается маркер длинного имени файла. Входные данные могут представлять собой один путь или системный путь поиска, например $ENV{PATH}. Путь поиска преобразуется в список, разделённый точками с запятой (на платформах, отличных от Windows, это означает, что разделители : заменяются на ;).

Если указан параметр NORMALIZE, путь нормализуется перед преобразованием.

Подробнее о выходной переменной см. в разделе Создание переменной пути.

Примечание

В отличие от большинства других подкоманд cmake_path(), подкоманда CONVERT принимает на вход строковый литерал, а не имя переменной.

cmake_path(CONVERT <input> TO_NATIVE_PATH_LIST <out-var> [NORMALIZE])

Преобразует путь <input> в стиле CMake в нативный путь с разделителями, специфичными для платформы (\ на хостах Windows и / на остальных платформах).

Входные данные могут представлять собой один путь или список, разделённый точками с запятой. Список преобразуется в нативный путь поиска (с разделителями ; в Windows и : на других платформах).

Если указан параметр NORMALIZE, путь нормализуется перед преобразованием.

Подробнее о выходной переменной см. в разделе Создание переменной пути.

Примечание

В отличие от большинства других подкоманд cmake_path(), подкоманда CONVERT принимает на вход строковый литерал, а не имя переменной.

Например:

set(paths "/a/b/c" "/x/y/z")
cmake_path(CONVERT "${paths}" TO_NATIVE_PATH_LIST native_paths)
message("Native path list is \"${native_paths}\"")

Вывод в Windows:

Native path list is "\a\b\c;\x\y\z"

Вывод на всех остальных платформах:

Native path list is "/a/b/c:/x/y/z"

Хеширование

cmake_path(HASH <path-var> <out-var>)

Вычисляет хеш-значение <path-var> таким образом, что для двух путей p1 и p2, которые считаются равными (COMPARE ... EQUAL), хеш-значение p1 равно хеш-значению p2. Перед вычислением хеша путь всегда нормализуется.

Подробнее о выходной переменной см. в разделе Создание переменной пути.