chiark / gitweb /
README: document trouble with tricky packages, and submodules
[nailing-cargo.git] / README.md
1 nailing-cargo
2 =============
3
4 This is a wrapper tool for cargo, the Rust build tool and package
5 manager.  Functions:
6
7  * Conveniently use local crates, including completely
8    unpublished crates.
9  * Perform out-of-tree builds, including in an account with
10    no write access to the source tree.
11  * Provide convenience aliases for target architecture names.
12  * Make the default be offline (ie, not to access the internet).
13
14 These functions are of course configurable.
15
16 The primary source of information for nailing-cargo is the file
17 `../Cargo.nail` (which is in TOML syntax).  You put `Cargo.nail`
18 alongside the top-level git repositories you are working with, and
19 invoke nailing-cargo from the git directory containing the Rust
20 package you want to build.
21
22 Installing
23 ----------
24
25 nailing-cargo is designed to be run out of a git clone:
26
27 ```
28 $ git clone https://salsa.debian.org/iwj/nailing-cargo.git
29 $ ln -s `pwd`/nailing-cargo/nailing-cargo ~/bin
30 ```
31
32 It is self-contained, depending only on a reasonably functional Perl
33 installation.
34
35 Most basic example usage
36 ------------------------
37
38 ```
39 $ cd myproject
40 $ cat >../Cargo.nail
41 subdirs="""
42 myproject
43 mylibrary
44 """
45 $ nailing-cargo -u fetch
46 $ nailing-cargo build
47 ```
48
49 Documentation table of contents
50 -------------------------------
51
52 <!-- TOC autogenerated by ./markdown-toc-filter, do not edit -->
53
54   * [Introduction](#nailing-cargo)
55     * [Installing](#installing)
56     * [Most basic example usage](#most-basic-example-usage)
57     * [Documentation table of contents](#documentation-table-of-contents)
58   * [Using local crates, or locally modified crates](#using-local-crates-or-locally-modified-crates)
59     * [How nailing-cargo helps with using local crates](#how-nailing-cargo-helps-with-using-local-crates)
60     * [Telling nailing-cargo how to massage `Cargo.toml`](#telling-nailing-cargo-how-to-massage-cargo.toml)
61   * [Out-of-tree builds](#out-of-tree-builds)
62     * [How nailing-cargo helps with out-of-tree builds](#how-nailing-cargo-helps-with-out-of-tree-builds)
63     * [Configuring out-of-tree builds](#configuring-out-of-tree-builds)
64   * [Target architecture convenience aliases](#target-architecture-convenience-aliases)
65   * [Default change to offline mode](#default-change-to-offline-mode)
66   * [Invocation and command-line option reference](#invocation-and-command-line-option-reference)
67     * [Usages](#usages)
68     * [Options](#options)
69     * [Environment of the build command](#environment-of-the-build-command)
70   * [Configuration reference](#configuration-reference)
71     * [Source directories and packages (toplevel)](#source-directories-and-packages-toplevel)
72     * [`[alt_cargolock]`: Alternative `Cargo.lock` filename](#alt_cargolock-alternative-cargo.lock-filename)
73     * [`[oot]`: Out-of-tree build support](#oot-out-of-tree-build-support)
74     * [`[arch]`: Architecture convenience aliases](#arch-architecture-convenience-aliases)
75     * [`[misc]`: Miscellaneous individual nailing-cargo config](#misc-miscellaneous-individual-nailing-cargo-config)
76   * [Limitations and bugs](#limitations-and-bugs)
77   * [Contributing and legal](#contributing-and-legal)
78     * [Legal](#legal)
79
80 Using local crates, or locally modified crates
81 ==============================================
82
83 cargo does not work well with local crates,
84 especially completely unpublished ones.
85 (See [issue#6713](https://github.com/rust-lang/cargo/issues/6713),
86 [stackoverflow](https://stackoverflow.com/questions/33025887/how-to-use-a-local-unpublished-crate),
87 [issue#1481](https://github.com/rust-lang/cargo/issues/1481),
88 [my blog](https://diziet.dreamwidth.org/1805.html).)
89
90 Using a local version of a crate should be possible without putting
91 paths into your `Cargo.toml` and without editing complex
92 configuration.
93
94 How nailing-cargo helps with using local crates
95 -----------------------------------------------
96
97 nailing-cargo temporarily edits all the `Cargo.toml` files in all the
98 subdirectories you mention, to refer to each other; then it runs
99 cargo; and then it puts everything back.
100
101 Telling nailing-cargo how to massage `Cargo.toml`
102 -------------------------------------------------
103
104 To find the subdirectories, and the packages, nailing-cargo looks for
105 `subdirs` and `packages` in `Cargo.nail`.
106
107 For straightforward use, write `subdirs` as a multi-line string
108 containing a list of subdirectory names one per line.  In each of
109 these directories `Cargo.toml` will be massaged, and the package there
110 will be used for other massaged `Cargo.toml`s.
111
112 See the [Configuration reference](#configuration-reference) for full details.
113
114 Scope of nailing-cargo's local crate functionality
115 --------------------------------------------------
116
117 nailing-cargo's `Cargo.toml` massaging will allow you to easily build
118 an interdepending set of local packages, possibly even including
119 private unpublished packages, and/or locally-modified versions of
120 published packages.  These local packages can freely depend on
121 published packages (eg from `crates.io`) in the usual way.
122
123 Compared to the corresponding cargo feature, nailing-cargo's approach:
124 (i) works even for local crates that have not been published anywhere; and
125 (ii) is a lot simpler to configure.
126
127 But nailing-cargo's local crate support won't work if any non-local
128 crate needs to be rebuilt against a local crate (ie, a local version
129 of one of its dependencies).  If that is your requirement, either make
130 local versions of the intermediate crates in the dependency graph, or
131 use the cargo override facility --- see [Overriding
132 Dependencies](https://doc.rust-lang.org/cargo/reference/overriding-dependencies.html)
133 in the Cargo Book.
134
135 Out-of-tree builds
136 ==================
137
138 It is often desirable to run builds in a way that does not write to
139 the source tree.  cargo's enthusiastic approach to the dependency
140 management task means that it is a good idea to try to insulate your
141 main working environment from the many things cargo has decided to
142 download and execute.
143
144 However, when you tell cargo to do an out of tree build (using
145 `--manifest-path`) it will insist on `Cargo.lock` being in the source
146 directory, and often will insist on writing to it.
147
148 How nailing-cargo helps with out-of-tree builds
149 -----------------------------------------------
150
151 nailing-cargo (configured appropriately) copies files back and forth
152 to between the source and build directories, and runs cargo as your
153 build user.
154
155 The `Cargo.lock` must still be saved in your source tree somewhere.
156 nailing-cargo arranges this for you.  You can either put this file in
157 `.gitignore`; or commit it to git; or you can tell nailing-cargo to
158 save it as something like `Cargo.lock.example`.
159
160 Depending on the circumstances, nailing-cargo uses a variety of
161 strategies, including `--manifest-path` options, and linkfarming, to
162 make out of tree builds.  Some crates don't natively support
163 out-of-tree builds, in which case passing a `--linkfarm` option to
164 nailing-cargo can be helpful.
165
166 Configuring out-of-tree builds
167 ------------------------------
168
169 To enable out-of-tree-builds, put an `[oot]` section in your
170 `Cargo.nail` or one of nailing-cargo's other config files.
171 In that section, specify at least `use`.
172
173 Also, specify `dir`, or create a symlink `Build` next to `Cargo.nail`,
174 pointing to to your build area.
175
176 For example,
177 ```
178 [oot]
179 use='ssh'
180 user='rustcargo'
181 ```
182 will have nailing-cargo run `ssh rustcargo@localhost` to
183 run build commands.
184
185 Target architecture convenience aliases
186 =======================================
187
188 If you are cross-building you may need to tell cargo `--target=`.
189 The architecture names are quite long and inconvenient.
190
191 A simple shell alias would help a lot, except that cargo rejects
192 `--target=` when it thinks it's not needed.
193
194 In your nailing-cargo config, you can write something like
195 `arch.RPI='arm-unknown-linux-gnueabihf'`.  Then `nailing-cargo -TRPI`
196 will DTRT.  In fact, you do not even need to specify that particular
197 arch alias, since it is built-in to nailing-cargo.
198
199 Default change to offline mode
200 ==============================
201
202 It seems to me that build tools should be explicit about their use of
203 the network.  So by default, nailing-cargo passes `--offline` to
204 cargo.
205
206 If you disagree with my opinion, write `misc.online=true` in your
207 nailing-cargo configuration.  `misc.online=false`, and command line
208 options, are also available, for overriding.
209
210 If you agree with me, you may wish to use `nailing-cargo
211 generate-lockfile`, which can update (even an existing) `Cargo.lock`
212 without going online, instead of `update`.
213
214 Invocation and command-line option reference
215 ============================================
216
217 Usages
218 ------
219
220 ```
221 1$ nailing-cargo <nailing-opts> <cargo-opts> [--] <subcmd>...
222 2$ nailing-cargo <nailing-opts> --- <cargo> <cargo-opts> [--] <subcmd>...
223 3$ nailing-cargo <nailing-opts> --- [--] <build-command>...
224 ```
225 Ususally the `--` is not needed.  (It should generally be passed by
226 programs which wrap nailing-cargo.  See [Invocation argument disambiguation rules](#invocation-argument-disambiguation-rules), below.)
227
228 In usage 1, nailing-cargo runs `cargo` (from `PATH`).  In the usage 2
229 nailing-cargo runs `<cargo>`.  In both these cases it adds its own
230 options to control cargo's behaviour.  In both of these cases
231 nailing-cargo looks at `<subcmd>` to determine the cargo subcommand
232 being run: this controls various defaults, to try to do the right
233 things.
234
235 In the third syntax, nailing-cargo runs `<build-command>...` without
236 additional arguments and does not attempt to identify the cargo
237 subcommand(s) that it will run.  Possibly it will be necessary to pass
238 `--online` or `--cargo-lock-update`, or even `--cargo-*arg*`
239
240 ### Invocation argument disambiguation rules ###
241
242 For authors of tools which call nailing-cargo (and pedants):
243
244 The usages overlap in syntax!  nailing-cargo follows the following
245 rules when interpreting its command line:
246
247   * The first option not recognised as a nailing-cargo option is
248     treated as the start of the `<cargo-opts>`.
249
250   * `<cargo-opts>` are terminated by `--` (which is removed) or the
251     first argument which does not start with a `-` or `+`.
252
253     (It is not possible to get nailing-cargo to pass the value `--`
254     as a separate argument to a cargo global option, but cargo global
255     options can typically take the values cuddled with `=`, so doing
256     that is not necessary.)
257
258   * After `---`, nailing-cargo will search for a `--`, to the end of
259     the arguments if necessary.  The position of the `--` determines
260     whether this is usage 2 or usage 3, and what `<subcmd>` is.
261
262     If the arguments after `nailing-cargo ... ---` might contain `--`
263     anywhere, an explicit `--` should be passed.
264
265   * If no `--` appears after `---`, the word after `---` is the
266     command to run; if its final pathname component contains the
267     string `cargo`, it is treated as `<cargo>` (implying usage 2 and
268     the search for `<subcmd>`).  Otherwise it is treated as
269     `<build-command>` (usage 3).
270
271 Options
272 -------
273
274   * `-v`: Increase verbosity.  Default is 1.
275
276   * `-q`: Set verbosity to 0.
277
278   * `-D`: Increase amount of debugging dump.
279
280   * `-n`: "No action": stop after writing `Cargo.toml.nailing~`
281        everywhere, and do not run any build command.
282
283   * `-f` | `--force`: Force going ahead even if problems are likely.
284     (E.g., due to missing `-E` option.)
285
286   * `-T<arch>` | `--target=<arch>`
287
288     Specify target architecture.
289
290     This option translates to a `--target=<arch>` option to cargo
291     (when the subcommand accepts it).
292
293     If `<arch>` starts with a capital ascii letter, it is an alias
294     for some other arch: it is looked up in the configuration, and
295     then in the builtin arch alias list.  The builtin list is
296     equivalent to:
297
298 ```
299 [arch]
300 RPI="arm-unknown-linux-gnueabihf"
301 WASM="wasm32-unknown-unknown"
302 ```
303
304   * `-o` | `--online` | `-O` | `--offline`
305
306     Whether to allow cargo to make network access.  nailing-cargo
307     always passes `--offline` to cargo, unless `--online` is in
308     force.  The default value depends on the configuration and the
309     cargo subcommand - see [`[misc]` `online`](#misc_online),
310     under Configuration.
311
312   * `-u` | `--cargo-lock-update` | `-U` | `--no-cargo-lock-update`
313
314     Allows (or disallows) cargo to update `Cargo.lock` in the source
315     directory.  Without this enabled, nailing-cargo passes `--locked`
316     to cargo.
317
318     With this enabled, in an out-of-tree build the `Cargo.lock` and
319     `Cargo.toml` are copied to the build directory along with a
320     linkfarm, to fool cargo.  After cargo has run, the resulting
321     `Cargo.lock` is copied back to the source tree.
322
323     Default is no update unless the whole point of the cargo
324     subcommand is to update `Cargo.lock`.
325
326   * `-c` | `-C`
327
328     Controls the addition of cargo command line options; ie,
329     whether nailing-cargo should treat the build command as if it
330     were cargo.
331     With `-C`, nailing-cargo will not add additional options
332     to the build command.  With `-c` it will pass those options
333     after the cargo subcommand (usages 1 and 2) or right
334     after the build command (usage 3).
335
336     The cargo options are in any case also passed in the
337     environment - see [Environment of the build command](#environment-of-the-build-command).
338
339     The default is to pass cargo options if the command line
340     parsing yielded a cargo command and options (usages 1 and 2),
341     rather than a non-cargo build command (usage 3).  `-C` and `-c`
342     do not affect the parsing of nailing-cargo's command line.
343
344   * <a name="s_subcommand">`-s<subcommand>`</a>
345
346     Behave as if the build command were `cargo <subcommand>`.
347     This influences the logic which tries to determine which
348     options to pass to cargo, whether cargo needs to be online, and
349     whether cargo might want to update `Cargo.lock`.
350
351     nailing-cargo knows about the following commands:
352      * `fetch`
353      * `fmt`
354      * `generate-lockfile`
355      * `init`
356      * `metadatay`
357      * `miri`
358      * `update`
359      * `upgrades`
360
361     All other subcommands are (silently) treated the same way
362     as `build` (ie, no subcommand properties).  See
363     `--subcommand-props` for more detail about how the
364     subcommand affects nailing-cargo's behaviour.
365
366     The default is to use the cargo subcommand found from parsing
367     nailing-cargo's command line.  NB: `-s` does not affect
368     which build command (and which cargo subcommand) is actually run.
369
370   * <a name="subcommand_props">`--subcommand-props=<prop>,...`</a>
371
372     Specify the properties of the subcommand.  This is an
373     alternative to `-s<subcmd>`.  The usual properties are:
374
375     * `lock-update`: cargo will want to update `Cargo.lock`.  (The `-u` and `-U` options override this.)
376     * `online`: this subcommand makes no sense to run offline.  (The `-o` and `-O` options, and the configuration, can override this.)
377     * `edits`: The purpose of this subcommand is to edit the source tree.  Imples that `--edit-sources` is necessary (unless `--force`).
378     * `creates`: The purpose of this subcommand is to edit the source tree and create new files in it.  Imples that `-EE` (`--edit-sources`, twice) is necessary (unless `--force`).
379     * `!target`: cargo would reject `--target=<arch>`; in this case nailing-cargo's `-T` option is ineffective.
380     * `!target-dir`: cargo would reject `--target-dir`, so don't pass it.  (Usually we pass `--target-dir=target` when we pass `--manifest-path`, since cargo's default is `target` in the same directory as `Cargo.toml`.)
381     * `linkfarm-shallow`: Make the default be `--linkfarm=shallow`.  This is the default for `miri` and can also be used for other subcommands which do not understandg `--manifest-path` properly.
382     * `linkfarm-gitclean`: Make the defaults be `--linkfarm=git` and `--preclean-build=src`.
383
384     There are also some properties which should not be needed, but are
385     provided for completeness.  Do not use these to solve the problem
386     of nailing-cargo passing cargo options to a build command which is
387     not cargo - use `-C` for that.  The properties whose use is discouraged:
388
389     * `!manifest-path`: cargo would reject `--manifest-path`, so don't pass it (and don't pass `--target-dir` either).  Only makes any difference for out-of-tree builds.  Things will probably go wrong unless the build command looks at `[NAILING]CARGO_MANIFEST_DIR`.
390     * `!locked`: cargo would reject `--locked`, so don't pass it.  Hazardous.
391     * `!offline`: the build command would reject `--offline`, so never pass it.  *Not* overridden by configuration or command line.
392
393
394   * `--linkfarm[=no|shallow|git|full]`: Override nailing-cargo's
395     approach to out-of-tree builds.  Normally nailing-cargo chooses
396     automatically whether to make a linkfarm, and precisely what kind
397     of linkfarm, based on the cargo subcommand.  The linkfarm styles
398     are:
399
400     * `no`: Do not make a linkfarm; pass a `--manifest-path` option
401       pointing to the actual source directory.  This is the default
402       for most cargo commands.
403
404     * `shallow`: Symlink top-level objects in the source directory,
405       including whole subdirectories.  This the default when
406       nailing-cargo thinks cargo is going to update `Cargo.lock`.
407
408     * `git`: Make a deep linkfarm, with subdirectories.  Symlink
409       those objects tracked by git.  This is the default for
410       `cargo publish`.
411
412     * `full`: Make a deep linkfarm and symlink every nondirectory found
413       in the source tree.  This will including all sorts of junk,
414       including for example editor backup files.
415
416     Whenever nailing-cargo linkfarms, old symlinks pointing back to
417     the source tree are deleted.  In each case, `Cargo.lock` is not
418     symlinked, but copied.  If nailing-cargo expects cargo to update
419     `Cargo.lock`, it will copy it back to the source tree afterwards.
420     Just `--linkfarm` is the same as `--linkfarm=git`.
421
422   * `--edit | --edit-sources | -E`: Permits the cargo command to edit
423     sources in the source tree.  This is achieved by *copying* the
424     entire source tree (all files tracked by git) into the destination
425     directory, and then copying back all changed files.  *Only git
426     tracked filles* can be edited by the cargo command; edits to
427     other files, and creation of new files, will be ignored.
428
429     When this option is repeated (`-EE`), the cargo subcommand can
430     create new files including dotfiles (but nothing in the toplevel
431     `target` and nothing called `.git`).  (This also enables
432     `--preclean=src` by default.)
433
434     If you are running out of tree builds for privsep reasons, you
435     should use git to review the edits made by the cargo command and
436     either stage and commit them, or reject them.
437
438     This option is overridden by a subsequent `--linkfarm` options.
439
440     `-E` or `-f` is needed for `nailing-cargo fmt`.  `-EE` or `-f` is
441     needed for `nailing-cargo init`.  `-E` is never the default,
442     even if nailing-cargo thinks it's needed.
443
444   * `--just-linkfarm[=shallow|git|full]`: Make the out-of-tree
445     linkfarm as if for `--cargo-lock-update`, but do not actually run
446     any command, nor try to copy back a a generated `Cargo.lock`.
447     Forces `--keep-linkfarm` (even if the contrary is also specified).
448
449     With a linkfarming mode, overrides (and is overridden by)
450     `--linkfarm=`.  Without a linkfarming mode, and without
451     `--linkfarm`, the default is `shallow`.
452
453   * `--keep-linkfarm` | `--clean-linkfarm`: When doing an out-of-tree
454     lockfile update, controls whether the linkfarm is kept afterwards.
455     Overrides the `oot.clean` config option.  (Default: keep.)
456
457   * `--[no-]preclean-build[=no|src|full]`: When doing an out-of-tree
458     build, controls whether the build directory is purged of leftover
459     contents *before* the build is run.  The usual default is `no`.
460     For `cargo publish`, the default is `src`, which deletes
461     everything except the directory `target`.  `full` means to clean
462     out that too.
463
464   * `--leave-nailed`: At the end, leave all the `Cargo.toml` files in
465     their edited state, rather than (trying to) clean them up.  To
466     clean this up later, run `nailing-cargo` again without this option.
467     Without this option, the nailed versions are left in
468      `.Cargo.toml.nailed~`, so you only need this if you want to run
469     cargo by hand or something.
470
471   * `--just-run`: Execute the specified command (perhaps concurrently
472     with other commands), but do not manipulate any of Cargo's
473     metadata fiules.  Useful in out of tree mode to invoke a non-cargo
474     command in the build environment.  Implies `--no-nail`,
475     `--no-cargo-lock-manip` and `--no-concurrency-lock` (overrideable
476     by later occurrences of the corresponding opposite options).
477     Hazardous if the command is actually cargo, or will run cargo.
478
479   * `--no-nail` | `--nail` (default): Whether to actually nail - ie,
480     whether to actually modify any `Cargo.toml`s while running the
481     command.  This can be useful, e.g., in out-of-tree mode with
482     commands that don't actually invoke cargo.  Consider passing
483     `--no-concurrency-lock` too.
484
485   * `--no-cargo-lock-manip` | `--cargo-lock-manip` (default):
486     Whether to manipulate `Cargo.lock`.  For example, whether to copy
487     it to the build tree and back (in out of tree mode) and whether to
488     rename it from an alternative lockfile name, and put it back.
489     Overrides `-u` etc.
490
491   * `--no-concurrency-lock` | `--concurrency-lock` (default): Whether
492     to take the nailing-cargo lock.  Some kind of protection against
493     concurrent operation is necessary to prevent multiple instances of
494     nailing-cargo trashing each others' work, and possibly mangling
495     your `Cargo.toml`s, `Cargo.lock`, etc., so `--no-concurrency-lock`
496     is dangerous unless you take other measures against concurrent
497     execution.
498
499   * `-h` | `--help`: Print usage summary.
500
501   * `--doc` | `--man` | `--manual`: Format this manual into html using
502     `pandoc` and display it with `w3m`.
503
504 Environment of the build command
505 --------------------------------
506
507 nailing-cargo passes these environment variables to the build command:
508
509   * `CARGO_MANIFEST_DIR`: invocation `.` (invocation directory)
510   * `NAILINGCARGO_MANIFEST_DIR`: same as `CARGO_MANIFEST_DIR`
511   * `NAILINGCARGO_WORKSPHERE`: invocation `..` (parent)
512   * `NAILINGCARGO_BUILD_DIR`: build directory (even if same as source)
513   * `NAILINGCARGO_BUILDSPHERE`: parent of build dir (only set if out-of-tree)
514   * `NAILINGCARGO_CARGO_OPTIONS`: additional options that nailing-cargo passed (or would pass) to cargo.  Space-separated; does not include `--manifest-path`.
515
516 All of these are absolute paths.
517
518 ### Build commands which wrap cargo ###
519
520 If you specify a build command which eventually runs cargo, you may
521 wish to pass on to your cargo the options which nailing-cargo would
522 have passed.  This will definitely be necessary if you are using nailing-cargo's out-of-tree facility.
523
524 In such a situation, do it like this:
525 ```
526   cargo build --manifest-path="${CARGO_MANIFEST_DIR-.}"/Cargo.toml $NAILINGCARGO_CARGO_OPTIONS
527 ```
528
529 If you need to run a cargo subcommand which doesn't understand some of
530 nailing-cargo's options, currently, you must strip them out of
531 `NAILINGCARGO_CARGO_OPTIONS` yourself - or pass some `-s` or
532 `--subcmd-props` option to nailing-cargo (but that is a layering
533 violation and may not work if one build command runs various different
534 cargo runes).
535
536 Configuration reference
537 =======================
538
539 nailing-cargo reads these configuration files:
540 ```
541     /etc/nailing-cargo/cfg.toml
542     ~/.nailing-cargo.toml
543     ./.nailing-cargo.toml
544     ../Nailing-Cargo.toml
545     ../Cargo.nail
546 ```
547 Settings in later-mentioned files override ones in earlier-mentioned
548 files.
549
550 Source directories and packages (toplevel)
551 ------------------------------------------
552
553 Note that unlike everything else, these keys (`packages` and
554 `subdirs`) are read only from `Cargo.nail` (see "Limitations and
555 bugs", below).
556
557 These keys specify a combination of (i) a mapping from package name to
558 source subdirectory (ii) a set of subdirectories whose `Cargo.toml`
559 must be massaged.
560
561   * `packages`: a map keyed by package name, giving the subdirectory
562     for each one.
563
564     This causes each mentioned subdirectory's `Cargo.toml` to be
565     massaged, and records that subdirectory as the source for that
566     package.  (nailing-cargo will check that subdirectory actually
567     contains the indicated package.)
568
569     Each value can be just the subdirectory name (eg `[packages]`
570     `mylibrary='mylibrary-test'`) or itself a map with the key `subdir`
571     (eg `[packages.mylibrary]` `subdir='mylibrary-test'`).
572
573   * `subdirs`: a list of subdirectory names to process.
574
575     Each subdirectory's `Cargo.toml` will be massaged.  Also, the
576     subdirectory will be examined to see what package it contains; it
577     will then be used as the source for that package, unless that
578     package appears in an entry in `packages`, or an earlier entry in
579     `subdirs`.
580
581     This can be a list of strings (eg `subdirs =
582     ['myproject','mylibrary']`).  Or it can be single multi-line
583     string containing one subdirectory name per line; in that
584     case, `#`-comments are supported and tabs and spaces are ignored
585     (see "Most basic example usage" above.)
586
587 In each case the subdirectory should usually be a relative pathname;
588 it is relative to the directory containing `Cargo.nail`.
589
590 `[alt_cargolock]`: Alternative `Cargo.lock` filename
591 ----------------------------------------------------
592
593 To control use of alternative `Cargo.lock` filename, use the section
594 `[alt_cargolock]`.  Settings here:
595
596   * `file = <some leafname>`.
597
598   * `file = true`: Equivalent to `file = "Cargo.lock.example"`.
599     (This is the default.)
600
601   * `file = false`: Disables this feature.
602
603   * `force = false`: Uses the alternative filename only if it
604      already exists.  (This is the default.)
605
606   * `force = true`: Always uses the alternative filename.
607
608 `[oot]`: Out-of-tree build support
609 ----------------------------------
610
611   * `dir`: The build directory.  If relative, it is relative to the
612    parent of the invocation directory (and could be a symlink then).
613    Default is `Build` (assuming `use` is specified).
614
615    The build directory will contain one subdir for each package: each
616    subdir in the build dir corresponds to one source dir where
617    nailing-cargo was invoked.  nailing-cargo will arrange to create
618    these subdirectories, so the build directory can start out empty.
619
620   * `use`: How to become the build user.  Needs to be combined
621     with other setting(s):
622
623     * `ssh`: Use ssh.  `user` must be given as well and can be
624        a username on localhost, or the `<user>@<host>`
625        argument to ssh.
626
627     * `command_args`: `command` must be specified as a list,
628        specifying a command and arguments which work like `nice`.
629
630     * `command_sh`: `command` must be specified as a list,
631        specifying a command and arguments which work like `sh -c`.
632
633     * `null`: Run builds as the same user.
634
635     * `really`: Use `really` from `chiark-really.deb`.
636        `user` must be given as well.
637
638     * `disable': Disable this feature, even if `dir` is set.
639
640  * `command`: The command to run for `command_sh` or `command_args`.
641
642    In both cases, this is a command and its arguments/options.  The
643    list will be passed to `execvp`.  The difference between
644    `command_args` and `command_sh` is in what nailing-cargo appends to
645    the specified `command` list:
646
647    For `command_args`, nailing cargo appends multiple more arguments;
648    each one should be passed as-is as a single argument to the actual
649    build command.  This is correct if `command` is a program like
650    `nice` or `really`, which takes a command and its arguments and
651    does not go via the shell.
652
653    For `command_sh`, nailing-cargo appends one single further
654    argument.  That argument is a shell command; nailing-cargo
655    constructs it by shell-quoting the real command and arguments and
656    wrapping them up in a small script, the text of which becomes the
657    extra argument to `command`.  This is correct if `command` will
658    pass its argument to a bournelike shell - for example, if `command`
659    is an ssh rune for a remote account whose shell is `/bin/sh` or
660    `/bin/bash`.
661
662  * `user`: The build username, for `really` and `ssh`.  For `ssh`, can
663    be just the local username (meaning `@localhost`), or
664    `<user>@<host>`.
665
666  * `clean` (boolean): When doing a `Cargo.lock` update, which involves
667    linkfarming in the build directory, whether the clean up the
668    linkfarm afterwards.  Default: `true`.  Can be overridden by
669    `--keep-linkfarm` or `--clean-linkfarm`.
670
671 `[arch]`: Architecture convenience aliases
672 ------------------------------------------
673
674 This is a map from archictecture aliases to full cargo architecture
675 names.  The keys are the aliases; each entry should be a string, the
676 cargo architecture name.
677
678 Only keys starting with an ascii uppercase letter are relevant, since
679 other names are not looked up in this alias map.
680
681 `[misc]`: Miscellaneous individual nailing-cargo config
682 -------------------------------------------------------
683
684  * <a name="misc_online">`online`</a>:
685
686    Specifies whether to allow or prevent cargo from accessing the
687    network.  Value is a boolean or `'auto'`.  `'auto'` permits online
688    access if the cargo subcommand being invoked is one whose main
689    purpose involves online access.
690
691    Implemented by passing `--offline` to cargo when necessary ---
692    cargo's default is online.  nailing-cargo's default is
693    `'auto'`.
694
695 Limitations and bugs
696 ====================
697
698   * nailing-cargo temporarily dirties your source trees, including
699     particularly `Cargo.toml` and `Cargo.lock`; and if nailing-cargo
700     crashes or is interrupted these changes may be left behind.
701     Unfortunately it is not possible to avoid this temporary dirtying
702     because the cargo team have deliberately made cargo inflexible -
703     [issue#6715](https://github.com/rust-lang/cargo/issues/6715).  
704     At least, running nailing-cargo again will clean up any mess
705     left by an interrupted run.
706
707   * nailing-cargo needs to understand the behaviour of the cargo
708     subcommand you are running - especially for out-of-tree builds.
709     nailing-cargo only has a short builtin list of commands it knows
710     about (see [`-s<subcommand`](#s_subcommand)).  For other commands, you may need to
711     add an entry to `@subcmd_props` in the source, or use
712     [`--subcommand-props`](#subcommand_props).
713
714     Contributions of additonal entries to `@subcmd_props` (or bug
715     reports about missing entries) are of course very welcome.
716
717   * Out-of-tree builds ought to support `sudo`.  Patches welcome.
718
719   * Out-of-tree builds require a unified filesystem view: eg, different
720     users on the same host, NFS, or something.
721
722     Specifically, the invocation and build execution environments must
723     both have visibility of the source and build directories, at the
724     same absolute pathnames.  The invocation environment must be able
725     to write to the build environment (but vice versa is not
726     required).
727
728     This could be improved.
729
730   * The alternative `Cargo.lock` filename must currently be a leafname.  I
731     think fixing this just involves review to check other values work
732     properly.
733
734   * The alternative `Cargo.lock` file must be on the same filesystem
735     as the source tree.  This is not so easy to fix; we would want the
736     existing algorithm but a fallback for the different-filsystem case.
737
738   * `Cargo.nail` is unconditionally looked for in the parent directory.
739     Ideally this should be configurable, and also perhaps be able to
740     combine multiple `Cargo.nail` files?  Relatedly, although
741     nailing-cargo can read multiple config files, it can only handle
742     one file specifying directories and packages.
743
744   * nailing-cargo uses a single lockfile alongside your `Cargo.nail`,
745     rather than a more sophisticated scheme involving locking
746     particular directories.  This means that if you run multiple
747     copies of nailing-cargo at once, in different directories, but
748     with `Cargo.nail` files which imply overlapping sets of package
749     directories, things will go Badly Wrong.
750
751   * Many real-world packages do not support out-of-tree builds
752     properly.  Doing so well is not easy because cargo does not
753     provide a package with all the path information needed to do a
754     good job.  Also the Rust community's infrastructure and tooling
755     does not do out-of-tree builds by default.
756
757     If you encounter such a package, `--linkfarm` will often help.
758
759   * git submodules are not supported.  In theory this could perhaps be
760     improved, but it is not trivial because git submodules are badly
761     broken.  If you can, avoid git submodule and use other techniques
762     instead (e.g., `git subtree`).
763
764 Contributing and legal
765 ======================
766
767 nailing-cargo is Free Software.
768
769 Please help improve it.  Contributions (to address the limitations, or
770 to add new facilities to help work with cargo) are welcome by email to
771 `ijackson@chiark.greenend.org.uk` or via the [Salsa
772 project](https://salsa.debian.org/iwj/nailing-cargo).
773
774 If you plan to do substantial work, please do get in touch with a
775 sketch of your proposed changes.
776
777 Legal
778 -----
779
780 This project accepts contributions based on the git commit
781 Signed-off-by convention, by which the contributors certify their
782 contributions according to the Developer Certificate of Origin version
783 1.1 - see the file DEVELOPER-CERTIFICATE.
784
785 Copyright (C) 2019-2021 Ian Jackson and others
786
787 This program is free software: you can redistribute it and/or modify
788 it under the terms of the GNU Affero General Public License as
789 published by the Free Software Foundation, either version 3 of the
790 License, or (at your option) any later version.
791
792 This program is distributed in the hope that it will be useful,
793 but WITHOUT ANY WARRANTY; without even the implied warranty of
794 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
795 GNU Affero General Public License for more details.
796
797 You should have received a copy of the GNU Affero General Public License
798 along with this program.  If not, see <http://www.gnu.org/licenses/>.
799
800 Individual files generally contain the following tag in the copyright
801 notice, instead of the full licence grant text:
802 ```
803    SPDX-License-Identifier: AGPL-3.0-or-later
804 ```
805 As is conventional, this should be read as a licence grant.