-
Notifications
You must be signed in to change notification settings - Fork 7
/
Copy pathbuildprocess.tex
199 lines (144 loc) · 8.81 KB
/
buildprocess.tex
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
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
%!TEX root = iso_cpp_modules_ecosystem_technical_report.tex
\rSec0[build]{Build Process}
\indextext{build|(}%
\rSec1[build.import]{Import relationship between translation units}
\pnum The name of a module used in the ``import'' and ``module''
keywords is the ``logical name'' of a module.
\pnum When a translation unit imports a named module, the translation
unit doing the import has an import dependency on the translation unit
providing the importable unit identified via the ``logical name''.
\pnum The translation of an importable unit is externalized into an
intermediate artifact, the Built Module Interface file (BMI). That
file is then consumed when importing a named module.
\rSec1[build.arguments]{Compilation commands and the import relationship}
\pnum ``ABI coherency'' is the expected level of coherency in the
compilation command for the translation of the code in the purview of a
module and all translation units importing that module. When that
level of coherency is not met, the final program may fail to link or
it may link and have undefined behavior at runtime.
\pnum ``BMI coherency'' is the expected level of coherency in the
compilation command for a BMI file to be used when importing a
module. When that level of coherency is not met, the translation will
fail because the BMI cannot be loaded.
\pnum While all translation units importing a module must have ``ABI
coherency'', different translation units importing the same module may
not meet the requirements for ``BMI coherency''. It must be valid for
those to consume different BMI files of the same importable unit, and
to be linked into the same program.
\pnum ``Local Preprocessor Arguments'' are the arguments that are
expected to be different in the translation of an importable unit and
the translation of a unit importing that named module.
\pnum The decision on whether an argument is a ``Local Preprocessor
Argument'' cannot be made by introspection on the code or the command
line, and should be provided by the author of the importable units
and of the unit importing a module.
\pnum To assemble a ``BMI coherent'' command line in order to produce
a BMI file that is usable in the context of a translation unit
importing that module, the starting point should be the compilation
command of the translation unit doing the import, then the ``Local
Preprocessor Arguments'' for the translation unit doing the import are
removed, and the ones for the importable unit are integrated into the
command line.
\pnum Header units never have any ``Local Preprocessor
Arguments''. They are translated using the same command line of the
translation unit importing the header unit with the ``Local
Preprocessor Arguments'' of that translation unit removed.
\pnum Compilers should offer an interface to generate an identifier
for the command line that allows matching the translation unit
importing a module with a BMI that can be loaded in that context. That
interface should not require the primary source file of the
translation unit to be identified, nor the output names to be
produced. Any preprocessor argument given to the compiler in this mode
should be considered for the identifier.
\pnum Build systems should be able to deduplicate the rules to
generate BMI files to be used when importing the same named module
from different translation units by getting the identifier for the
command line of those translation units with the ``Local Preprocessor
Arguments'' filtered out.
\rSec1[build.steps]{Steps of the Build}
\pnum When building \Cpp{} code that produces or consumes modules, the
build process needs to be broken down in different steps. The steps
described here represent the semantic organization, not the interface
presented to the \Cpp{} developer, the organization in steps does not
preclude parts of those steps to be executed in parallel.
\rSec2[build.steps.external-importable]{Identify External Importable Units}
\pnum As the \Cpp{} standard library itself will offer a modular
interface as well as importable headers, it will be very rarely the
case that a build system will be able to consider only modules
declared inside the same build context.
\pnum External importable units will be described in metadata files
made available to the build system. While this report recommends a
specific format for that metadata file, the mechanism by which the set
of metadata files to be considered is identified will be
implementation specific.
\pnum Annex \ref{discovery-prebuilt.linker-arguments} specifies a
convention for environments where the build system and the package
manager can resolve linker argument fragments early enough such that
it can be used to identify the set of module metadata files that need
to be considered.
\pnum TODO: Format of the metadata file.
\pnum TODO: \href{https://github.com/cplusplus/modules-ecosystem-tr/issues/5}{modules-ecosystem-tr\#5}
\rSec2[build.steps.importable-headers]{Identify Importable Headers}
\pnum The \Cpp{} standard describes ``importable headers'' and
``non-importable headers'', however those cannot be differentiated
from their content alone, therefore they need to identified at the
tooling level.
\pnum The \Cpp{} standard also allows (15.3.7) the implementation to
optimize away source file inclusion when a header is known to be
importable.
\pnum Since an include directive may be replaced by an import
directive, a change in the identification of header units may change
the dependency information of any translation unit.
\pnum The Built Module Interface for a header unit should have as its
source the file that would have been found when performing source
inclusion. Implementations should consider an error otherwise.
\pnum A header is identified as importable by the presence of a
metadata file relative to the path being found for source inclusion.
\pnum The path to the metadata file is formed by removing the basename
of the file being included from the path, then appending a separate
directory entry with name \texttt{.importable-headers}, and finally
appending the original basename back with an additional
\texttt{.importable} suffix.
\pnum Note: The reason for the additional directory in the search is
to reduce the number of stat calls the tool needs to perform in order
to identify whether a header is importable or not. The tool should
only need to stat the \texttt{.importable-headers} directory once for
every header in that directory.
\pnum In order to allow the specification of importable headers
without changing the location where those headers are installed, tools
should support a mechanism to specify an additional location for
metadata associated with a given directory.
\pnum TODO: \href{https://github.com/cplusplus/modules-ecosystem-tr/issues/6}{modules-ecosystem-tr\#6}
\rSec2[build.steps.dependency-scan]{Dependency Scanning}
\pnum Importing a named module does not change the state of the
preprocessor. Dependency scanning does not need to be aware of the
location or the contents of the sources providing that particular
named module.
\pnum Importing a header unit changes the state of the preprocessor at
the point of importation, therefore the dependency scanning needs to
identify whether a header is importable or not and perform an
emulation of the import in order to establish in which way the
preprocessor state is changed at that point.
\pnum When emulating the import of a header unit, the dependency
scanning needs the information about what is the command that should
be used to preprocess that importable header. That command should be
the same as the command for the translation unit doing the import,
without the Local Preprocessor Arguments.
\pnum All header units imported by the same translation unit will be
processed with equivalent command lines.
\pnum TODO: \href{https://github.com/cplusplus/modules-ecosystem-tr/issues/7}{modules-ecosystem-tr\#7}
\rSec2[build.steps.bmi-generation]{Generation of the Binary Module Inteface}
\pnum TODO: \href{https://github.com/cplusplus/modules-ecosystem-tr/issues/8}{modules-ecosystem-tr\#8}
\rSec2[build.steps.compilation]{Compilation}
\pnum TODO: \href{https://github.com/cplusplus/modules-ecosystem-tr/issues/9}{modules-ecosystem-tr\#9}
\rSec2[build.steps.linking]{Linking}
\pnum TODO: \href{https://github.com/cplusplus/modules-ecosystem-tr/issues/10}{modules-ecosystem-tr\#10}
\rSec1[build.coherency]{Coherency Requirements}
\pnum TODO: \href{https://github.com/cplusplus/modules-ecosystem-tr/issues/11}{modules-ecosystem-tr\#11}
\rSec1[build.header-units]{Header Units}
\pnum TODO: \href{https://github.com/cplusplus/modules-ecosystem-tr/issues/12}{modules-ecosystem-tr\#12}
\rSec1[build.stdlib]{Relationship with the Standard Library}
\pnum TODO: \href{https://github.com/cplusplus/modules-ecosystem-tr/issues/13}{modules-ecosystem-tr\#13}
\rSec1[build.trivial]{Trivial Cases}
\pnum TODO: \href{https://github.com/cplusplus/modules-ecosystem-tr/issues/14}{modules-ecosystem-tr\#14}
\indextext{build|)}%