4 This is a wrapper tool for cargo, the Rust build tool and package
7 * Conveniently use local crates, including completely
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).
14 These functions are of course configurable.
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.
25 nailing-cargo is designed to be run out of a git clone:
28 $ git clone https://salsa.debian.org/iwj/nailing-cargo.git
29 $ ln -s `pwd`/nailing-cargo/nailing-cargo ~/bin
32 It is self-contained, depending only on a reasonably functional Perl
35 Most basic example usage
36 ------------------------
45 $ nailing-cargo -u fetch
49 Documentation table of contents
50 -------------------------------
52 <!-- TOC autogenerated by ./markdown-toc-filter, do not edit -->
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)
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)
80 Using local crates, or locally modified crates
81 ==============================================
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).)
90 Using a local version of a crate should be possible without putting
91 paths into your `Cargo.toml` and without editing complex
94 How nailing-cargo helps with using local crates
95 -----------------------------------------------
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.
101 Telling nailing-cargo how to massage `Cargo.toml`
102 -------------------------------------------------
104 To find the subdirectories, and the packages, nailing-cargo looks for
105 `subdirs` and `packages` in `Cargo.nail`.
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.
112 See the [Configuration reference](#configuration-reference) for full details.
114 Scope of nailing-cargo's local crate functionality
115 --------------------------------------------------
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.
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.
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)
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.
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.
148 How nailing-cargo helps with out-of-tree builds
149 -----------------------------------------------
151 nailing-cargo (configured appropriately) copies files back and forth
152 to between the source and build directories, and runs cargo as your
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`.
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.
166 Configuring out-of-tree builds
167 ------------------------------
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`.
173 Also, specify `dir`, or create a symlink `Build` next to `Cargo.nail`,
174 pointing to to your build area.
182 will have nailing-cargo run `ssh rustcargo@localhost` to
185 Target architecture convenience aliases
186 =======================================
188 If you are cross-building you may need to tell cargo `--target=`.
189 The architecture names are quite long and inconvenient.
191 A simple shell alias would help a lot, except that cargo rejects
192 `--target=` when it thinks it's not needed.
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.
199 Default change to offline mode
200 ==============================
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
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.
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`.
214 Invocation and command-line option reference
215 ============================================
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>...
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.)
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
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*`
240 ### Invocation argument disambiguation rules ###
242 For authors of tools which call nailing-cargo (and pedants):
244 The usages overlap in syntax! nailing-cargo follows the following
245 rules when interpreting its command line:
247 * The first option not recognised as a nailing-cargo option is
248 treated as the start of the `<cargo-opts>`.
250 * `<cargo-opts>` are terminated by `--` (which is removed) or the
251 first argument which does not start with a `-` or `+`.
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.)
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.
262 If the arguments after `nailing-cargo ... ---` might contain `--`
263 anywhere, an explicit `--` should be passed.
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).
274 * `-v`: Increase verbosity. Default is 1.
276 * `-q`: Set verbosity to 0.
278 * `-D`: Increase amount of debugging dump.
280 * `-n`: "No action": stop after writing `Cargo.toml.nailing~`
281 everywhere, and do not run any build command.
283 * `-f` | `--force`: Force going ahead even if problems are likely.
284 (E.g., due to missing `-E` option.)
286 * `-T<arch>` | `--target=<arch>`
288 Specify target architecture.
290 This option translates to a `--target=<arch>` option to cargo
291 (when the subcommand accepts it).
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
300 RPI="arm-unknown-linux-gnueabihf"
301 WASM="wasm32-unknown-unknown"
304 * `-o` | `--online` | `-O` | `--offline`
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),
312 * `-u` | `--cargo-lock-update` | `-U` | `--no-cargo-lock-update`
314 Allows (or disallows) cargo to update `Cargo.lock` in the source
315 directory. Without this enabled, nailing-cargo passes `--locked`
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.
323 Default is no update unless the whole point of the cargo
324 subcommand is to update `Cargo.lock`.
328 Controls the addition of cargo command line options; ie,
329 whether nailing-cargo should treat the build command as if it
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).
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).
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.
344 * <a name="s_subcommand">`-s<subcommand>`</a>
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`.
351 nailing-cargo knows about the following commands:
354 * `generate-lockfile`
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.
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.
370 * <a name="subcommand_props">`--subcommand-props=<prop>,...`</a>
372 Specify the properties of the subcommand. This is an
373 alternative to `-s<subcmd>`. The usual properties are:
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`.
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:
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.
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
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.
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`.
408 * `git`: Make a deep linkfarm, with subdirectories. Symlink
409 those objects tracked by git. This is the default for
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.
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`.
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.
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.)
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.
438 This option is overridden by a subsequent `--linkfarm` options.
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.
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).
449 With a linkfarming mode, overrides (and is overridden by)
450 `--linkfarm=`. Without a linkfarming mode, and without
451 `--linkfarm`, the default is `shallow`.
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.)
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
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.
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.
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.
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.
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
499 * `-h` | `--help`: Print usage summary.
501 * `--doc` | `--man` | `--manual`: Format this manual into html using
502 `pandoc` and display it with `w3m`.
504 Environment of the build command
505 --------------------------------
507 nailing-cargo passes these environment variables to the build command:
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`.
516 All of these are absolute paths.
518 ### Build commands which wrap cargo ###
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.
524 In such a situation, do it like this:
526 cargo build --manifest-path="${CARGO_MANIFEST_DIR-.}"/Cargo.toml $NAILINGCARGO_CARGO_OPTIONS
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
536 Configuration reference
537 =======================
539 nailing-cargo reads these configuration files:
541 /etc/nailing-cargo/cfg.toml
542 ~/.nailing-cargo.toml
543 ./.nailing-cargo.toml
544 ../Nailing-Cargo.toml
547 Settings in later-mentioned files override ones in earlier-mentioned
550 Source directories and packages (toplevel)
551 ------------------------------------------
553 Note that unlike everything else, these keys (`packages` and
554 `subdirs`) are read only from `Cargo.nail` (see "Limitations and
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`
561 * `packages`: a map keyed by package name, giving the subdirectory
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.)
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'`).
573 * `subdirs`: a list of subdirectory names to process.
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
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.)
587 In each case the subdirectory should usually be a relative pathname;
588 it is relative to the directory containing `Cargo.nail`.
590 `[alt_cargolock]`: Alternative `Cargo.lock` filename
591 ----------------------------------------------------
593 To control use of alternative `Cargo.lock` filename, use the section
594 `[alt_cargolock]`. Settings here:
596 * `file = <some leafname>`.
598 * `file = true`: Equivalent to `file = "Cargo.lock.example"`.
599 (This is the default.)
601 * `file = false`: Disables this feature.
603 * `force = false`: Uses the alternative filename only if it
604 already exists. (This is the default.)
606 * `force = true`: Always uses the alternative filename.
608 `[oot]`: Out-of-tree build support
609 ----------------------------------
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).
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.
620 * `use`: How to become the build user. Needs to be combined
621 with other setting(s):
623 * `ssh`: Use ssh. `user` must be given as well and can be
624 a username on localhost, or the `<user>@<host>`
627 * `command_args`: `command` must be specified as a list,
628 specifying a command and arguments which work like `nice`.
630 * `command_sh`: `command` must be specified as a list,
631 specifying a command and arguments which work like `sh -c`.
633 * `null`: Run builds as the same user.
635 * `really`: Use `really` from `chiark-really.deb`.
636 `user` must be given as well.
638 * `disable': Disable this feature, even if `dir` is set.
640 * `command`: The command to run for `command_sh` or `command_args`.
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:
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.
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
662 * `user`: The build username, for `really` and `ssh`. For `ssh`, can
663 be just the local username (meaning `@localhost`), or
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`.
671 `[arch]`: Architecture convenience aliases
672 ------------------------------------------
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.
678 Only keys starting with an ascii uppercase letter are relevant, since
679 other names are not looked up in this alias map.
681 `[misc]`: Miscellaneous individual nailing-cargo config
682 -------------------------------------------------------
684 * <a name="misc_online">`online`</a>:
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.
691 Implemented by passing `--offline` to cargo when necessary ---
692 cargo's default is online. nailing-cargo's default is
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.
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).
714 Contributions of additonal entries to `@subcmd_props` (or bug
715 reports about missing entries) are of course very welcome.
717 * Out-of-tree builds ought to support `sudo`. Patches welcome.
719 * Out-of-tree builds require a unified filesystem view: eg, different
720 users on the same host, NFS, or something.
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
728 This could be improved.
730 * The alternative `Cargo.lock` filename must currently be a leafname. I
731 think fixing this just involves review to check other values work
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.
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.
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.
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.
757 If you encounter such a package, `--linkfarm` will often help.
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`).
764 Contributing and legal
765 ======================
767 nailing-cargo is Free Software.
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).
774 If you plan to do substantial work, please do get in touch with a
775 sketch of your proposed changes.
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.
785 Copyright (C) 2019-2021 Ian Jackson and others
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.
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.
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/>.
800 Individual files generally contain the following tag in the copyright
801 notice, instead of the full licence grant text:
803 SPDX-License-Identifier: AGPL-3.0-or-later
805 As is conventional, this should be read as a licence grant.