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
|
Configuration
=============
Targets describe abstract concepts like "library". Depending on
requirements, a library might manifest itself in different ways. For
example,
- it can be built for various target architectures,
- it can have the requirement to produce position-independent code,
- it can be a special build for debugging, profiling, etc.
So, a target (like a library described by header files, source files,
dependencies, etc) has some additional input. As those inputs are
typically of a global nature (e.g., a profiling build usually wants all
involved libraries to be built for profiling), this additional input,
called "configuration" follows the same approach as the `UNIX`
environment: it is a global collection of key-value pairs and every
target picks, what it needs.
Top-level configuration
-----------------------
The configuration is a `JSON` object. The configuration for the target
requested can be specified on the command line using the `-c` option;
its argument is a file name and that file is supposed to contain the
`JSON` object.
Propagation
-----------
Rules and target definitions have to declare which parts of the
configuration they want to have access to. The (essentially) full
configuration, however, is passed on to the dependencies; in this way, a
target not using a part of the configuration can still depend on it, if
one of its dependencies does.
### Rules configuration and configuration transitions
As part of the definition of a rule, it specifies a set `"config_vars"`
of variables. During the evaluation of the rule, the configuration
restricted to those variables (variables unset in the original
configuration are set to `null`) is used as environment.
Additionally, the rule can request that certain targets be evaluated in
a modified configuration by specifying `"config_transitions"`
accordingly. Typically, this is done when a tool is required during the
build; then this tool has to be built for the architecture on which the
build is carried out and not the target architecture. Those tools often
are `"implicit"` dependencies, i.e., dependencies that every target
defined by that rule has, without the need to specify it in the target
definition.
### Target configuration
Additionally (and independently of the configuration-dependency of the
rule), the target definition itself can depend on the configuration.
This can happen, if a debug version of a library has additional
dependencies (e.g., for structured debug logs).
If such a configuration-dependency is needed, the reserved key word
`"arguments_config"` is used to specify a set of variables (if unset,
the empty set is assumed; this should be the usual case). The
environment in which all arguments of the target definition are
evaluated is the configuration restricted to those variables (again,
with values unset in the original configuration set to `null`).
For example, a library where the debug version has an additional
dependency could look as follows.
``` jsonc
{ "libfoo":
{ "type": ["@", "rules", "CC", "library"]
, "arguments_config": ["DEBUG"]
, "name": ["foo"]
, "hdrs": ["foo.hpp"]
, "srcs": ["foo.cpp"]
, "local defines":
{ "type": "if"
, "cond": {"type": "var", "name": "DEBUG"}
, "then": ["DEBUG"]
}
, "deps":
{ "type": "++"
, "$1":
[ ["libbar", "libbaz"]
, { "type": "if"
, "cond": {"type": "var", "name": "DEBUG"}
, "then": ["libdebuglog"]
}
]
}
}
}
```
Effective configuration
-----------------------
A target is influenced by the configuration through
- the configuration dependency of target definition, as specified in
`"arguments_config"`,
- the configuration dependency of the underlying rule, as specified in
the rule's `"config_vars"` field, and
- the configuration dependency of target dependencies, not taking into
account values explicitly set by a configuration transition.
Restricting the configuration to this collection of variables yields the
effective configuration for that target-configuration pair. The
`--dump-targets` option of the `analyse` subcommand allows to inspect
the effective configurations of all involved targets. Due to
configuration transitions, a target can be analyzed in more than one
configuration, e.g., if a library is used both, for a tool needed during
the build, as well as for the final binary cross-compiled for a
different target architecture.
|
