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 generate-lockfile
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] for full details.
117 It is often desirable to run builds in a way that does not write to
118 the source tree. cargo's enthusiastic approach to the dependency
119 management task means that it is a good idea to try to insulate your
120 main working environment from the many things cargo has decided to
121 download and execute.
123 However, when you tell cargo to do an out of tree build (using
124 `--manifest-path`) it will insist on `Cargo.lock` being in the source
125 directory, and often will insist on writing to it.
127 How nailing-cargo helps with out-of-tree builds
128 -----------------------------------------------
130 nailing-cargo (configured appropriately) copies files back and forth
131 to between the source and build directories, and runs cargo as your
134 The `Cargo.lock` must still be saved in your source tree somewhere.
135 nailing-cargo arranges this for you. You can either put this file in
136 `.gitignore`; or commit it to git; or you can tell nailing-cargo to
137 save it as something like `Cargo.lock.example`.
139 Configuring out-of-tree builds
140 ------------------------------
142 To enable out-of-tree-builds, put an `[oot]` section in your
143 `Cargo.nail` or one of nailing-cargo's other config files.
144 In that section, specify at least `use`.
146 Also, specify `dir`, or create a symlink `Build` next to `Cargo.nail`,
147 pointing to to your build area.
155 will have nailing-cargo run `ssh rustcargo@localhost` to
158 Target architecture convenience aliases
159 =======================================
161 If you are cross-building you may need to tell cargo `--target=`.
162 The architecture names are quite long and inconvenient.
164 A simple shell alias would help a lot, except that cargo rejects
165 `--target=` when it thinks it's not needed.
167 In your nailing-cargo config, you can write something like
168 `arch.RPI='arm-unknown-linux-gnueabihf'`. Then `nailing-cargo -TRPI`
169 will DTRT. In fact, you do not even need to specify that particular
170 arch alias, since it is built-in to nailing-cargo.
172 Default change to offline mode
173 ==============================
175 It seems to me that build tools should be explicit about their use of
176 the network. So by default, nailing-cargo passes `--offline` to
179 If you disagree with my opinion, write `misc.online=true` in your
180 nailing-cargo configuration. `misc.online=false`, and command line
181 options, are also available, for overriding.
183 Invocation and command-line option reference
184 ============================================
190 1$ nailing-cargo <nailing-opts> <cargo-opts> [--] <subcmd>...
191 2$ nailing-cargo <nailing-opts> --- <cargo> <cargo-opts> [--] <subcmd>...
192 3$ nailing-cargo <nailing-opts> --- [--] <build-command>...
194 Ususally the `--` is not needed. (It should generally be passed by
195 programs which wrap nailing-cargo. See [Invocation argument disambiguation rules], below.)
197 In usage 1, nailing-cargo runs `cargo` (from `PATH`). In the usage 2
198 nailing-cargo runs `<cargo>`. In both these cases it adds its own
199 options to control cargo's behaviour. In both of these cases
200 nailing-cargo looks at `<subcmd>` to determine the cargo subcommand
201 being run: this controls various defaults, to try to do the right
204 In the third syntax, nailing-cargo runs `<build-command>...` without
205 additional arguments and does not attempt to identify the cargo
206 subcommand(s) that it will run. Possibly it will be necessary to pass
207 `--online` or `--cargo-lock-update`, or even `--cargo-*arg*`
209 ### Invocation argument disambiguation rules ###
211 For authors of tools which call nailing-cargo (and pedants):
213 The usages overlap in syntax! nailing-cargo follows the following
214 rules when interpreting its command line:
216 * The first option not recognised as a nailing-cargo option is
217 treated as the start of the `<cargo-opts>`.
219 * `<cargo-opts>` are terminated by `--` (which is removed) or the
220 first argument which does not start with a `-`.
222 (It is not possible to get nailing-cargo to pass the value `--`
223 as a separate argument to a cargo global option, but cargo global
224 options can typically take the values cuddled with `=`, so doing
225 that is not necessary.)
227 * After `---`, nailing-cargo will search for a `--`, to the end of
228 the arguments if necessary. The position of the `--` determines
229 whether this is usage 2 or usage 3, and what `<subcmd>` is.
231 If the arguments after `nailing-cargo ... ---` might contain `--`
232 anywhere, an explicit `--` should be passed.
234 * If no `--` appears after `---`, the word after `---` is the
235 command to run; if its final pathname component contains the
236 string `cargo`, it is treated as `<cargo>` (implying usage 2 and
237 the search for `<subcmd>`). Otherwise it is treated as
238 `<build-command>` (usage 3).
243 * `-v`: Increase verbosity. Default is 1.
245 * `-q`: Set verbosity to 0.
247 * `-D`: Increase amount of debugging dump.
249 * `-n`: "No action": stop after writing `Cargo.toml.nailing~`
250 everywhere, and do not run any build command.
252 * `-T<arch>` | `--target=<arch>`
254 Specify target architecture.
256 This option translates to a `--target=<arch>` option to cargo
257 (when the subcommand accepts it).
259 If `<arch>` starts with a capital ascii letter, it is an alias
260 for some other arch: it is looked up in the configuration, and
261 then in the builtin arch alias list. The builtin list is
262 equivalent to: `[arch]` `RPI='arm-unknown-linux-gnueabihf'`.
264 * `-o` | `--online` | `-O` | `--offline`
266 Whether to allow cargo to make network access. nailing-cargo
267 always passes `--offline` to cargo, unless `--online` is in
268 force. The default value depends on the configuration and the
269 cargo subcommand - see [`[misc]` `online`](#misc_online),
272 * `-u` | `--cargo-lock-update` | `-U` | `--no-cargo-lock-update`
274 Enables, or disables, the dance to allow `Cargo.lock` (or
275 alternative) to be updated in the source directory.
277 With this dance enabled the `Cargo.lock` and `Cargo.toml` are
278 copied to the build directory along with a skeleton just big
279 enough to fool cargo. After cargo has run, the resulting
280 `Cargo.lock` is copied back to the source tree.
282 This makes no sense with in-tree builds.
284 Default is no update unless the cargo subcommand will want it.
288 Controls the addition of cargo command line options; ie,
289 whether nailing-cargo should treat the build command as if it
291 With `-C`, nailing-cargo will not add additional options
292 to the build command. With `-c` it will pass those options
293 after the cargo subcommand (usages 1 and 2) or right
294 after the build command (usage 3).
296 The cargo options are in any case also passed in the
297 environment - see [Environment of the build command].
299 The default is to pass cargo options if the command line
300 parsing yielded a cargo command and options (usages 1 and 2),
301 rather than a non-cargo build command (usage 3). `-C` and `-c`
302 do not affect the parsing of nailing-cargo's command line.
304 * <a name="s_subcommand">`-s<subcommand>`</a>
306 Behave as if the build command were `cargo <subcommand>`.
307 This influences the logic which tries to determine which
308 options to pass to cargo, whether cargo needs to be online, and
309 whether cargo might want to update `Cargo.lock`.
311 nailing-cargo knows about `update`, `generate-lockfile` and
312 `fetch`; all other subcommands are (silently) treated the same way
313 as `build` (ie, no subcommand properties). See
314 `--subcommand-props` for more detail about how the
315 subcommand affects nailing-cargo's behaviour.
317 The default is to use the cargo subcommand found from parsing
318 nailing-cargo's command line. NB: `-s` does not affect
319 which build command (and which cargo subcommand) is actually run.
321 * <a name="subcommand_props">`--subcommand-props=<prop>,...`</a>
323 Specify the properties of the subcommand. This is an
324 alternative to `-s<subcmd>`. The usual properties are:
326 * `lock_update`: cargo will want to update `Cargo.lock`. (The `-u` and `-U` options override this.)
327 * `online`: this subcommand makes no sense to run offline. (The `-o` and `-O` options, and the configuration, can override this.)
328 * `!target`: cargo would reject `--target=<arch>`; in this case nailing-cargo's `-T` option is ineffective.
329 * `!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`.)
331 There are also some properties which should not be needed, but are
332 provided for completeness. Do not use these to solve the problem
333 of nailing-cargo passing cargo options to a build command which is
334 not cargo - use `-C` for that. The properties whose use is discouraged:
336 * `!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`.
337 * `!locked`: cargo would reject `--locked`, so don't pass it. Hazardous.
338 * `!offline`: the build command would reject `--offline`, so never pass it. *Not* overridden by configuration or command line.
340 Environment of the build command
341 --------------------------------
343 nailing-cargo passes these environment variables to the build command:
345 * `CARGO_MANIFEST_DIR`: invocation `.` (invocation directory)
346 * `NAILINGCARGO_MANIFEST_DIR`: same as `CARGO_MANIFEST_DIR`
347 * `NAILINGCARGO_WORKSPHERE`: invocation `..` (parent)
348 * `NAILINGCARGO_BUILD_DIR`: build directory (even if same as source)
349 * `NAILINGCARGO_BUILDSPHERE`: parent of build dir (only set if out-of-tree)
350 * `NAILINGCARGO_CARGO_OPTIONS`: additional options that nailing-cargo passed (or would pass) to cargo. Space-separated; does not include `--manifest-path`.
352 All of these are absolute paths.
354 ### Build commands which wrap cargo ###
356 If you specify a build command which eventually runs cargo, you may
357 wish to pass on to your cargo the options which nailing-cargo would
358 have passed. This will definitely be necessary if you are using nailing-cargo's out-of-tree facility.
360 In such a situation, do it like this:
362 cargo build --manifest-path="${CARGO_MANIFEST_DIR-.}"/Cargo.toml $NAILINGCARGO_CARGO_OPTIONS
365 If you need to run a cargo subcommand which doesn't understand some of
366 nailing-cargo's options, currently, you must strip them out of
367 `NAILINGCARGO_CARGO_OPTIONS` yourself - or pass some `-s` or
368 `--subcmd-props` option to nailing-cargo (but that is a layering
369 violation and may not work if one build command runs various different
372 Configuration reference
373 =======================
375 nailing-cargo reads these configuration files:
377 /etc/nailing-cargo/cfg.toml
378 ~/.nailing-cargo.toml
379 ./.nailing-cargo.toml
380 ../Nailing-Cargo.toml
383 Settings in later-mentioned files override ones in earlier-mentioned
386 Source directories and packages (toplevel)
387 ------------------------------------------
389 Note that unlike everything else, these keys (`packages` and
390 `subdirs`) are read only from `Cargo.nail` (see "Limitations and
393 These keys specify a combination of (i) a mapping from package name to
394 source subdirectory (ii) a set of subdirectories whose `Cargo.toml`
397 * `packages`: a map keyed by package name, giving the subdirectory
400 This causes each mentioned subdirectory's `Cargo.toml` to be
401 massaged, and records that subdirectory as the source for that
402 package. (nailing-cargo will check that subdirectory actually
403 contains the indicated package.)
405 Each value can be just the subdirectory name (eg `[packages]`
406 `mylibrary='mylibrary-test'`) or itself a map with the key `subdir`
407 (eg `[packages.mylibrary]` `subdir='mylibrary-test'`).
409 * `subdirs`: a list of subdirectory names to process.
411 Each subdirectory's `Cargo.toml` will be massaged. Also, the
412 subdirectory will be examined to see what package it contains; it
413 will then be used as the source for that package, unless that
414 package appears in an entry in `packages`, or an earlier entry in
417 This can be a list of strings (eg `subdirs =
418 ['myproject','mylibrary']`). Or it can be single multi-line
419 string containing one subdirectory name per line; in that
420 case, `#`-comments are supported and tabs and spaces are ignored
421 (see "Most basic example usage" above.)
423 In each case the subdirectory should usually be a relative pathname;
424 it is relative to the directory containing `Cargo.nail`.
426 `[alt_cargolock]`: Alternative `Cargo.lock` filename
427 ----------------------------------------------------
429 To control use of alternative `Cargo.lock` filename, use the section
430 `[alt_cargolock]`. Settings here:
432 * `file = <some leafname>`.
434 * `file = true`: Equivalent to `file = "Cargo.lock.example"`.
435 (This is the default.)
437 * `file = false`: Disables this feature.
439 * `force = false`: Uses the alternative filename only if it
440 already exists. (This is the default.)
442 * `force = true`: Always uses the alternative filename.
444 `[oot]`: Out-of-tree build support
445 ----------------------------------
447 * `dir`: The build directory. If relative, it is relative to the
448 parent of the invocation directory (and could be a symlink then).
449 Default is `Build` (assuming `use` is specified).
451 The build directory will contain one subdir for each package: each
452 subdir in the build dir corresponds to one source dir where
453 nailing-cargo was invoked. nailing-cargo will arrange to create
454 these subdirectories, so the build directory can start out empty.
456 * `use`: How to become the build user. Needs to be combined
457 with other setting(s):
459 * `ssh`: Use ssh. `user` must be given as well and can be
460 a username on localhost, or the `<user>@<host>`
463 * `command_args`: `command` must be specified as a list,
464 specifying a command and arguments which work like `nice`.
466 * `command_sh`: `command` must be specified as a list,
467 specifying a command and arguments which work like `sh -c`.
469 * `null`: Run builds as the same user.
471 * `really`: Use `really` from `chiark-really.deb`.
472 `user` must be given as well.
474 * `disable': Disable this feature, even if `dir` is set.
476 * `command`: The command to run for `command_sh` or `command_args`.
478 In both cases, this is a command and its arguments/options. The
479 list will be passed to `execvp`. The difference between
480 `command_args` and `command_sh` is in what nailing-cargo appends to
481 the specified `command` list:
483 For `command_args`, nailing cargo appends multiple more arguments;
484 each one should be passed as-is as a single argument to the actual
485 build command. This is correct if `command` is a program like
486 `nice` or `really`, which takes a command and its arguments and
487 does not go via the shell.
489 For `command_sh`, nailing-cargo appends one single further
490 argument. That argument is a shell command; nailing-cargo
491 constructs it by shell-quoting the real command and arguments and
492 wrapping them up in a small script, the text of which becomes the
493 extra argument to `command`. This is correct if `command` will
494 pass its argument to a bournelike shell - for example, if `command`
495 is an ssh rune for a remote account whose shell is `/bin/sh` or
498 * `user`: The build username, for `really` and `ssh`. For `ssh`, can
499 be just the local username (meaning `@localhost`), or
502 `[arch]`: Architecture convenience aliases
503 ------------------------------------------
505 This is a map from archictecture aliases to full cargo architecture
506 names. The keys are the aliases; each entry should be a string, the
507 cargo architecture name.
509 Only keys starting with an ascii uppercase letter are relevant, since
510 other names are not looked up in this alias map.
512 `[misc]`: Miscellaneous individual nailing-cargo config
513 -------------------------------------------------------
515 * <a name="misc_online">`online`</a>: boolean, specifying whether to
516 pass `--offline` to cargo (cargo's default is online mode). The
517 default is offline, unless nailing-cargo can see that the cargo
518 subcommand being invoked is one which requires online access, in
519 which case the default is online.
524 * nailing-cargo temporarily dirties your source trees, including
525 particularly `Cargo.toml` and `Cargo.lock`; and if nailing-cargo
526 crashes or is interrupted these changes may be left behind.
527 Unfortunately it is not possible to avoid this temporary dirtying
528 because the cargo team have deliberately made cargo inflexible -
529 [issue#6715](https://github.com/rust-lang/cargo/issues/6715).
530 At least, running nailing-cargo again will clean up any mess
531 left by an interrupted run.
533 * nailing-cargo needs to understand the behaviour of the cargo
534 subcommand you are running - especially for out-of-tree builds.
535 nailing-cargo only has a short builtin list of commands it knows
536 about (see [`-s<subcommand`](#s_subcommand)). For other commands, you may need to
537 add an entry to `@subcmd_props` in the source, or use
538 [`--subcommand-props`](#subcommand_props).
540 Contributions of additonal entries to `@subcmd_props` (or bug
541 reports about missing entries) are of course very welcome.
543 * Out-of-tree builds ought to support `sudo`. Patches welcome.
545 * Out-of-tree builds require a unified filesystem view: eg, different
546 users on the same host, NFS, or something.
548 Specifically, the invocation and build execution environments must
549 both have visibility of the source and build directories, at the
550 same absolute pathnames. The invocation environment must be able
551 to write to the build environment (but vice versa is not
554 This could be improved.
556 * The alternative `Cargo.lock` filename must currently be a leafname. I
557 think fixing this just involves review to check other values work
560 * The alternative `Cargo.lock` file must be on the same filesystem
561 as the source tree. This is not so easy to fix; we would want the
562 existing algorithm but a fallback for the different-filsystem case.
564 * `Cargo.nail` is unconditionally looked for in the parent directory.
565 Ideally this should be configurable, and also perhaps be able to
566 combine multiple `Cargo.nail` files? Relatedly, although
567 nailing-cargo can read multiple config files, it can only handle
568 one file specifying directories and packages.
570 * nailing-cargo uses a single lockfile alongside your `Cargo.nail`,
571 rather than a more sophisticated scheme involving locking
572 particular directories. This means that if you run multiple
573 copies of nailing-cargo at once, in different directories, but
574 with `Cargo.nail` files which imply overlapping sets of package
575 directories, things will go Badly Wrong.
577 Contributing and legal
578 ======================
580 nailing-cargo is Free Software.
582 Please help improve it. Contributions (to address the limitations, or
583 to add new facilities to help work with cargo) are welcome by email to
584 `ijackson@chiark.greenend.org.uk` or via the [Salsa
585 project](https://salsa.debian.org/iwj/nailing-cargo).
587 If you plan to do substantial work, please do get in touch with a
588 sketch of your proposed changes.
593 This project accepts contributions based on the git commit
594 Signed-off-by convention, by which the contributors certify their
595 contributions according to the Developer Certificate of Origin version
596 1.1 - see the file DEVELOPER-CERTIFICATE.
598 Copyright (C) 2019-2020 Ian Jackson and others
600 This program is free software: you can redistribute it and/or modify
601 it under the terms of the GNU Affero General Public License as
602 published by the Free Software Foundation, either version 3 of the
603 License, or (at your option) any later version.
605 This program is distributed in the hope that it will be useful,
606 but WITHOUT ANY WARRANTY; without even the implied warranty of
607 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
608 GNU Affero General Public License for more details.
610 You should have received a copy of the GNU Affero General Public License
611 along with this program. If not, see <http://www.gnu.org/licenses/>.
613 Individual files generally contain the following tag in the copyright
614 notice, instead of the full licence grant text:
616 SPDX-License-Identifier: AGPL-3.0-or-later
618 As is conventional, this should be read as a licence grant.