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
|
% JUST-MRRC(5) | File Formats Manual
NAME
====
just-mrrc - The format of the configuration used by **`just-mr`**(1)
DESCRIPTION
===========
The file is read as JSON. Any other serialization describing the same
JSON object is equivalent. We assume, that in JSON objects, each key
occurs at most once; it is implementation defined how repetitions of the
same key are treated.
Location objects
----------------
A *location* is a JSON object with the keys *`"root"`*, *`"path"`*, and
*`"base"`*.
The value for key *`"root"`* is either *`"workspace"`*, *`"home"`*, or
*`"system"`*, which have the following meanings:
- *`"workspace"`* refers to the root of the workspace in which the
`just-mr` invocation was issued (not the workspace of the requested
main repository). This location root is ignored if **`just-mr`** was not
invoked from inside a workspace.
- *`"home"`* refers to the user's home directory.
- *`"system"`* refers to the system root *`/`*.
The value for key *`"path"`* is the relative path of the item to locate
within the location root.
The value for key *`"base"`* is a relative path within the location
root. This path is only relevant for locations of config files. If such
a config file contains relative paths, those will be resolved relative
to the specified base. If omitted, the default value *`"."`* is used.
The just-mrrc format
--------------------
The just-mrrc is given by a JSON object.
- The value for the key *`"config lookup order"`* is a JSON list of
location objects, specifying where to look for multi-repository
configurations (see **`just-mr-repository-config`**(5) for more
detail). The lookup is performed in the same order the location
objects appear in the list.
- The value for the key *`"absent"`*, if provided, is a JSON list
of location objects to search for a file specifying the list of
absent repositories.
- The value for the key *`"local build root"`* is a single location
object, specifying the path to use as the local build root. For more
details, see **`just-mr`**(1).
- The value for the key *`"checkout locations"`* is a single location
object, specifying the path to the file describing checkout locations
and additional mirror locations. For more details, see **`just-mr`**(1).
- The value for the key *`"distdirs"`* is a JSON list of location
objects, specifying where to look for distribution files (usually
collected via the subcommand **`fetch`**). The lookup is performed in
the same order the location objects appear in the list. For more
details, see **`just-mr`**(1).
- The value for the key *`"just"`* is a single location object,
specifying the path to the **`just`** binary to use for execution, if
**`just-mr`** is used as a launcher.
- The value for the key *`"git"`* is a single location object,
specifying the path to the git binary to use in the instances when
**`just-mr`** needs to shell out.
- The value for the key *`"local launcher"`*, if given, is list of
strings setting the default for local launcher for **`just-mr`**;
command-line arguments take precedence over the value in the
configuration file. If the key *`"local launcher"`* is absent, the
default *`["env", "--"]`* is assumed.
- The value for the key *`"log limit"`*, if given, sets the default
value for the log limit, that can be overridden by the command-line
options.
- The value for the key *`"restrict stderr log limit"`*, if given,
sets the default value for the restriction of the log limit on
console; this value can be overridden by the command-line option.
- The value *`"log files"`*, if given, has to be a list of location
objects, specifying additional log files, on top of those specified
on the command line.
- The value for the key *`"remote execution"`* is a JSON object specifying the
remote execution options for **`just-mr`**.
For subkey *`"address"`* the value is a string specifying the remote
execution address in a NAME:PORT format.
For subkey *`"compatible"`* the value is a flag which specifies whether the
remote endpoint uses the original remote execution protocol.
Each subkey value can be overwritten by its corresponding command-line
argument.
- The value for the key *`"remote serve"`* is a JSON object specifying the
remote serve options for **`just-mr`**.
For subkey *`"address"`* the value is a string specifying the remote
serve address in a NAME:PORT format.
Each subkey value can be overwritten by its corresponding command-line
argument.
- The value for the key *`"authentication"`* is a JSON object specifying
client-side authentication options for **`just-mr`**.
For subkey *`"ca cert"`* the value is a single location object
specifying the path to a TLS CA certificate.
For subkey *`"client cert"`* the value is a single location object specifying
the path to a TLS client certificate.
For subkey *`"client key"`* the value is a single location object specifying
the path to a TLS client key.
Each subkey value can be overwritten by its corresponding command-line
argument.
- The value for the key *`"remote-execution properties"`*, if
provided, has to be a list of strings. Each entry is forwarded
as `--remote-execution-property` to the invocation of the build
tool, if **`just-mr`** is used as a launcher.
- The value for the key *`"max attempts"`*, if provided, has
to be a number. If a remote procedure call (rpc) returns
`grpc::StatusCode::UNAVAILABLE`, that rpc is retried at most
this number of times.
- The value for the key *`"initial backoff seconds"`*, if provided,
has to be a number. Before retrying an rpc the second time, the
client will wait the given amount of seconds plus a jitter, to
better distribute the workload.
- The value for the key *`"max backoff seconds"`*, if provided,
has to be a number. Normally, on subsequent retries, the backoff
time is doubled; this number specifies the maximal time between
attempts of an rpc, not counting the jitter.
- The value for the key *`"just files"`* is a JSON object. The keys correspond
to options that some **`just`** subcommands accept and require a file as
argument. For each key, the value is a list of location objects. When
**`just-mr`** is used as a launcher and the invoked subcommand is known to
support this option, this option is set in the **`just`** invocation with
the first matching entry, if any. The supported options are *`"config"`*
and *`endpoint-configuration`*.
- The value for the key *`"just args"`* is a JSON object. Its keys are
**`just`** subcommands and its value is a JSON list of strings. For the
corresponding subcommand, these strings are prefixed to the **`just`**
argument vector (after all other options provided through the rc file),
if **`just-mr`** is used as a launcher.
- The value for the key *`"rc files"`*, if given, is a list of
location objects. For those location objects that refer to
an existing file, this file is read as an additional rc file
overlaying the given rc file in the specified order; the value
of `"rc files"` in the overlaying files is ignored.
In this way, an rc file commited to a repository can be allowed
to set a sensible configuration, remote-execution and serve end
points, etc. This is particularly useful when simultaneously
working on several projects with different settings.
EXAMPLE
=======
An example just-mrrc file could look like the following:
``` jsonc
{ "rc files":
[ {"root": "workspace", "path": "rc.json"}
, {"root": "workspace", "path": "etc/rc.json"}
]
, "config lookup order":
[ {"root": "workspace", "path": "repos.json"}
, {"root": "workspace", "path": "etc/repos.json"}
, {"root": "home", "path": ".just-repos.json"}
, {"root": "system", "path": "etc/just-repos.json"}
]
, "absent":
[ {"root": "workspace", "path": "etc/absent.json"}
, {"root": "home", "path": ".just-absent"}
]
, "local build root": {"root": "home", "path": ".cache/just"}
, "checkout locations": {"root": "home", "path": ".just-local.json"}
, "local launcher": ["env", "--"]
, "log limit": 5
, "restrict stderr log limit": 4
, "log files": [{"root": "home", "path": ".log/just/latest-invocation"}]
, "distdirs": [{"root": "home", "path": ".distfiles"}]
, "just": {"root": "system", "path": "usr/bin/just"}
, "git": {"root": "system", "path": "usr/bin/git"}
, "remote execution": {"address": "10.0.0.1:8980"}
, "remote-execution properties": ["image:development-v1.2.3"]
, "just args":
{ "build": ["-J", "64"]
, "install": ["-J", "64", "--remember"]
, "install-cas": ["--remember"]
}
, "just files":
{ "config":
[ {"root": "workspace", "path": "etc/config.json"}
, {"root": "home", "path": ".just-config"}
]
}
}
```
See also
========
**`just-mr`**(1),
**`just-mr-repository-config`**(5)
|
