4 This is a wrapper tool for cargo, the Rust build tool and package
7 * Conveniently use local crates, including completely
10 * Perform out-of-tree builds, including in an account with
11 no write access to the source tree.
13 * Provide convenience aliases for target architecture names.
15 * Make the default be offline (ie, not to access the internet)
17 These functions are of course configurable.
19 The primary source of information for nailing-cargo is the file
20 `../Cargo.nail` (which is in TOML syntax). You put `Cargo.nail`
21 alongside the top-level git repositories you are working with, and
22 invoke nailing-cargo from the git directory containing the Rust
23 package you want to build.
28 nailing-cargo is designed to be run out of a git clone:
31 $ git clone https://salsa.debian.org/iwj/nailing-cargo.git
32 $ ln -s `pwd`/nailing-cargo/nailing-cargo ~/bin
35 It is self-contained, depending only on a reasonably functional Perl
38 Most basic example usage
39 ------------------------
48 $ nailing-cargo generate-lockfile
52 Documentation table of contents
53 -------------------------------
55 <!-- TOC autogenerated by ./markdown-toc-filter, do not edit -->
57 * [Introduction](#nailing-cargo)
58 * [Installing](#installing)
59 * [Most basic example usage](#most-basic-example-usage)
60 * [Documentation table of contents](#documentation-table-of-contents)
61 * [Using local crates, or locally modified crates](#using-local-crates-or-locally-modified-crates)
62 * [How nailing-cargo helps with using local crates](#how-nailing-cargo-helps-with-using-local-crates)
63 * [Telling nailing-cargo how to massage `Cargo.toml`](#telling-nailing-cargo-how-to-massage-cargo.toml)
64 * [Out-of-tree builds](#out-of-tree-builds)
65 * [How nailing-cargo helps with out-of-tree builds](#how-nailing-cargo-helps-with-out-of-tree-builds)
66 * [Configuring out-of-tree builds](#configuring-out-of-tree-builds)
67 * [Target architecture convenience aliases](#target-architecture-convenience-aliases)
68 * [Default change to offline mode](#default-change-to-offline-mode)
69 * [Invocation and command-line option reference](#invocation-and-command-line-option-reference)
72 * [Environment of the build command](#environment-of-the-build-command)
73 * [Configuration reference](#configuration-reference)
74 * [Source directories and packages (toplevel)](#source-directories-and-packages-toplevel)
75 * [`[alt_cargolock]`: Alternative `Cargo.lock` filename](#alt_cargolock-alternative-cargo.lock-filename)
76 * [`[oot]`: Out-of-tree build support](#oot-out-of-tree-build-support)
77 * [`[arch]`: Architecture convenience aliases](#arch-architecture-convenience-aliases)
78 * [`[misc]`: Miscellaneous individual nailing-cargo config](#misc-miscellaneous-individual-nailing-cargo-config)
79 * [Limitations and bugs](#limitations-and-bugs)
80 * [Contributing and legal](#contributing-and-legal)
83 Using local crates, or locally modified crates
84 ==============================================
86 cargo does not work well with local crates,
87 especially completely unpublished ones.
88 (See [issue#6713](https://github.com/rust-lang/cargo/issues/6713),
89 [stackoverflow](https://stackoverflow.com/questions/33025887/how-to-use-a-local-unpublished-crate),
90 [issue#1481](https://github.com/rust-lang/cargo/issues/1481),
91 [my blog](https://diziet.dreamwidth.org/1805.html).)
93 Using a local version of a crate should be possible without putting
94 paths into your `Cargo.toml` and without editing complex
97 How nailing-cargo helps with using local crates
98 -----------------------------------------------
100 nailing-cargo temporarily edits all the `Cargo.toml` files in all the
101 subdirectories you mention, to refer to each other; then it runs
102 cargo; and then it puts everything back.
104 Telling nailing-cargo how to massage `Cargo.toml`
105 -------------------------------------------------
107 To find the subdirectories, and the packages, it looks for `subdirs`
108 and `packages` in `Cargo.nail`.
110 For straightforward use, write `subdirs` as a multi-line string
111 containing a list of subdirectory names one per line. In each of
112 these directories `Cargo.toml` will be massaged, and the package there
113 will be used for other massaged `Cargo.toml`s.
115 See "Configuration reference", below, for full details.
120 It is often desirable to run builds in a way that does not write to
121 the source tree. cargo's enthusiastic approach to the dependency
122 management task means that it is a good idea to try to insulate your
123 main working environment from the many things cargo has decided to
124 download and execute.
126 However, when you tell cargo to do an out of tree build (using
127 `--manifest-path`) it will insist on `Cargo.lock` being in the source
128 directory, and often will insist on writing to it.
130 How nailing-cargo helps with out-of-tree builds
131 -----------------------------------------------
133 nailing-cargo (configured appropriately) copies files back and forth
134 to between the source and build directories, and runs cargo as your
137 The `Cargo.lock` must still be saved in your source tree somewhere.
138 nailing-cargo arranges this for you. You can either put this file in
139 `.gitignore`; or commit it to git; or you can tell nailing-cargo to
140 save it as something like `Cargo.lock.example`.
142 Configuring out-of-tree builds
143 ------------------------------
145 To enable out-of-tree-builds, put an `[oot]` section in your
146 `Cargo.nail` or one of nailing-cargo's other config files.
147 In that section, specify at least `use`.
149 Also, specify `dir`, or create a symlink `Build` next to `Cargo.nail`,
150 pointing to to your build area.
158 will have nailing-cargo run `ssh rustcargo@localhost` to
161 Target architecture convenience aliases
162 =======================================
164 If you are cross-building you may need to tell cargo `--target=`.
165 The architecture names are quite long and inconvenient.
167 A simple shell alias would help a lot, except that cargo rejects
168 `--target=` when it thinks it's not needed.
170 In your nailing-cargo config, you can write something like
171 `arch.RPI='arm-unknown-linux-gnueabihf'`. Then `nailing-cargo -ARPI`
172 will DTRT. In fact, you do not even need to specify that particular
173 arch alias, since it is built-in to nailing-cargo.
175 Default change to offline mode
176 ==============================
178 It seems to me that build tools should be explicit about their use of
179 the network. So by default, nailing-cargo passes `--offline` to
182 If you disagree with my opinion, write `misc.online=true` in your
183 nailing-cargo configuration. `misc.online=false`, and command line
184 options, are also available, for overriding.
186 Invocation and command-line option reference
187 ============================================
193 1$ nailing-cargo <nailing-opts> <cargo-opts> [--] <subcmd>...
194 2$ nailing-cargo <nailing-opts> --- <cargo> <cargo-opts> [--] <subcmd>...
195 3$ nailing-cargo <nailing-opts> --- [--] <build-command>...
197 Ususally the `--` is not needed. (It should generally be passed by
198 programs which wrap nailing-cargo. See below.)
200 In usage 1, nailing-cargo runs `cargo` (from `PATH`). In the usage 2
201 nailing-cargo runs `<cargo>`. In both these cases it adds its own
202 options to control cargo's behaviour. In both of these cases
203 nailing-cargo looks at `<subcmd>` to determine the cargo subcommand
204 being run: this controls various defaults, to try to do the right
207 In the third syntax, nailing-cargo runs `<build-command>...` without
208 additional arguments and does not attempt to identify the cargo
209 subcommand(s) that it will run. Possibly it will be necessary to pass
210 `--online` or `--cargo-lock-update`, or even `--cargo-*arg*`
212 ### Invocation argument disambiguation rules ###
214 For authors of tools which call nailing-cargo (and pedants):
216 The usages overlap in syntax! nailing-cargo follows the following
217 rules when interpreting its command line:
219 * The first option not recognised as a nailing-cargo option is
220 treated as the start of the `<cargo-opts>`.
222 * `<cargo-opts>` are terminated by `--` (which is removed) or the
223 first argument which does not start with a `-`.
225 (It is not possible to get nailing-cargo to pass the value `--`
226 as a separate argument to a cargo global option, but cargo global
227 options can typically take the values cuddled with `=`, so doing
228 that is not necessary.)
230 * After `---`, nailing-cargo will search for a `--`, to the end of
231 the arguments if necessary. The position of the `--` determines
232 whether this is usage 2 or usage 3, and what `<subcmd>` is.
234 If the arguments after `nailing-cargo ... ---` might contain `--`
235 anywhere, an explicit `--` should be passed.
237 * If no `--` appears after `---`, the word after `---` is the
238 command to run; if its final pathname component contains the
239 string `cargo`, it is treated as `<cargo>` (implying usage 2 and
240 the search for `<subcmd>`). Otherwise it is treated as
241 `<build-command>` (usage 3).
246 * `-v`: Increase verbosity. Default is 1.
248 * `-q`: Set verbosity to 0.
250 * `-D`: Increase amount of debugging dump.
252 * `-n`: "No action": stop after writing `Cargo.toml.nailing~`
253 everywhere, and do not run any build command.
255 * `-T<arch>` | `--target=<arch>`
257 Specify target architecture.
259 This option translates to a `--target=<arch>` option to cargo
260 (when the subcommand accepts it).
262 If `<arch>` starts with a capital ascii letter, it is an alias
263 for some other arch: it is looked up in the configuration, and
264 then in the builtin arch alias list. The builtin list is
265 equivalent to: `[arch]` `RPI='arm-unknown-linux-gnueabihf'`.
269 Behave as if the build command were `cargo <subcommand>`.
270 This influences the logic which tries to determine which
271 options to pass to cargo, whether cargo needs to be online, and
272 whether cargo might want to update `Cargo.lock`.
274 nailing-cargo knows about `update`, `generate-lockfile` and
275 `fetch`; all other subcommands are (silently) treated the same
276 way as `build` (ie, no subcommand properties). See
277 `--subcommand-props`, below, for more detail about how the
278 subcommand affects nailing-cargo's behaviour.
280 This option does not affect which build command (and which
281 cargo subcommand) is actually run. The default is to use the
282 cargo subcommand found from parsing nailing-cargo's
287 Controls the addition of cargo command line options; ie,
288 whether nailing-cargo should treat the build command as if it
290 With `-C`, nailing-cargo will not add additional options
291 to the build command. With `-c` it will pass those options
292 after the cargo subcommand (usages 1 and 2) or right
293 after the build command (usage 3).
295 The cargo options are in any case also passed in the
296 environment - see [Environment of the build command].
298 The default is to pass cargo options if the command line
299 parsing yielded a cargo command and options (usages 1 and 2),
300 rather than a non-cargo build command (usage 3). `-C` and `-c`
301 do not affect the parsing of nailing-cargo's command line.
303 * `-o` | `--online` | `-O` | `--offline`
305 Whether to allow cargo to make network access. nailing-cargo
306 always passes `--offline` to cargo, unless `--online` is in
307 force. The default value depends on the configuration and the
308 cargo subcommand - see `[misc]` `online` in "Configuration".
310 * `-u` | `--cargo-lock-update` | `-U` | `--no-cargo-lock-update`
312 Enables, or disables, the dance to allow `Cargo.lock` (or
313 alternative) to be updated in the source directory.
315 With this dance enabled the `Cargo.lock` and `Cargo.toml` are
316 copied to the build directory along with a skeleton just big
317 enough to fool cargo. After cargo has run, the resulting
318 `Cargo.lock` is copied back to the source tree.
320 This makes no sense with in-tree builds.
322 Default is no update unless the cargo subcommand will want it.
324 * `--subcommand-props=<prop>,...`
326 Specify the properties of the subcommand. This is an
327 alternative to `-s<subcmd>`. The usual properties are:
329 * `lock_update`: cargo will want to update `Cargo.lock`. (The `-u` and `-U` options override this.)
330 * `online`: this subcommand makes no sense to run offline. (The `-o` and `-O` options, and the configuration, can override this.)
331 * `!target`: cargo would reject `--target=<arch>`; in this case nailing-cargo's `-T` option is ineffective.
332 * `!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`.)
334 There are also some properties which should not be needed, but are
335 provided for completeness. Do not use these to solve the problem
336 of nailing-cargo passing cargo options to a build command which is
337 not cargo - use `-C` for that. The properties whose use is discouraged:
339 * `!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`.
340 * `!locked`: cargo would reject `--locked`, so don't pass it. Hazardous.
341 * `!offline`: the build command would reject `--offline`, so never pass it. *Not* overridden by configuration or command line.
343 Environment of the build command
344 --------------------------------
346 nailing-cargo passes these environment variables to the build command:
348 * `CARGO_MANIFEST_DIR`: invocation `.` (invocation directory)
349 * `NAILINGCARGO_MANIFEST_DIR`: same as `CARGO_MANIFEST_DIR`
350 * `NAILINGCARGO_WORKSPHERE`: invocation `..` (parent)
351 * `NAILINGCARGO_BUILD_DIR`: build directory (even if same as source)
352 * `NAILINGCARGO_BUILDSPHERE`: parent of build dir (only set if out-of-tree)
353 * `NAILINGCARGO_CARGO_OPTIONS`: additional options that nailing-cargo passed (or would pass) to cargo. Space-separated; does not include `--manifest-path`.
355 All of these are absolute paths.
357 ### Build commands which wrap cargo ###
359 If you specify a build command which eventually runs cargo, you may
360 wish to pass on to your cargo the options which nailing-cargo would
361 have passed. This will definitely be necessary if you are using nailing-cargo's out-of-tree facility.
363 In such a situation, do it like this:
365 cargo build --manifest-path="${CARGO_MANIFEST_DIR-.}"/Cargo.toml $NAILINGCARGO_CARGO_OPTIONS
368 If you need to run a cargo subcommand which doesn't understand some of
369 nailing-cargo's options, currently, you must strip them out of
370 `NAILINGCARGO_CARGO_OPTIONS` yourself - or pass some `-s` or
371 `--subcmd-props` option to nailing-cargo (but that is a layering
372 violation and may not work if one build command runs various different
375 Configuration reference
376 =======================
378 nailing-cargo reads these configuration files:
380 /etc/nailing-cargo/cfg.toml
381 ~/.nailing-cargo.toml
382 ./.nailing-cargo.toml
383 ../Nailing-Cargo.toml
386 Settings in later-mentioned files override ones in earlier-mentioned
389 Source directories and packages (toplevel)
390 ------------------------------------------
392 Note that unlike everything else, these keys (`packages` and
393 `subdirs`) are read only from `Cargo.nail` (see "Limitations and
396 These keys specify a combination of (i) a mapping from package name to
397 source subdirectory (ii) a set of subdirectories whose `Cargo.toml`
400 * `packages`: a map keyed by package name, giving the subdirectory
403 This causes each mentioned subdirectory's `Cargo.toml` to be
404 massaged, and records that subdirectory as the source for that
405 package. (nailing-cargo will check that subdirectory actually
406 contains the indicated package.)
408 Each value can be just the subdirectory name (eg `[packages]`
409 `mylibrary='mylibrary-test'`) or itself a map with the key `subdir`
410 (eg `[packages.mylibrary]` `subdir='mylibrary-test'`).
412 * `subdirs`: a list of subdirectory names to process.
414 Each subdirectory's `Cargo.toml` will be massaged. Also, the
415 subdirectory will be examined to see what package it contains; it
416 will then be used as the source for that package, unless that
417 package appears in an entry in `packages`, or an earlier entry in
420 This can be a list of strings (eg `subdirs =
421 ['myproject','mylibrary']`). Or it can be single multi-line
422 string containing one subdirectory name per line; in that
423 case, `#`-comments are supported and tabs and spaces are ignored
424 (see "Most basic example usage" above.)
426 In each case the subdirectory should usually be a relative pathname;
427 it is relative to the directory containing `Cargo.nail`.
429 `[alt_cargolock]`: Alternative `Cargo.lock` filename
430 ----------------------------------------------------
432 To control use of alternative `Cargo.lock` filename, use the section
433 `[alt_cargolock]`. Settings here:
435 * `file = <some leafname>`.
437 * `file = true`: Equivalent to `file = "Cargo.lock.example"`.
438 (This is the default.)
440 * `file = false`: Disables this feature.
442 * `force = false`: Uses the alternative filename only if it
443 already exists. (This is the default.)
445 * `force = true`: Always uses the alternative filename.
447 `[oot]`: Out-of-tree build support
448 ----------------------------------
450 * `dir`: The build directory. If relative, it is relative to the
451 parent of the invocation directory (and could be a symlink then).
452 Default is `Build` (assuming `use` is specified).
454 The build directory will contain one subdir for each package: each
455 subdir in the build dir corresponds to one source dir where
456 nailing-cargo was invoked. nailing-cargo will arrange to create
457 these subdirectories, so the build directory can start out empty.
459 * `use`: How to become the build user. Needs to be combined
460 with other setting(s):
462 * `ssh`: Use ssh. `user` must be given as well and can be
463 a username on localhost, or the `<user>@<host>`
466 * `command_args`: `command` must be specified as a list,
467 specifying a command and arguments which work like `nice`.
469 * `command_sh`: `command` must be specified as a list,
470 specifying a command and arguments which work like `sh -c`.
472 * `null`: Run builds as the same user.
474 * `really`: Use `really` from `chiark-really.deb`.
475 `user` must be given as well.
477 * `disable': Disable this feature, even if `dir` is set.
479 * `command`: The command to run for `command_sh` or `command_args`.
481 * `user`: The local username for `really` and `ssh`, or
482 `<user>@<host>` for `ssh`.
484 `[arch]`: Architecture convenience aliases
485 ------------------------------------------
487 This is a map from archictecture aliases to full cargo architecture
488 names. The keys are the aliases; each entry should be a string, the
489 cargo architecture name.
491 Only keys starting with an ascii uppercase letter are relevant, since
492 other names are not looked up in this alias map.
494 `[misc]`: Miscellaneous individual nailing-cargo config
495 -------------------------------------------------------
497 * `online`: boolean, specifying whether to pass `--offline` to cargo
498 (cargo's default is online mode). The default is offline, unless
499 nailing-cargo can see that the cargo subcommand being invoked is
500 one which requires online access (currently, `fetch`), in which
501 case the default is online.
506 * nailing-cargo temporarily dirties your source trees, including
507 particularly `Cargo.toml` and `Cargo.lock`; and if nailing-cargo
508 crashes or is interrupted these changes may be left behind.
509 Unfortunately it is not possible to avoid this temporary dirtying
510 because the cargo team have deliberately made cargo inflexible -
511 [issue#6715](https://github.com/rust-lang/cargo/issues/6715).
512 At least, running nailing-cargo again will clean up any mess
513 left by an interrupted run.
515 * nailing-cargo needs to understand the behaviour of the cargo
516 subcommand you are running - especially for out-of-tree builds.
517 nailing-cargo only has a short builtin list of commands it knows
518 about (see the `-s` option). For other commands, you may need to
519 add an entry to `@subcmd_propss` in the source, or use
520 `--subcommand-props`.
522 * Out of tree builds require a unified filesystem view: eg, different
523 users on the same host, NFS, or something.
525 Specifically, the invocation and build execution environments must
526 both have visibility of the source and build directories, at the
527 same absolute pathnames. The invocation environment must be able
528 to write to the build environment (but vice versa is not
531 This could be improved.
533 * The alternative `Cargo.lock` filename must currently be a leafname. I
534 think fixing this just involves review to check other values work
537 * The alternative `Cargo.lock` file must be on the same filesystem
538 as the source tree. This is not so easy to fix; we would want the
539 existing algorithm but a fallback for the different-filsystem case.
541 * `Cargo.nail` is unconditionally looked for in the parent directory.
542 Ideally this should be configurable, and also perhaps be able to
543 combine multiple `Cargo.nail` files? Relatedly, although
544 nailing-cargo can read multiple config files, it can only handle
545 one file specifying directories and packages.
547 * nailing-cargo uses a single lockfile alongside your `Cargo.nail`,
548 rather than a more sophisticated scheme involving locking
549 particular directories. This means that if you run multiple
550 copies of nailing-cargo at once, in different directories, but
551 with `Cargo.nail` files which imply overlapping sets of package
552 directories, things will go Badly Wrong.
554 Contributing and legal
555 ======================
557 nailing-cargo is Free Software.
559 Please help improve it. Contributions (to address the limitations, or
560 to add new facilities to help work with cargo) are welcome by email to
561 `ijackson@chiark.greenend.org.uk` or via the [Salsa
562 project](https://salsa.debian.org/iwj/nailing-cargo).
564 If you plan to do substantial work, please do get in touch with a
565 sketch of your proposed changes.
570 This project accepts contributions based on the git commit
571 Signed-off-by convention, by which the contributors certify their
572 contributions according to the Developer Certificate of Origin version
573 1.1 - see the file DEVELOPER-CERTIFICATE.
575 Copyright (C) 2019-2020 Ian Jackson and others
577 This program is free software: you can redistribute it and/or modify
578 it under the terms of the GNU Affero General Public License as
579 published by the Free Software Foundation, either version 3 of the
580 License, or (at your option) any later version.
582 This program is distributed in the hope that it will be useful,
583 but WITHOUT ANY WARRANTY; without even the implied warranty of
584 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
585 GNU Affero General Public License for more details.
587 You should have received a copy of the GNU Affero General Public License
588 along with this program. If not, see <http://www.gnu.org/licenses/>.
590 Individual files generally contain the following tag in the copyright
591 notice, instead of the full licence grant text:
593 SPDX-License-Identifier: AGPL-3.0-or-later
595 As is conventional, this should be read as a licence grant.