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
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
|
% JUST-MR REPOSITORY CONFIG(5) | File Formats Manual
NAME
====
just-mr-repository-config - The format of the repository config used by
**`just-mr`**(1)
DESCRIPTION
===========
In order for the **`just-mr`**(1) tool to generate a repository
configuration file usable by the **`just`**(1) multi-repository build
system, it requires a configuration file describing repositories and
their dependencies.
The file is read as JSON. Any other serialization describing the same
JSON object is equivalent. It is assumed that in JSON objects keys occur
at most once; it is implementation defined how repetitions of the same
key are treated.
Workspace root description
--------------------------
A repository's *workspace root description* provides information about
the location of source files. It can be an explicit description, given
as a JSON object, or an implicit one, given as the global name of
another repository, from which the workspace root can be inferred.
Explicit workspace roots can be of several types, distinguishable by the
value of the key *`"type"`* in the JSON object. Depending on this value,
other fields in the object are also supported.
### *`"file"`*
It defines as workspace root a directory on the file system.
The following fields are supported:
- *`"path"`* provides the root directory containing the source files.
This entry is mandatory.
### *`"archive"`* / *`"zip"`*
They define as workspace root a remote archive. The only difference
between the two types is the nature of the archive: a tarball (preferably
compressed) in the case of *`"archive"`*, or a compressed zip or 7zip file
in the case of *`"zip"`*.
The following fields are supported:
- *`"content"`* provides the Git blob hash of the archive file. This
has to be specified in hex encoding. This entry is mandatory.
- *`"fetch"`* specifies the URL to the remote archive. This entry is
mandatory.
- *`"distfile"`* provides an alternative name for the archive file.
This entry is optional. If missing, the basename of the fetch URL is
used.
- *`"mirrors"`* is an optional list of alternative locations to try to
fetch from if contacting the main fetch location fails. This entry is
optional.
- *`"sha256"`*,
- *`"sha512"`* provide optional checksum hashes in order to verify the
integrity of the remote site archive. These have to be provided in
hex encoding. These checks are only performed if the archive file is
actually downloaded from the (potentially untrusted) network and not
already available locally.
- *`"subdir"`* specifies the subdirectory withing the unpacked archive.
This entry is optional. If missing, the root directory of the archive
is used.
### *`"foreign file"`*
Define a root as consisting of single file with given content at
a specific name with specified executable bit.
The following fields are supported.
- *`"content"`*, *`"fetch"`*, *`"distfile"`*, *`"mirrors"`*, *`"sha256"`*,
and *`"sha512"`* specify the file content in the same way as they specify
the archive content for an *`"archive"`* repository.
- *`"name"`* specifies the name the content should have in the defined root.
It has to be a plain file name without implicitly specified sudirs. This
field is mandatory.
- *`"executable"`* is a boolean indicating whether the fetched file should
be provided with the executable bit. Defaults to `false`.
### *`"git"`*
It defines as workspace root a part of a Git repository.
The following fields are supported:
- *`"repository"`* provides the URL of the Git repository. This entry
is mandatory. Note that only URLs starting with `/`, `./`, or `file://`
are considered file URLs.
- *`"commit"`* contains the commit hash. This has to be specified in
hex encoding. This entry is mandatory.
- *`"branch"`* provides the branch name, with the promise that it
contains the aforementioned commit. This entry is mandatory.
- *`"mirrors"`* is an optional list of alternative locations to try to
fetch from if contacting the main repository fails. This entry is
optional.
- *`"subdir"`* specifies the subdirectory containing the distribution
files. This entry is optional. If missing, the root directory of the
Git repository is used.
- *`"inherit env"`* provides a list of variables. When `just-mr`
shells out to `git`, those variables are inherited from the
environment `just-mr` is called within, if set there.
### *`"git tree"`*
It defines as workspace root as a fixed `git` tree, given by the
corresponding tree identifier. If that tree is not known already to
`just-mr`, a specified command will be executed in a fresh directory
that is expected to produce the given tree somewhere below the
working directory.
This type of root is the way builds against sources versioned in
arbitrary version-control systems can be carried out. The command
then would be a call to the version control system requesting an
export at a particular version.
As the root is already fully determined by the specified `git` tree
identifier, the corresponding action need not be fully isolated.
In fact, to check out a repository it might be necessary to provide
credentials (which do not matter for the checked-out tree, but
differ from user to user). To support this, the description of the
root can specify environment variables to inherit from the ambient
environment. E.g., `SSH_AUTH_SOCK` can be specified here to support
`ssh`-based authentication.
The following fields are supported:
- *`"id"`* provides the Git tree identifier. This entry is mandatory.
- *`"cmd"`* provides a list of strings forming a command which promises
that, when executed in an empty directory (anywhere in the file
system), creates in that directory a directory structure containing
the promised Git tree (either top-level or in some subdirectory).
This entry is mandatory.
- *`"env"`* provides a map of envariables to be set for executing the
command.
- *`"inherit env"`* provides a list of variables to be inherited from the
environment `just-mr` is called within, if set there.
### *`"distdir"`*
It defines as workspace root a directory with the distribution archives
of the specified repositories. Usually this root is realized as a Git
tree in the Git repository in **`just`**'s local build root.
The following fields are supported:
- *`"repositories"`* provides a list of global names of repositories.
This entry is mandatory.
### *`"computed"`*
It defines a computed root, typically to be used as root by other
repositories. A computed root is given as the artifacts map of
an export target of a content-fixed repository. Computed roots
themselves are content fixed; the dependency of computed roots on
one another must be cycle free.
The following fields are supported:
- *`"repo"`* specifies the repository the export target belongs
to. This entry is mandatory.
- *`"target"`* specifies the export target within the given
repository in module-name form. This entry is mandatory.
- *`"config"`* specifies the configuration at which to evaluate
the export target. This entry is optional and defaults to the
empty map.
### Additional keys
The key *`"pragma"`* is reserved for type-specific repository directives
which alter the workspace root. It is given as a JSON object. The
different workspace roots might support different keys for this object;
unsupported keys are always ignored.
For a *`"file"`* workspace root the pragma key *`"to_git"`* is
supported. If its value is *`true`* then it indicates that the workspace
root should be returned as a Git tree. If the root directory is already
part of a Git repository, its Git tree identifier is used; otherwise,
the workspace root will be realized as a Git tree in the Git repository
in **`just`**'s local build root.
For all workspace roots except *`"distdir"`* the pragma key *`"special"`* is
supported. If its value is *`"ignore"`* then it indicates that the workspace
root should ignore all special (i.e., neither file, executable, nor tree)
entries. For a *`"file"`* workspace root or for an *`"archive"`* workspace root
a value of *`"resolve-completely"`* indicates that the workspace root should
resolve all confined relative symbolic links, while a value of
*`"resolve-partially"`* indicates that the workspace root should resolve only
the confined relative upwards symbolic links; for a *`"file"`* workspace root
these two values imply *`"to_git"`* is *`true`*.
For all workspace roots the pragma key *`"absent"`* is supported. If its value
is *`true`* then it indicates that an absent root should be generated, i.e., one
given only by its Git tree without any explicit witnessing repository.
Repository description
----------------------
A *repository description* is defined as a JSON object, containing a
*workspace root description*, directory roots and names for targets,
rules, and expressions files, and bindings to other repositories.
Specifically, the following fields are supported:
- *`"repository"`* contains a *workspace root description*. This entry
is mandatory.
- *`"target_root"`*,
- *`"rule_root"`*,
- *`"expression_root"`* define the root directories for the targets,
rules, and expressions, respectively. If provided, they are passed on
expanded to the workspace root of the repository named by their
value.
- *`"target_file_name"`*,
- *`"rule_file_name"`*,
- *`"expression_file_name"`* refer to the name of the files containing
the targets, rules, and expressions, respectively, located relative
to the corresponding root directories. These entries are optional.
If provided, they are passed on as-is.
- *`"bindings"`* provides a JSON object defining dependencies on other
repositories. The object's keys are strings defining local repository
names, while the values are the corresponding global names of those
repositories. If provided, this entry is passed on as-is.
Repository configuration format
-------------------------------
The repository configuration format is structured as a JSON object. The
following fields are supported:
- *`"main"`* contains a JSON string that determines which of the
provided repositories is considered the main repository. This entry
is optional, and if ommitted, it will be ommitted in the generated
**`just-repository-config`**.
- *`"repositories"`* contains a JSON object, where each key is the
global name of a repository and its corresponding value is the
*repository description*.
Additional keys
---------------
Any JSON object described in this format might have additional keys
besides the ones mentioned. The current strategy of **`just-mr`**(1) is
to accept and ignore them. Users should be aware that future versions of
this format might give specific meanings to these extra keys.
See also
========
**`just`**(1),
**`just-mr`**(1),
**`just-repository-config`**(5)
|
