-
Notifications
You must be signed in to change notification settings - Fork 7
/
discovery-in-prebuilt-library-releases.tex
150 lines (123 loc) · 7.2 KB
/
discovery-in-prebuilt-library-releases.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
\infannex{discovery-prebuilt}{C++ Modules Discovery in Prebuilt
Library Releases}
\rSec1[discovery-prebuilt.linker-arguments]{``Linker Arguments'' as a
mechanism to discover \Cpp{} module metadata files}
\pnum This section describes a framework for the discovery of module
metadata files on environments where the linker arguments for the
library can be resolved early enough. This is not a requirement for
all implementations, as some build systems need to defer the
resolution of linker arguments to a step that is later than the
translation of the module interfaces.
\pnum While almost the entirety of the behavior of build systems and
package managers are implementation-defined, there is one concept
that is common to most of them: At some point, the build system and
the package manager, when consuming a library as a prebuilt artifact,
need to communicate enough to identify what are the linker arguments
that a consuming build needs in order to successfully use that
library.
\pnum While the way in which those arguments are discovered is fully
implementation-defined, while the format and semantics of those
arguments are also fully implementation-defined, the concept that when
you consume a prebuilt library you will need to use additional linker
arguments is a point of convergence.
\pnum It is also a point of convergence that those arguments will be
translatable to files on disk, through implementation-defined
translations. This is a requirement for C++ libraries being
distributed as prebuilt artifacts today.
\pnum While the format and arguments of the linker are specified in an
implementation-defined way, the current reality is that build systems,
package managers, static analysis tools, etc that want to interact
with different linkers consistently need to re-implement the parsing
of the arguments and trying to emulate the behavior of the linker.
\pnum This report recommends that a toolchain should provide a
mechanism to translate linker arguments, even if just a fragment of a
complete linker invocation, into the input files that are going to be
used by the linker.
\pnum Third-party implementations of that translation can be provided
in case vendors do not provide it directly, but there is room for
better interoperability if a tool that performs that translation
exists one way or another.
\pnum The convention estalishes that metadata files will be
deterministically named alongside the files that are used as inputs to
the linker, such that the build system can parse those to create a
complete understanding of all modules relevant to this project.
\pnum The specific conversions from the paths to the input to the
linkers to the paths of the metadata files are implementation
defined. Different sections of this report will describe the
convention for specific environments.
\rSec2[discovery-prebuilt.header-only]{Header-only Libraries}
\pnum Header-only libraries have been a common practice in the C++
ecosystem. It makes a specific trade-off on how to use specific C++
language constructs in order to avoid the complexities of the lack of
convergence on the package management for various different
environments.
\pnum It also allows a library to avoid ABI-compatibility questions,
and therefore support virtually any standards-conforming toolchain
without having to provide a prebuilt artifact to any of them.
\pnum It is often the case that package managers will still provide a
release of those header-only libraries within their ecosystem, such
that they can be addressed for dependency management as well as to
manage required compiler arguments, such as include directories and
compile definitions, even when linker arguments are not required.
\pnum As we transition to C++ modules, it is reasonable to presume
that the same approach can be translated, we can call them
“importable-unit-only module libraries”. As with header-only
libraries, there are specific constraints on how the code has to be
written, but, in principle, any library that could be implemented as a
header-only library could also be implemented as an
“importable-unit-only module library”.
\pnum However, C++ modules create additional requirements for the
parsing of the consumers of a library. Therefore even if a library
doesn’t require linker arguments, it needs to be able to specify how
to parse those interface units coherently. In practice, that means
there is distinctively more metadata that needs to be provided with an
“importable-unit-only module library” than the comparable “header-only
library”.
\pnum Specifically, this will mean much more importance to the work
done by the maintainers of the package management metadata for those
libraries in the various package management systems. It is fair to say
that it will not be practical, beyond illustrative cases, to consume
C++ module libraries in the absence of some amount of package
management infrastructure.
\pnum Solving the consumption of “importable-unit-only module
libraries” in an interoperable way will require a wider convergence on
package management in general. Therefore this report recommends that
package managers following this convention produce library artifacts,
even if empty, and include linker arguments for importable-unit-only
module libraries.
\pnum This will allow the linker arguments to be a consistent point of
convergence for all cases, which is enough ground to stand a
convention on how to discover C++ modules in pre-built library
releases. Future work for the convergence in the area of package
management may make this recommendation unnecessary.
\rSec2[discovery-prebuilt.conventions]{Convention for translating
linker input files to module metadata files}
\pnum The input file is considered directly, if the filesystem
supports symbolic links, they should not be followed. For example: in
the case of SONAME symlinks on GNU/Linux, the metadata file will be
associated with the unversioned library name, not with the final
target of the symbolic link.
\pnum The metadata file will be a different entry in the same
directory as the path that is the input file to the linker, only with
a different name.
\pnum The name of the directory entry for the metadata is composed by
appending to the name of the directory entry for the input file to the
linker.
\pnum The directory entry for the metadata file will have a final suffix
composed by the dot character and XXXX (TODO: Extension of the module
metadata file,
\href{https://github.com/cplusplus/modules-ecosystem-tr/issues/23}{modules-ecosystem-tr\#23}).
\pnum If the toolchain supports linker input files with more than one
Instruction Set Architecture (ISA), the search should start with a
directory name entry that includes an additional dot character
followed by the implementation-defined ISA code before the final
suffix, and then fallback to the directory entry name without the ISA
code.
\pnum This report recommends that toolchain implementations should
provide a tool that translates linker argument fragments into the path
to the related metadata files found according to the specifics of the
implementation.
\pnum This report recommends that toolchain implementations should
provide a tool that describes what the metadata file path should be
for a library, given the implementation-defined characteristics of the
library being produced.