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
|
The ti(module.modulemap) file defines the organization of one or more
modules. It relates header files to defined module(s). The name
tt(module.modulemap) is a predefined name, and module specifications must use
this name. tt(Module.modulemap) files may contain comment: standard bf(C)
and/or end-of-line comment.
A emi(module specification) defines a name and possibly options for a
module. The elements of a module specification are specified inside a
curly-braced section (note that when using [xxx] the square brackets are
em(not) optional).
The following description does not cover the full syntax of tt(module.map), as
some specifications apply only to some operating systems. For the full
description the reader is referred to the
lurl(http://clang.llvm.org/docs/Modules.html) document.
The generic layout of a tt(module.modulemap) file starts with the module
header, defining the name of the module. This name is used as the first part
of the compiled module file (e.g., tt(minimal-2ORZEBL9H54OZ.pcm) for a module
called tt(minimal)). Different programs may use identical module names, as
modules receives unique `last names' (in the example: tt(2ORZEBL9H54OZ)).
Inside a module definition headers commonly are included in module
specifications of their own. So the generic syntax looks like this (in the
syntax specifications the following conventions are used: blank lines separate
syntax definitions; syntax elements followed by a tt(*) may be omitted or may
be used once or multiple times; vertical bars separate alternatives; quoted
names and characters should literally be used, without the quotes; tt('ident')
must be replaced by a standard bf(C++) identifier; double quoted strings are
NTBSs, (their meanings are provided inside the double quoted strings); syntax
elements preceded by tt(opt_) (e.g., tt('opt_[extern_c]')) are optional (such
elements are either omitted or are used without the tt(opt_) prefix:
tt('opt_[extern_c]') means: tt([extern_c]))):
verb( module-declarations:
module_declaration*
module_declaration:
header
'{'
module_member*
'}'
|
'extern' 'module' 'ident' " TO DO "
header:
'module' 'ident' 'opt_[extern_c]' // [extern_c]: the module holds
// C code that can be used from
// within C++
module_member:
cf_modules_html // refer to clang's Modules.html document
| // for these member declarations
export_declaration
|
header_declaration
|
link_declaration
|
module_declarations // nested declarations are commonly used
|
requires_declaration
|
umbrella_dir_declaration
cf_modules_html:
config_macros_declaration
|
conflict_declaration
|
export_as_declaration
|
submodule_declaration
|
use_declaration
export_declaration: // see below
'export' module_id
feature_list: // see below
feature_list ',' 'ident'
|
'ident'
header_declaration:
link_declaration: // add '-llibraryName' to the linker
'link' "libraryName" // when using the module
requires_declaration
'requires' 'opt_!' feature_list
umbrella_dir_declaration
'umbrella' "directory-specification" // e.g., ".", see below)
In this overview,
itemization(
itt(export_declaration) specifies a tt(module_id) which is the
name of the module that will be visible from the defined
modules. These names refer to headers (without the .h extension) that
are made visible from the current module. Usually everything is made
available, for which tt(export *) is commonly used. Refer to the
tt(Modules.html) document for additional info about using tt(export).
itt(feature_list) is used to specify languages or architectures for which
the module is available. For bf(C++) the relevant features are
em(cplusplus, cplusplus11, cplusplus14, cplusplus17, tls). A
tt(cplusplsus2a) feature is not (yet?) available. The tt(tls) feature
means: thread local storage must be available. nl()
Example: tt(requires cplusplus).
itt(umbrella_dir_declaration) is used to indicate that all headers in and
below the specified directory must be added to the module. Directory
specification tt(".") refers to all headers in and below the current
directory.
)
Usually when defining a a module its tt(module.modulemap) defines the module's
name, and then uses the headers of its (sub)directories to define submodules
for each directory, exporting all their symbols. E.g., the program
bf(ssh-cron) (cf. lurl(https://fbb-git.gitlab.io/ssh-cron/)) defines eight
classes, each in its own subdirectory. To create the module tt(ssh_cron) the
following tt(module.modulemap) can be used:
verbinsert(-as4 examples/ssh-cron.map)
resulting in the module tt(ssh_cron-2D64GM0XFP9U2.pcm) which is about 11MB
large.
|
