Next:Module Preprocessing, Up:C++ Modules [Contents][Index]
A module mapper provides a server or file that the compiler queries todetermine the mapping between module names and CMI files. It is alsoused to build CMIs on demand.Mapper functionality is in itsinfancy and is intended for experimentation with build systeminteractions.
You can specify a mapper with the-fmodule-mapper=valoption orCXX_MODULE_MAPPER environment variable. The value mayhave one of the following forms:
[hostname]:port[?ident]An optional hostname and a numeric port number to connect to. If thehostname is omitted, the loopback address is used. If the hostnamecorresponds to multiple IPV6 addresses, these are tried in turn, untilone is successful. If your host lacks IPv6, this form isnon-functional. If you must use IPv4 use-fmodule-mapper='|ncatipv4hostport'.
=socket[?ident]A local domain socket. If your host lacks local domain sockets, thisform is non-functional.
|program[?ident][args...]A program to spawn, and communicate with on its stdin/stdout streams.YourPATH environment variable is searched for the program.Arguments are separated by space characters, (it is not possible forone of the arguments delivered to the program to contain a space). Anexception is ifprogram begins with @. In that caseprogram (sans @) is looked for in the compiler’s internalbinary directory. Thus the sample mapper-server can be specifiedwith@g++-mapper-server.
<>[?ident]<>inout[?ident]<in>out[?ident]Named pipes or file descriptors to communicate over. The first form,<>, communicates over stdin and stdout. The other formsallow you to specify a file descriptor or name a pipe. A numeric valueis interpreted as a file descriptor, otherwise named pipe is opened.The second form specifies a bidirectional pipe and the last formallows specifying two independent pipes. Using file descriptorsdirectly in this manner is fragile in general, as it can require thecooperation of intermediate processes. In particular using stdin &stdout is fraught with danger as other compiler options might alsocause the compiler to read stdin or write stdout, and it can haveunfortunate interactions with signal delivery from the terminal.
file[?ident]A mapping file consisting of space-separated module-name, filenamepairs, one per line. Only the mappings for the direct imports and anymodule export name need be provided. If other mappings are provided,they override those stored in any imported CMI files. A repositoryroot may be specified in the mapping file by using ‘$root’ as themodule name in the first active line. Use of this option will disableany default module->CMI name mapping.
As shown, an optionalident may suffix the first word of theoption, indicated by a ‘?’ prefix. The value is used in theinitial handshake with the module server, or to specify a prefix onmapping file lines. In the server case, the main source file name isused if noident is specified. In the file case, all non-blanklines are significant, unless a value is specified, in which case onlylines beginning withident are significant. Theidentmust be separated by whitespace from the module name. Be aware that‘<’, ‘>’, ‘?’, and ‘|’ characters are oftensignificant to the shell, and therefore may need quoting.
The mapper is connected to or loaded lazily, when the first modulemapping is required. The networking protocols are only supported onhosts that provide networking. If no mapper is specified a default isprovided.
A project-specific mapper is expected to be provided by the buildsystem that invokes the compiler. It is not expected that ageneral-purpose server is provided for all compilations. As such, theserver will know the build configuration, the compiler it invoked, andthe environment (such as working directory) in which that isoperating. As it may parallelize builds, several compilations mayconnect to the same socket.
The default mapper generates CMI files in a ‘gcm.cache’directory. CMI files have a ‘.gcm’ suffix. The module unit nameis used directly to provide the basename. Header units construct arelative path using the underlying header file name. If the path isalready relative, a ‘,’ directory is prepended. Internal‘..’ components are translated to ‘,,’. No attempt is madeto canonicalize these filenames beyond that done by the preprocessor’sinclude search algorithm, as in general it is ambiguous when symboliclinks are present.
The mapper protocol was published as “A Module Mapper”https://wg21.link/p1184. The implementation is provided bylibcody,https://github.com/urnathan/libcody,which specifies the canonical protocol definition. A proof of conceptserver implementation embedded inmake was described in”Make Me A Module”,https://wg21.link/p1602.
Next:Module Preprocessing, Up:C++ Modules [Contents][Index]