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.