diff options
Diffstat (limited to 'share/doc/gcc/C_002b_002b-Module-Mapper.html')
| -rw-r--r-- | share/doc/gcc/C_002b_002b-Module-Mapper.html | 197 |
1 files changed, 197 insertions, 0 deletions
diff --git a/share/doc/gcc/C_002b_002b-Module-Mapper.html b/share/doc/gcc/C_002b_002b-Module-Mapper.html new file mode 100644 index 0000000..83b3c05 --- /dev/null +++ b/share/doc/gcc/C_002b_002b-Module-Mapper.html @@ -0,0 +1,197 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- This file documents the use of the GNU compilers. + +Copyright (C) 1988-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Funding Free Software", the Front-Cover +Texts being (a) (see below), and with the Back-Cover Texts being (b) +(see below). A copy of the license is included in the section entitled +"GNU Free Documentation License". + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>Using the GNU Compiler Collection (GCC): C++ Module Mapper</title> + +<meta name="description" content="Using the GNU Compiler Collection (GCC): C++ Module Mapper"> +<meta name="keywords" content="Using the GNU Compiler Collection (GCC): C++ Module Mapper"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Indices.html#Indices" rel="index" title="Indices"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="C_002b_002b-Modules.html#C_002b_002b-Modules" rel="up" title="C++ Modules"> +<link href="C_002b_002b-Module-Preprocessing.html#C_002b_002b-Module-Preprocessing" rel="next" title="C++ Module Preprocessing"> +<link href="C_002b_002b-Modules.html#C_002b_002b-Modules" rel="previous" title="C++ Modules"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en_US" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="C_002b_002b-Module-Mapper"></a> +<div class="header"> +<p> +Next: <a href="C_002b_002b-Module-Preprocessing.html#C_002b_002b-Module-Preprocessing" accesskey="n" rel="next">C++ Module Preprocessing</a>, Up: <a href="C_002b_002b-Modules.html#C_002b_002b-Modules" accesskey="u" rel="up">C++ Modules</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indices.html#Indices" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Module-Mapper"></a> +<h4 class="subsection">3.23.1 Module Mapper</h4> +<a name="index-C_002b_002b-Module-Mapper"></a> + +<p>A module mapper provides a server or file that the compiler queries to +determine the mapping between module names and CMI files. It is also +used to build CMIs on demand. <em>Mapper functionality is in its +infancy and is intended for experimentation with build system +interactions.</em> +</p> +<p>You can specify a mapper with the <samp>-fmodule-mapper=<var>val</var></samp> +option or <code>CXX_MODULE_MAPPER</code> environment variable. The value may +have one of the following forms: +</p> +<dl compact="compact"> +<dt><code><span class="roman">[</span><var>hostname</var><span class="roman">]</span>:<var>port</var><span class="roman">[</span>?<var>ident</var><span class="roman">]</span></code></dt> +<dd><p>An optional hostname and a numeric port number to connect to. If the +hostname is omitted, the loopback address is used. If the hostname +corresponds to multiple IPV6 addresses, these are tried in turn, until +one is successful. If your host lacks IPv6, this form is +non-functional. If you must use IPv4 use +<samp>-fmodule-mapper='|ncat <var>ipv4host</var> <var>port</var>'</samp>. +</p> +</dd> +<dt><code>=<var>socket</var><span class="roman">[</span>?<var>ident</var><span class="roman">]</span></code></dt> +<dd><p>A local domain socket. If your host lacks local domain sockets, this +form is non-functional. +</p> +</dd> +<dt><code>|<var>program</var><span class="roman">[</span>?<var>ident</var><span class="roman">]</span> <span class="roman">[</span><var>args...</var><span class="roman">]</span></code></dt> +<dd><p>A program to spawn, and communicate with on its stdin/stdout streams. +Your <var>PATH</var> environment variable is searched for the program. +Arguments are separated by space characters, (it is not possible for +one of the arguments delivered to the program to contain a space). An +exception is if <var>program</var> begins with @. In that case +<var>program</var> (sans @) is looked for in the compiler’s internal +binary directory. Thus the sample mapper-server can be specified +with <code>@g++-mapper-server</code>. +</p> +</dd> +<dt><code><><span class="roman">[</span>?<var>ident</var><span class="roman">]</span></code></dt> +<dt><code><><var>inout</var><span class="roman">[</span>?<var>ident</var><span class="roman">]</span></code></dt> +<dt><code><<var>in</var>><var>out</var><span class="roman">[</span>?<var>ident</var><span class="roman">]</span></code></dt> +<dd><p>Named pipes or file descriptors to communicate over. The first form, +<samp><></samp>, communicates over stdin and stdout. The other forms +allow you to specify a file descriptor or name a pipe. A numeric value +is interpreted as a file descriptor, otherwise named pipe is opened. +The second form specifies a bidirectional pipe and the last form +allows specifying two independent pipes. Using file descriptors +directly in this manner is fragile in general, as it can require the +cooperation of intermediate processes. In particular using stdin & +stdout is fraught with danger as other compiler options might also +cause the compiler to read stdin or write stdout, and it can have +unfortunate interactions with signal delivery from the terminal. +</p> +</dd> +<dt><code><var>file</var><span class="roman">[</span>?<var>ident</var><span class="roman">]</span></code></dt> +<dd><p>A mapping file consisting of space-separated module-name, filename +pairs, one per line. Only the mappings for the direct imports and any +module export name need be provided. If other mappings are provided, +they override those stored in any imported CMI files. A repository +root may be specified in the mapping file by using ‘<samp>$root</samp>’ as the +module name in the first active line. Use of this option will disable +any default module->CMI name mapping. +</p> +</dd> +</dl> + +<p>As shown, an optional <var>ident</var> may suffix the first word of the +option, indicated by a ‘<samp>?</samp>’ prefix. The value is used in the +initial handshake with the module server, or to specify a prefix on +mapping file lines. In the server case, the main source file name is +used if no <var>ident</var> is specified. In the file case, all non-blank +lines are significant, unless a value is specified, in which case only +lines beginning with <var>ident</var> are significant. The <var>ident</var> +must be separated by whitespace from the module name. Be aware that +‘<samp><</samp>’, ‘<samp>></samp>’, ‘<samp>?</samp>’, and ‘<samp>|</samp>’ characters are often +significant to the shell, and therefore may need quoting. +</p> +<p>The mapper is connected to or loaded lazily, when the first module +mapping is required. The networking protocols are only supported on +hosts that provide networking. If no mapper is specified a default is +provided. +</p> +<p>A project-specific mapper is expected to be provided by the build +system that invokes the compiler. It is not expected that a +general-purpose server is provided for all compilations. As such, the +server will know the build configuration, the compiler it invoked, and +the environment (such as working directory) in which that is +operating. As it may parallelize builds, several compilations may +connect to the same socket. +</p> +<p>The default mapper generates CMI files in a ‘<samp>gcm.cache</samp>’ +directory. CMI files have a ‘<samp>.gcm</samp>’ suffix. The module unit name +is used directly to provide the basename. Header units construct a +relative path using the underlying header file name. If the path is +already relative, a ‘<samp>,</samp>’ directory is prepended. Internal +‘<samp>..</samp>’ components are translated to ‘<samp>,,</samp>’. No attempt is made +to canonicalize these filenames beyond that done by the preprocessor’s +include search algorithm, as in general it is ambiguous when symbolic +links are present. +</p> +<p>The mapper protocol was published as “A Module Mapper” +<a href="https://wg21.link/p1184">https://wg21.link/p1184</a>. The implementation is provided by +<code>libcody</code>, <a href="https://github.com/urnathan/libcody">https://github.com/urnathan/libcody</a>, +which specifies the canonical protocol definition. A proof of concept +server implementation embedded in <code>make</code> was described in +”Make Me A Module”, <a href="https://wg21.link/p1602">https://wg21.link/p1602</a>. +</p> +<hr> +<div class="header"> +<p> +Next: <a href="C_002b_002b-Module-Preprocessing.html#C_002b_002b-Module-Preprocessing" accesskey="n" rel="next">C++ Module Preprocessing</a>, Up: <a href="C_002b_002b-Modules.html#C_002b_002b-Modules" accesskey="u" rel="up">C++ Modules</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indices.html#Indices" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> |