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.
36 nailing-cargo is designed to be run out of a git clone:
39 $ git clone https://salsa.debian.org/iwj/nailing-cargo.git
40 $ ln -s `pwd`/nailing-cargo/nailing-cargo ~/bin
43 It is self-contained, depending only on a reasonably functional Perl
46 Most basic example usage
47 ------------------------
56 $ nailing-cargo generate-lockfile
60 Using local crates, or locally modified crates
61 ==============================================
63 cargo does not work well with local crates,
64 especially completely unpublished ones.
65 (See [issue#6713](https://github.com/rust-lang/cargo/issues/6713),
66 [stackoverflow](https://stackoverflow.com/questions/33025887/how-to-use-a-local-unpublished-crate),
67 [issue#1481](https://github.com/rust-lang/cargo/issues/1481),
68 [my blog](https://diziet.dreamwidth.org/1805.html).)
70 Using a local version of a crate should be possible without putting
71 paths into your `Cargo.toml` and without editing complex
74 How nailing-cargo helps with using local crates
75 -----------------------------------------------
77 nailing-cargo temporarily edits all the `Cargo.toml` files in all the
78 subdirectories you mention, to refer to each other; then it runs
79 cargo; and then it puts everything back.
81 Telling nailing-cargo how to massage `Cargo.toml`
82 -------------------------------------------------
84 To find the subdirectories, and the packages, it looks for `subdirs`
85 and `packages` in `Cargo.nail`.
87 For straightforward use, write `subdirs` as a multi-line string
88 containing a list of subdirectory names one per line. In each of
89 these directories `Cargo.toml` will be massaged, and the package there
90 will be used for other massaged `Cargo.toml`s.
92 See "Configuration reference", below, for full details.
97 It is often desirable to run builds in a way that does not write to
98 the source tree. cargo's enthusiastic approach to the dependency
99 management task means that it is a good idea to try to insulate your
100 main working environment from the many things cargo has decided to
101 download and execute.
103 However, when you tell cargo to do an out of tree build (using
104 `--manifest-path`) it will insist on `Cargo.lock` being in the source
105 directory, and often will insist on writing to it.
107 How nailing-cargo helps with out-of-tree builds
108 -----------------------------------------------
110 nailing-cargo (configured appropriately) copies files back and forth
111 to between the source and build directories, and runs cargo as your
114 The `Cargo.lock` must still be saved in your source tree somewhere.
115 nailing-cargo arranges this for you. You can either put this file in
116 `.gitignore`; or commit it to git; or you can tell nailing-cargo to
117 save it as something like `Cargo.lock.example`.
119 Configuring out-of-tree builds
120 ------------------------------
122 To enable out-of-tree-builds, put an `[oot]` section in your
123 `Cargo.nail` or one of nailing-cargo's other config files.
124 In that section, specify at least `use`.
126 Also, specify `dir`, or create a symlink `Build` next to `Cargo.nail`,
127 pointing to to your build area.
135 will have nailing-cargo run `ssh rustcargo@localhost` to
138 Target architecture convenience aliases
139 =======================================
141 If you are cross-building you may need to tell cargo `--target=`.
142 The architecture names are quite long and inconvenient.
144 A simple shell alias would help a lot, except that cargo rejects
145 `--target=` when it thinks it's not needed.
147 In your nailing-cargo config, you can write something like
148 `arch.RPI='arm-unknown-linux-gnueabihf'`. Then `nailing-cargo -ARPI`
149 will DTRT. In fact, you do not even need to specify that particular
150 arch alias, since it is built-in to nailing-cargo.
152 Default change to offline mode
153 ==============================
155 It seems to me that build tools should be explicit about their use of
156 the network. So by default, nailing-cargo passes `--offline` to
159 If you disagree with my opinion, write `misc.online=true` in your
160 nailing-cargo configuration. `misc.online=false`, and command line
161 options, are also available, for overriding.
163 Invocation and command-line option reference
164 ============================================
170 1$ nailing-cargo <nailing-opts> <cargo-opts> [--] <subcmd>...
171 2$ nailing-cargo <nailing-opts> --- <cargo> <cargo-opts> [--] <subcmd>...
172 3$ nailing-cargo <nailing-opts> --- [--] <build-command>...
174 Ususally the `--` is not needed. (It should generally be passed by
175 programs which wrap nailing-cargo. See below.)
177 In usage 1, nailing-cargo runs `cargo` (from `PATH`). In the usage 2
178 nailing-cargo runs `<cargo>`. In both these cases it adds its own
179 options to control cargo's behaviour. In both of these cases
180 nailing-cargo looks at `<subcmd>` to determine the cargo subcommand
181 being run: this controls various defaults, to try to do the right
184 In the third syntax, nailing-cargo runs `<build-command>...` without
185 additional arguments and does not attempt to identify the cargo
186 subcommand(s) that it will run. Possibly it will be necessary to pass
187 `--online` or `--cargo-lock-update`, or even `--cargo-*arg*`
189 ### Invocation argument disambiguation rules ###
191 For authors of tools which call nailing-cargo (and pedants):
193 The usages overlap in syntax! nailing-cargo follows the following
194 rules when interpreting its command line:
196 * The first option not recognised as a nailing-cargo option is
197 treated as the start of the `<cargo-opts>`.
199 * `<cargo-opts>` are terminated by `--` (which is removed) or the
200 first argument which does not start with a `-`.
202 (It is not possible to get nailing-cargo to pass the value `--`
203 as a separate argument to a cargo global option, but cargo global
204 options can typically take the values cuddled with `=`, so doing
205 that is not necessary.)
207 * After `---`, nailing-cargo will search for a `--`, to the end of
208 the arguments if necessary. The position of the `--` determines
209 whether this is usage 2 or usage 3, and what `<subcmd>` is.
211 If the arguments after `nailing-cargo ... ---` might contain `--`
212 anywhere, an explicit `--` should be passed.
214 * If no `--` appears after `---`, the word after `---` is the
215 command to run; if its final pathname component contains the
216 string `cargo`, it is treated as `<cargo>` (implying usage 2 and
217 the search for `<subcmd>`). Otherwise it is treated as
218 `<build-command>` (usage 3).
223 * `-v`: Increase verbosity. Default is 1.
225 * `-q`: Set verbosity to 0.
227 * `-D`: Increase amount of debugging dump.
229 * `-n`: "No action": stop after writing `Cargo.toml.nailing~`
230 everywhere, and do not run any build command.
232 * `-A<arch>` | `--arch=<arch>` | `--target=<arch>`
234 Specify target architecture.
236 This option translates to a `--target=<arch>` option to the
237 ultimate command, unless that is a cargo subcommand which we
238 know would reject it. `--arch` and `--target` are simply
241 If `<arch>` starts with a capital ascii letter, it is an alias
242 for some other arch: it is looked up in the configuration, and
243 then in the builtin arch alias list. The builtin list is
244 equivalent to: `[arch]` `RPI='arm-unknown-linux-gnueabihf'`.
246 * `-u` | `--cargo-lock-update` | `-U` | `--no-cargo-lock-update`
248 Enables, or disables, the dance to allow `Cargo.lock` (or
249 alternative) to be updated in the source directory.
251 With this dance enabled the `Cargo.lock` and `Cargo.toml` are
252 copied to the build directory along with a skeleton just big
253 enough to fool cargo. After cargo has run, the resulting
254 `Cargo.lock` is copied back to the source tree.
256 This makes no sense with in-tree builds.
258 Default is no update unless the ultimate command is a
259 cargo subcommand which we know needs it.
261 * `-m` | `--cargo-manifest-args` | `-M` | `--no-cargo-manifest-args`
263 Controls whether we add cargo command line options, relating to
264 finding `Cargo.toml`, to the command to run.
266 Default is to add them if we are doing an out-of-tree build,
267 unless we are doing the dance to update the `Cargo.lock` (see
268 above) since in that case all the relevant files can be found
269 by cargo in the build directory.
271 The arguments added are
273 --manifest-path=<path/to/Cargo.toml>
277 * `-T` | `--no-cargo-target-dir-arg` | `-t` | `--cargo-target-dir-arg`
279 `-T` suppresses `--target-dir`; `-t` un-suppresses it. Only
280 makes any difference with `-m`, since otherwise no
281 `--target-dir` would be passed anyway. Additionally this is
282 done automatically when nailing-cargo sees that the cargo
283 subcommand is one which needs it, eg `fetch`.
285 * `-o` | `--online` | `-O` | `--offline`
287 Whether to allow cargo to make network access. nailing-cargo
288 always passes `--offline` to cargo, unless `--online` is in
289 force. The default value depends on the configuration and the
290 cargo subcommand - see `[misc]` `online` in "Configuration".
292 Environment of the build command
293 --------------------------------
295 nailing-cargo passes these environment variables to the build command:
297 * `NAILINGCARGO_WORKSPHERE`: invocation `..` (parent)
298 * `NAILINGCARGO_MANIFEST_DIR`: invocation `.` (invocation directory)
299 * `NAILINGCARGO_BUILD_DIR`: build directory (even if same as source)
300 * `NAILINGCARGO_BUILDSPHERE`: only set if out of tree: parent of build dir.
302 All of these are absolute paths.
304 Configuration reference
305 =======================
307 nailing-cargo reads these configuration files:
309 /etc/nailing-cargo/cfg.toml
310 ~/.nailing-cargo.toml
311 ./.nailing-cargo.toml
312 ../Nailing-Cargo.toml
315 Settings in later-mentioned files override ones in earlier-mentioned
318 Source directories and packages (toplevel)
319 ------------------------------------------
321 Note that unlike everything else, these keys (`packages` and
322 `subdirs`) are read only from `Cargo.nail` (see "Limitations and
325 These keys specify a combination of (i) a mapping from package name to
326 source subdirectory (ii) a set of subdirectories whose `Cargo.toml`
329 * `packages`: a map keyed by package name, giving the subdirectory
332 This causes each mentioned subdirectory's `Cargo.toml` to be
333 massaged, and records that subdirectory as the source for that
334 package. (nailing-cargo will check that subdirectory actually
335 contains the indicated package.)
337 Each value can be just the subdirectory name (eg `[packages]`
338 `mylibrary='mylibrary-test'`) or itself a map with the key `subdir`
339 (eg `[packages.mylibrary]` `subdir='mylibrary-test'`).
341 * `subdirs`: a list of subdirectory names to process.
343 Each subdirectory's `Cargo.toml` will be massaged. Also, the
344 subdirectory will be examined to see what package it contains; it
345 will then be used as the source for that package, unless that
346 package appears in an entry in `packages`, or an earlier entry in
349 This can be a list of strings (eg `subdirs =
350 ['myproject','mylibrary']`). Or it can be single multi-line
351 string containing one subdirectory name per line; in that
352 case, `#`-comments are supported and tabs and spaces are ignored
353 (see "Most basic example usage" above.)
355 In each case the subdirectory should usually be a relative pathname;
356 it is relative to the directory containing `Cargo.nail`.
358 `[alt_cargolock]`: Alternative `Cargo.lock` filename
359 ----------------------------------------------------
361 To control use of alternative `Cargo.lock` filename, use the section
362 `[alt_cargolock]`. Settings here:
364 * `file = <some leafname>`.
366 * `file = true`: Equivalent to `file = "Cargo.lock.example"`.
367 (This is the default.)
369 * `file = false`: Disables this feature.
371 * `force = false`: Uses the alternative filename only if it
372 already exists. (This is the default.)
374 * `force = true`: Always uses the alternative filename.
376 `[oot]`: Out-of-tree build support
377 ----------------------------------
379 * `dir`: The build directory. If relative, it is relative to the
380 parent of the invocation directory (and could be a symlink then).
381 Default is `Build` (assuming `use` is specified).
383 The build directory will contain one subdir for each package: each
384 subdir in the build dir corresponds to one source dir where
385 nailing-cargo was invoked. nailing-cargo will arrange to create
386 these subdirectories, so the build directory can start out empty.
388 * `use`: How to become the build user. Needs to be combined
389 with other setting(s):
391 * `ssh`: Use ssh. `user` must be given as well and can be
392 a username on localhost, or the `<user>@<host>`
395 * `command_args`: `command` must be specified as a list,
396 specifying a command and arguments which work like `nice`.
398 * `command_sh`: `command` must be specified as a list,
399 specifying a command and arguments which work like `sh -c`.
401 * `null`: Run builds as the same user.
403 * `really`: Use `really` from `chiark-really.deb`.
404 `user` must be given as well.
406 * `command`: The command to run for `command_sh` or `command_args`.
408 * `user`: The local username for `really` and `ssh`, or
409 `<user>@<host>` for `ssh`.
411 `[arch]`: Architecture convenience aliases
412 ------------------------------------------
414 This is a map from archictecture aliases to full cargo architecture
415 names. The keys are the aliases; each entry should be a string, the
416 cargo architecture name.
418 Only keys starting with an ascii uppercase letter are relevant, since
419 other names are not looked up in this alias map.
421 `[misc]`: Miscellaneous individual nailing-cargo config
422 -------------------------------------------------------
424 * `online`: boolean, specifying whether to pass `--offline` to cargo
425 (cargo's default is online mode). The default is offline, unless
426 nailing-cargo can see that the cargo subcommand being invoked is
427 one which requires online access (currently, `fetch`), in which
428 case the default is online.
433 * nailing-cargo temporarily dirties your source trees, including
434 particularly `Cargo.toml` and `Cargo.lock`; and if nailing-cargo
435 crashes or is interrupted these changes may be left behind.
436 Unfortunately it is not possible to avoid this temporary dirtying
437 because the cargo team have deliberately made cargo inflexible -
438 [issue#6715](https://github.com/rust-lang/cargo/issues/6715).
439 At least, running nailing-cargo again will clean up any mess
440 left by an interrupted run.
442 * Out of tree builds require a unified filesystem view: eg, different
443 users on the same host, NFS, or something.
445 Specifically, the invocation and build execution environments must
446 both have visibility of the source and build directories, at the
447 same absolute pathnames. The invocation environment must be able
448 to write to the build environment (but vice versa is not
451 This could be improved.
453 * The alternative `Cargo.lock` filename must currently be a leafname. I
454 think fixing this just involves review to check other values work
457 * The alternative `Cargo.lock` file must be on the same filesystem
458 as the source tree. This is not so easy to fix; we would want the
459 existing algorithm but a fallback for the different-filsystem case.
461 * `Cargo.nail` is unconditionally looked for in the parent directory.
462 Ideally this should be configurable, and also perhaps be able to
463 combine multiple `Cargo.nail` files? Relatedly, although
464 nailing-cargo can read multiple config files, it can only handle
465 one file specifying directories and packages.
467 * nailing-cargo uses a single lockfile alongside your `Cargo.nail`,
468 rather than a more sophisticated scheme involving locking
469 particular directories. This means that if you run multiple
470 copies of nailing-cargo at once, in different directories, but
471 with `Cargo.nail` files which imply overlapping sets of package
472 directories, things will go Badly Wrong.
474 Contributing and legal
475 ======================
477 nailing-cargo is Free Software.
479 Please help improve it. Contributions (to address the limitations, or
480 to add new facilities to help work with cargo) are welcome by email to
481 `ijackson@chiark.greenend.org.uk` or via the [Salsa
482 project](https://salsa.debian.org/iwj/nailing-cargo).
484 If you plan to do substantial work, please do get in touch with a
485 sketch of your proposed changes.
490 This project accepts contributions based on the git commit
491 Signed-off-by convention, by which the contributors certify their
492 contributions according to the Developer Certificate of Origin version
493 1.1 - see the file DEVELOPER-CERTIFICATE.
495 Copyright (C) 2019-2020 Ian Jackson and others
497 This program is free software: you can redistribute it and/or modify
498 it under the terms of the GNU Affero General Public License as
499 published by the Free Software Foundation, either version 3 of the
500 License, or (at your option) any later version.
502 This program is distributed in the hope that it will be useful,
503 but WITHOUT ANY WARRANTY; without even the implied warranty of
504 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
505 GNU Affero General Public License for more details.
507 You should have received a copy of the GNU Affero General Public License
508 along with this program. If not, see <http://www.gnu.org/licenses/>.
510 Individual files generally contain the following tag in the copyright
511 notice, instead of the full licence grant text:
513 SPDX-License-Identifier: AGPL-3.0-or-later
515 As is conventional, this should be read as a licence grant.