1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
|
<!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++ Compiled Module Interface</title>
<meta name="description" content="Using the GNU Compiler Collection (GCC): C++ Compiled Module Interface">
<meta name="keywords" content="Using the GNU Compiler Collection (GCC): C++ Compiled Module Interface">
<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-Implementation.html#C-Implementation" rel="next" title="C Implementation">
<link href="C_002b_002b-Module-Preprocessing.html#C_002b_002b-Module-Preprocessing" rel="previous" title="C++ Module Preprocessing">
<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-Compiled-Module-Interface"></a>
<div class="header">
<p>
Previous: <a href="C_002b_002b-Module-Preprocessing.html#C_002b_002b-Module-Preprocessing" accesskey="p" rel="previous">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="Compiled-Module-Interface"></a>
<h4 class="subsection">3.23.3 Compiled Module Interface</h4>
<a name="index-C_002b_002b-Compiled-Module-Interface"></a>
<p>CMIs are an additional artifact when compiling named module
interfaces, partitions or header units. These are read when
importing. CMI contents are implementation-specific, and in GCC’s
case tied to the compiler version. Consider them a rebuildable cache
artifact, not a distributable object.
</p>
<p>When creating an output CMI, any missing directory components are
created in a manner that is safe for concurrent builds creating
multiple, different, CMIs within a common subdirectory tree.
</p>
<p>CMI contents are written to a temporary file, which is then atomically
renamed. Observers either see old contents (if there is an
existing file), or complete new contents. They do not observe the
CMI during its creation. This is unlike object file writing, which
may be observed by an external process.
</p>
<p>CMIs are read in lazily, if the host OS provides <code>mmap</code>
functionality. Generally blocks are read when name lookup or template
instantiation occurs. To inhibit this, the <samp>-fno-module-lazy</samp>
option may be used.
</p>
<p>The <samp>--param lazy-modules=<var>n</var></samp> parameter controls the limit
on the number of concurrently open module files during lazy loading.
Should more modules be imported, an LRU algorithm is used to determine
which files to close—until that file is needed again. This limit
may be exceeded with deep module dependency hierarchies. With large
code bases there may be more imports than the process limit of file
descriptors. By default, the limit is a few less than the per-process
file descriptor hard limit, if that is determinable.<a name="DOCF3" href="#FOOT3"><sup>3</sup></a>
</p>
<p>GCC CMIs use ELF32 as an architecture-neutral encapsulation mechanism.
You may use <code>readelf</code> to inspect them, although section
contents are largely undecipherable. There is a section named
<code>.gnu.c++.README</code>, which contains human-readable text. Other
than the first line, each line consists of <code><var>tag</var>: <code>value</code></code>
tuples.
</p>
<div class="smallexample">
<pre class="smallexample">> <code>readelf -p.gnu.c++.README gcm.cache/foo.gcm</code>
String dump of section '.gnu.c++.README':
[ 0] GNU C++ primary module interface
[ 21] compiler: 11.0.0 20201116 (experimental) [c++-modules revision 20201116-0454]
[ 6f] version: 2020/11/16-04:54
[ 89] module: foo
[ 95] source: c_b.ii
[ a4] dialect: C++20/coroutines
[ be] cwd: /data/users/nathans/modules/obj/x86_64/gcc
[ ee] repository: gcm.cache
[ 104] buildtime: 2020/11/16 15:03:21 UTC
[ 127] localtime: 2020/11/16 07:03:21 PST
[ 14a] export: foo:part1 foo-part1.gcm
</pre></div>
<p>Amongst other things, this lists the source that was built, C++
dialect used and imports of the module.<a name="DOCF4" href="#FOOT4"><sup>4</sup></a> The timestamp is the same value as that
provided by the <code>__DATE__</code> & <code>__TIME__</code> macros, and may be
explicitly specified with the environment variable
<code>SOURCE_DATE_EPOCH</code>. For further details
see <a href="Environment-Variables.html#Environment-Variables">Environment Variables</a>.
</p>
<p>A set of related CMIs may be copied, provided the relative pathnames
are preserved.
</p>
<p>The <code>.gnu.c++.README</code> contents do not affect CMI integrity, and
it may be removed or altered. The section numbering of the sections
whose names do not begin with <code>.gnu.c++.</code>, or are not the string
section is significant and must not be altered.
</p>
<div class="footnote">
<hr>
<h4 class="footnotes-heading">Footnotes</h4>
<h3><a name="FOOT3" href="#DOCF3">(3)</a></h3>
<p>Where
applicable the soft limit is incremented as needed towards the hard limit.</p>
<h3><a name="FOOT4" href="#DOCF4">(4)</a></h3>
<p>The precise contents
of this output may change.</p>
</div>
<hr>
<div class="header">
<p>
Previous: <a href="C_002b_002b-Module-Preprocessing.html#C_002b_002b-Module-Preprocessing" accesskey="p" rel="previous">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>
|
