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 * [Introduction](#nailing-cargo)
56 * [Installing](#installing)
57 * [Most basic example usage](#most-basic-example-usage)
58 * [Documentation table of contents](#documentation-table-of-contents)
59 * [Using local crates, or locally modified crates](#using-local-crates-or-locally-modified-crates)
60 * [How nailing-cargo helps with using local crates](#how-nailing-cargo-helps-with-using-local-crates)
61 * [Telling nailing-cargo how to massage `Cargo.toml`](#telling-nailing-cargo-how-to-massage-cargo.toml)
62 * [Out-of-tree builds](#out-of-tree-builds)
63 * [How nailing-cargo helps with out-of-tree builds](#how-nailing-cargo-helps-with-out-of-tree-builds)
64 * [Configuring out-of-tree builds](#configuring-out-of-tree-builds)
65 * [Target architecture convenience aliases](#target-architecture-convenience-aliases)
66 * [Default change to offline mode](#default-change-to-offline-mode)
67 * [Invocation and command-line option reference](#invocation-and-command-line-option-reference)
70 * [Environment of the build command](#environment-of-the-build-command)
71 * [Configuration reference](#configuration-reference)
72 * [Source directories and packages (toplevel)](#source-directories-and-packages-toplevel)
73 * [`[alt_cargolock]`: Alternative `Cargo.lock` filename](#alt_cargolock-alternative-cargo.lock-filename)
74 * [`[oot]`: Out-of-tree build support](#oot-out-of-tree-build-support)
75 * [`[arch]`: Architecture convenience aliases](#arch-architecture-convenience-aliases)
76 * [`[misc]`: Miscellaneous individual nailing-cargo config](#misc-miscellaneous-individual-nailing-cargo-config)
77 * [Limitations and bugs](#limitations-and-bugs)
78 * [Contributing and legal](#contributing-and-legal)
81 Using local crates, or locally modified crates
82 ==============================================
84 cargo does not work well with local crates,
85 especially completely unpublished ones.
86 (See [issue#6713](https://github.com/rust-lang/cargo/issues/6713),
87 [stackoverflow](https://stackoverflow.com/questions/33025887/how-to-use-a-local-unpublished-crate),
88 [issue#1481](https://github.com/rust-lang/cargo/issues/1481),
89 [my blog](https://diziet.dreamwidth.org/1805.html).)
91 Using a local version of a crate should be possible without putting
92 paths into your `Cargo.toml` and without editing complex
95 How nailing-cargo helps with using local crates
96 -----------------------------------------------
98 nailing-cargo temporarily edits all the `Cargo.toml` files in all the
99 subdirectories you mention, to refer to each other; then it runs
100 cargo; and then it puts everything back.
102 Telling nailing-cargo how to massage `Cargo.toml`
103 -------------------------------------------------
105 To find the subdirectories, and the packages, it looks for `subdirs`
106 and `packages` in `Cargo.nail`.
108 For straightforward use, write `subdirs` as a multi-line string
109 containing a list of subdirectory names one per line. In each of
110 these directories `Cargo.toml` will be massaged, and the package there
111 will be used for other massaged `Cargo.toml`s.
113 See "Configuration reference", below, for full details.
118 It is often desirable to run builds in a way that does not write to
119 the source tree. cargo's enthusiastic approach to the dependency
120 management task means that it is a good idea to try to insulate your
121 main working environment from the many things cargo has decided to
122 download and execute.
124 However, when you tell cargo to do an out of tree build (using
125 `--manifest-path`) it will insist on `Cargo.lock` being in the source
126 directory, and often will insist on writing to it.
128 How nailing-cargo helps with out-of-tree builds
129 -----------------------------------------------
131 nailing-cargo (configured appropriately) copies files back and forth
132 to between the source and build directories, and runs cargo as your
135 The `Cargo.lock` must still be saved in your source tree somewhere.
136 nailing-cargo arranges this for you. You can either put this file in
137 `.gitignore`; or commit it to git; or you can tell nailing-cargo to
138 save it as something like `Cargo.lock.example`.
140 Configuring out-of-tree builds
141 ------------------------------
143 To enable out-of-tree-builds, put an `[oot]` section in your
144 `Cargo.nail` or one of nailing-cargo's other config files.
145 In that section, specify at least `use`.
147 Also, specify `dir`, or create a symlink `Build` next to `Cargo.nail`,
148 pointing to to your build area.
156 will have nailing-cargo run `ssh rustcargo@localhost` to
159 Target architecture convenience aliases
160 =======================================
162 If you are cross-building you may need to tell cargo `--target=`.
163 The architecture names are quite long and inconvenient.
165 A simple shell alias would help a lot, except that cargo rejects
166 `--target=` when it thinks it's not needed.
168 In your nailing-cargo config, you can write something like
169 `arch.RPI='arm-unknown-linux-gnueabihf'`. Then `nailing-cargo -ARPI`
170 will DTRT. In fact, you do not even need to specify that particular
171 arch alias, since it is built-in to nailing-cargo.
173 Default change to offline mode
174 ==============================
176 It seems to me that build tools should be explicit about their use of
177 the network. So by default, nailing-cargo passes `--offline` to
180 If you disagree with my opinion, write `misc.online=true` in your
181 nailing-cargo configuration. `misc.online=false`, and command line
182 options, are also available, for overriding.
184 Invocation and command-line option reference
185 ============================================
191 1$ nailing-cargo <nailing-opts> <cargo-opts> [--] <subcmd>...
192 2$ nailing-cargo <nailing-opts> --- <cargo> <cargo-opts> [--] <subcmd>...
193 3$ nailing-cargo <nailing-opts> --- [--] <build-command>...
195 Ususally the `--` is not needed. (It should generally be passed by
196 programs which wrap nailing-cargo. See below.)
198 In usage 1, nailing-cargo runs `cargo` (from `PATH`). In the usage 2
199 nailing-cargo runs `<cargo>`. In both these cases it adds its own
200 options to control cargo's behaviour. In both of these cases
201 nailing-cargo looks at `<subcmd>` to determine the cargo subcommand
202 being run: this controls various defaults, to try to do the right
205 In the third syntax, nailing-cargo runs `<build-command>...` without
206 additional arguments and does not attempt to identify the cargo
207 subcommand(s) that it will run. Possibly it will be necessary to pass
208 `--online` or `--cargo-lock-update`, or even `--cargo-*arg*`
210 ### Invocation argument disambiguation rules ###
212 For authors of tools which call nailing-cargo (and pedants):
214 The usages overlap in syntax! nailing-cargo follows the following
215 rules when interpreting its command line:
217 * The first option not recognised as a nailing-cargo option is
218 treated as the start of the `<cargo-opts>`.
220 * `<cargo-opts>` are terminated by `--` (which is removed) or the
221 first argument which does not start with a `-`.
223 (It is not possible to get nailing-cargo to pass the value `--`
224 as a separate argument to a cargo global option, but cargo global
225 options can typically take the values cuddled with `=`, so doing
226 that is not necessary.)
228 * After `---`, nailing-cargo will search for a `--`, to the end of
229 the arguments if necessary. The position of the `--` determines
230 whether this is usage 2 or usage 3, and what `<subcmd>` is.
232 If the arguments after `nailing-cargo ... ---` might contain `--`
233 anywhere, an explicit `--` should be passed.
235 * If no `--` appears after `---`, the word after `---` is the
236 command to run; if its final pathname component contains the
237 string `cargo`, it is treated as `<cargo>` (implying usage 2 and
238 the search for `<subcmd>`). Otherwise it is treated as
239 `<build-command>` (usage 3).
244 * `-v`: Increase verbosity. Default is 1.
246 * `-q`: Set verbosity to 0.
248 * `-D`: Increase amount of debugging dump.
250 * `-n`: "No action": stop after writing `Cargo.toml.nailing~`
251 everywhere, and do not run any build command.
253 * `-A<arch>` | `--arch=<arch>` | `--target=<arch>`
255 Specify target architecture.
257 This option translates to a `--target=<arch>` option to the
258 ultimate command, unless that is a cargo subcommand which we
259 know would reject it. `--arch` and `--target` are simply
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'`.
267 * `-u` | `--cargo-lock-update` | `-U` | `--no-cargo-lock-update`
269 Enables, or disables, the dance to allow `Cargo.lock` (or
270 alternative) to be updated in the source directory.
272 With this dance enabled the `Cargo.lock` and `Cargo.toml` are
273 copied to the build directory along with a skeleton just big
274 enough to fool cargo. After cargo has run, the resulting
275 `Cargo.lock` is copied back to the source tree.
277 This makes no sense with in-tree builds.
279 Default is no update unless the ultimate command is a
280 cargo subcommand which we know needs it.
282 * `-m` | `--cargo-manifest-args` | `-M` | `--no-cargo-manifest-args`
284 Controls whether we add cargo command line options, relating to
285 finding `Cargo.toml`, to the command to run.
287 Default is to add them if we are doing an out-of-tree build,
288 unless we are doing the dance to update the `Cargo.lock` (see
289 above) since in that case all the relevant files can be found
290 by cargo in the build directory.
292 The arguments added are
294 --manifest-path=<path/to/Cargo.toml>
298 * `-T` | `--no-cargo-target-dir-arg` | `-t` | `--cargo-target-dir-arg`
300 `-T` suppresses `--target-dir`; `-t` un-suppresses it. Only
301 makes any difference with `-m`, since otherwise no
302 `--target-dir` would be passed anyway. Additionally this is
303 done automatically when nailing-cargo sees that the cargo
304 subcommand is one which needs it, eg `fetch`.
306 * `-o` | `--online` | `-O` | `--offline`
308 Whether to allow cargo to make network access. nailing-cargo
309 always passes `--offline` to cargo, unless `--online` is in
310 force. The default value depends on the configuration and the
311 cargo subcommand - see `[misc]` `online` in "Configuration".
313 Environment of the build command
314 --------------------------------
316 nailing-cargo passes these environment variables to the build command:
318 * `NAILINGCARGO_WORKSPHERE`: invocation `..` (parent)
319 * `NAILINGCARGO_MANIFEST_DIR`: invocation `.` (invocation directory)
320 * `NAILINGCARGO_BUILD_DIR`: build directory (even if same as source)
321 * `NAILINGCARGO_BUILDSPHERE`: only set if out of tree: parent of build dir.
323 All of these are absolute paths.
325 Configuration reference
326 =======================
328 nailing-cargo reads these configuration files:
330 /etc/nailing-cargo/cfg.toml
331 ~/.nailing-cargo.toml
332 ./.nailing-cargo.toml
333 ../Nailing-Cargo.toml
336 Settings in later-mentioned files override ones in earlier-mentioned
339 Source directories and packages (toplevel)
340 ------------------------------------------
342 Note that unlike everything else, these keys (`packages` and
343 `subdirs`) are read only from `Cargo.nail` (see "Limitations and
346 These keys specify a combination of (i) a mapping from package name to
347 source subdirectory (ii) a set of subdirectories whose `Cargo.toml`
350 * `packages`: a map keyed by package name, giving the subdirectory
353 This causes each mentioned subdirectory's `Cargo.toml` to be
354 massaged, and records that subdirectory as the source for that
355 package. (nailing-cargo will check that subdirectory actually
356 contains the indicated package.)
358 Each value can be just the subdirectory name (eg `[packages]`
359 `mylibrary='mylibrary-test'`) or itself a map with the key `subdir`
360 (eg `[packages.mylibrary]` `subdir='mylibrary-test'`).
362 * `subdirs`: a list of subdirectory names to process.
364 Each subdirectory's `Cargo.toml` will be massaged. Also, the
365 subdirectory will be examined to see what package it contains; it
366 will then be used as the source for that package, unless that
367 package appears in an entry in `packages`, or an earlier entry in
370 This can be a list of strings (eg `subdirs =
371 ['myproject','mylibrary']`). Or it can be single multi-line
372 string containing one subdirectory name per line; in that
373 case, `#`-comments are supported and tabs and spaces are ignored
374 (see "Most basic example usage" above.)
376 In each case the subdirectory should usually be a relative pathname;
377 it is relative to the directory containing `Cargo.nail`.
379 `[alt_cargolock]`: Alternative `Cargo.lock` filename
380 ----------------------------------------------------
382 To control use of alternative `Cargo.lock` filename, use the section
383 `[alt_cargolock]`. Settings here:
385 * `file = <some leafname>`.
387 * `file = true`: Equivalent to `file = "Cargo.lock.example"`.
388 (This is the default.)
390 * `file = false`: Disables this feature.
392 * `force = false`: Uses the alternative filename only if it
393 already exists. (This is the default.)
395 * `force = true`: Always uses the alternative filename.
397 `[oot]`: Out-of-tree build support
398 ----------------------------------
400 * `dir`: The build directory. If relative, it is relative to the
401 parent of the invocation directory (and could be a symlink then).
402 Default is `Build` (assuming `use` is specified).
404 The build directory will contain one subdir for each package: each
405 subdir in the build dir corresponds to one source dir where
406 nailing-cargo was invoked. nailing-cargo will arrange to create
407 these subdirectories, so the build directory can start out empty.
409 * `use`: How to become the build user. Needs to be combined
410 with other setting(s):
412 * `ssh`: Use ssh. `user` must be given as well and can be
413 a username on localhost, or the `<user>@<host>`
416 * `command_args`: `command` must be specified as a list,
417 specifying a command and arguments which work like `nice`.
419 * `command_sh`: `command` must be specified as a list,
420 specifying a command and arguments which work like `sh -c`.
422 * `null`: Run builds as the same user.
424 * `really`: Use `really` from `chiark-really.deb`.
425 `user` must be given as well.
427 * `command`: The command to run for `command_sh` or `command_args`.
429 * `user`: The local username for `really` and `ssh`, or
430 `<user>@<host>` for `ssh`.
432 `[arch]`: Architecture convenience aliases
433 ------------------------------------------
435 This is a map from archictecture aliases to full cargo architecture
436 names. The keys are the aliases; each entry should be a string, the
437 cargo architecture name.
439 Only keys starting with an ascii uppercase letter are relevant, since
440 other names are not looked up in this alias map.
442 `[misc]`: Miscellaneous individual nailing-cargo config
443 -------------------------------------------------------
445 * `online`: boolean, specifying whether to pass `--offline` to cargo
446 (cargo's default is online mode). The default is offline, unless
447 nailing-cargo can see that the cargo subcommand being invoked is
448 one which requires online access (currently, `fetch`), in which
449 case the default is online.
454 * nailing-cargo temporarily dirties your source trees, including
455 particularly `Cargo.toml` and `Cargo.lock`; and if nailing-cargo
456 crashes or is interrupted these changes may be left behind.
457 Unfortunately it is not possible to avoid this temporary dirtying
458 because the cargo team have deliberately made cargo inflexible -
459 [issue#6715](https://github.com/rust-lang/cargo/issues/6715).
460 At least, running nailing-cargo again will clean up any mess
461 left by an interrupted run.
463 * Out of tree builds require a unified filesystem view: eg, different
464 users on the same host, NFS, or something.
466 Specifically, the invocation and build execution environments must
467 both have visibility of the source and build directories, at the
468 same absolute pathnames. The invocation environment must be able
469 to write to the build environment (but vice versa is not
472 This could be improved.
474 * The alternative `Cargo.lock` filename must currently be a leafname. I
475 think fixing this just involves review to check other values work
478 * The alternative `Cargo.lock` file must be on the same filesystem
479 as the source tree. This is not so easy to fix; we would want the
480 existing algorithm but a fallback for the different-filsystem case.
482 * `Cargo.nail` is unconditionally looked for in the parent directory.
483 Ideally this should be configurable, and also perhaps be able to
484 combine multiple `Cargo.nail` files? Relatedly, although
485 nailing-cargo can read multiple config files, it can only handle
486 one file specifying directories and packages.
488 * nailing-cargo uses a single lockfile alongside your `Cargo.nail`,
489 rather than a more sophisticated scheme involving locking
490 particular directories. This means that if you run multiple
491 copies of nailing-cargo at once, in different directories, but
492 with `Cargo.nail` files which imply overlapping sets of package
493 directories, things will go Badly Wrong.
495 Contributing and legal
496 ======================
498 nailing-cargo is Free Software.
500 Please help improve it. Contributions (to address the limitations, or
501 to add new facilities to help work with cargo) are welcome by email to
502 `ijackson@chiark.greenend.org.uk` or via the [Salsa
503 project](https://salsa.debian.org/iwj/nailing-cargo).
505 If you plan to do substantial work, please do get in touch with a
506 sketch of your proposed changes.
511 This project accepts contributions based on the git commit
512 Signed-off-by convention, by which the contributors certify their
513 contributions according to the Developer Certificate of Origin version
514 1.1 - see the file DEVELOPER-CERTIFICATE.
516 Copyright (C) 2019-2020 Ian Jackson and others
518 This program is free software: you can redistribute it and/or modify
519 it under the terms of the GNU Affero General Public License as
520 published by the Free Software Foundation, either version 3 of the
521 License, or (at your option) any later version.
523 This program is distributed in the hope that it will be useful,
524 but WITHOUT ANY WARRANTY; without even the implied warranty of
525 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
526 GNU Affero General Public License for more details.
528 You should have received a copy of the GNU Affero General Public License
529 along with this program. If not, see <http://www.gnu.org/licenses/>.
531 Individual files generally contain the following tag in the copyright
532 notice, instead of the full licence grant text:
534 SPDX-License-Identifier: AGPL-3.0-or-later
536 As is conventional, this should be read as a licence grant.