3.24.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 (без @) ищется во внутреннем каталоге двоичных файлов компилятора. Поэтому пример mapper-server можно указать как @g++-mapper-server.

<>[?ident]

<>inout[?ident]

<in>out[?ident]

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

file[?ident]

Файл сопоставлений, содержащий пары «имя модуля — имя файла», разделённые пробелом, по одной на строку. Достаточно указать только сопоставления для прямых импортов и имя экспорта любого модуля. Если указаны другие сопоставления, они переопределяют сопоставления, хранящиеся в импортированных файлах CMI. Корень репозитория можно указать в файле сопоставлений, используя ‘$root’ в качестве имени модуля в первой активной строке. Использование этого параметра отключает сопоставление имён module->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.