3.23.1 Модуль-маппер

Модуль-маппер предоставляет сервер или файл, к которому компилятор обращается для определения сопоставления между именами модулей и файлами CMI. Он также используется для построения CMI по требованию. Функциональность маппера находится на начальной стадии и предназначена для экспериментов с взаимодействием систем сборки.

Вы можете указать маппер с помощью опции -fmodule-mapper=val или переменной окружения CXX_MODULE_MAPPER. Значение может иметь один из следующих форматов:

[hostname]:port[?ident]

Необязательный хост и числовой номер порта для подключения. Если хост опущен, используется адрес петли обратной связи. Если хост соответствует нескольким адресам IPv6, они пробуются по очереди, пока один не увенчается успехом. Если у вашего хоста нет IPv6, этот формат не будет функциональным. Если вам необходимо использовать IPv4, используйте -fmodule-mapper='|ncat ipv4host port'.

=socket[?ident]

Локальный сокет домена. Если у вашего хоста нет локальных сокетов домена, этот формат не будет функциональным.

|program[?ident] [args...]

Программа для запуска и взаимодействия с ней через потоки stdin/stdout. В вашей переменной окружения PATH ищется программа. Аргументы разделяются пробелами (невозможно, чтобы один из аргументов, переданных программе, содержал пробел). Исключением является случай, когда program начинается с @. В этом случае program (без @) ищется в внутренней директории бинарных файлов компилятора. Таким образом, сервер маппера-образца можно указать с помощью @g++-mapper-server.

<>[?ident]

<>inout[?ident]

<in>out[?ident]

Именованные каналы или дескрипторы файлов для взаимодействия. Первый формат, <>, взаимодействует через stdin и stdout. Другие форматы позволяют указать дескриптор файла или назвать канал. Числовое значение интерпретируется как дескриптор файла, в противном случае открывается именованный канал. Второй формат определяет двунаправленный канал, а последний формат позволяет указать два независимых канала. Использование дескрипторов файлов напрямую таким образом в общем случае хрупко, так как может потребоваться сотрудничество промежуточных процессов. В частности, использование stdin и stdout сопряжено с опасностями, поскольку другие параметры компилятора могут также привести к чтению компилятором stdin или записи в stdout, и это может иметь нежелательные взаимодействия с передачей сигналов с терминала.

file[?ident]

Файл сопоставления, состоящий из пар «имя модуля — имя файла», разделённых пробелами, по одной паре на строку. Нужно указать только сопоставления для прямых импортов и любых имён экспорта модуля. Если будут предоставлены другие сопоставления, они перепишут сопоставления, хранящиеся в любых импортированных файлах CMI. Корень репозитория может быть указан в файле сопоставления с использованием ‘$root’ в качестве имени модуля в первой активной строке. Использование этого параметра отключит любое стандартное сопоставление имя модуля — имя файла CMI.

Как показано, необязательный ident может быть добавлен к первому слову опции, указанному префиксом ‘?’. Это значение используется в начальном рукопожатии с сервером модулей или для указания префикса в строках файла сопоставления. В случае сервера, если ident не указан, используется имя файла исходного кода. В случае файла, все строки, не содержащие пробелов, важны, если не указано значение, в этом случае важны только строки, начинающиеся с ident. ident должен быть разделен пробелом от имени модуля. Обратите внимание, что символы ‘<’, ‘>’, ‘?’, и ‘|’ часто имеют значение для оболочки, и поэтому могут потребоваться кавычки.

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

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

Маппер по умолчанию создаёт файлы CMI в каталоге ‘gcm.cache’. Файлы CMI имеют суффикс ‘.gcm’. Имя модуля используется непосредственно для создания имени файла. Единицы заголовков строят относительный путь, используя имя базового файла заголовка. Если путь уже относительный, добавляется директория ‘,’. Внутренние компоненты ‘..’ переводятся в ‘,,’. Не предпринимается попытка канонизировать эти имена файлов, кроме того, что выполняется алгоритмом поиска включений препроцессора, так как в общем случае это неоднозначно, когда присутствуют символические ссылки.

Протокол маппера был опубликован как «Модульный маппер» https://wg21.link/p1184. Реализация предоставляется libcody, https://github.com/urnathan/libcody, в котором указано каноническое определение протокола. Реализация сервера-прототипа, встроенная в make, была описана в «Создайте мне модуль», https://wg21.link/p1602.