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 cargo generate-lockfile
49 $ nailing-cargo cargo build
52 Using local crates, or locally modified crates
53 ==============================================
55 cargo does not work well with local crates,
56 especially completely unpublished ones.
57 (See [issue#6713](https://github.com/rust-lang/cargo/issues/6713),
58 [stackoverflow](https://stackoverflow.com/questions/33025887/how-to-use-a-local-unpublished-crate),
59 [issue#1481](https://github.com/rust-lang/cargo/issues/1481),
60 [my blog](https://diziet.dreamwidth.org/1805.html).)
62 Using a local version of a crate should be possible without putting
63 paths into your `Cargo.toml` and without editing complex
66 How nailing-cargo helps with using local crates
67 -----------------------------------------------
69 nailing-cargo temporarily edits all the `Cargo.toml` files in all the
70 subdirectories you mention, to refer to each other; then it runs
71 cargo; and then it puts everything back.
73 Telling nailing-cargo how to massage `Cargo.toml`
74 -------------------------------------------------
76 To find the subdirectories, and the packages, it looks for `subdirs`
77 and `packages` in `Cargo.nail`.
79 `subdirs` can be a (usually multi-line) string containing a list of
80 subdirectory names one per line. (`#`-comments are supported.) Or it
81 can be a list of strings (`subdirs = ['myproject','mylibrary']`). In
82 each of these directories `Cargo.toml` will be massaged, and
83 the package there will be used for other massaged `Cargo.toml`s
85 For more complex cases: `packages` is a mapping from package names to
86 strings or dictionaries (e.g. in `Cargo.nail`, write something like:
87 `[packages.mylibrary]` `subdir='mylibrary-test'` or `[packages]`
88 `mylibrary='mylibrary-test'`). These override the locations for the
89 specified packages (so you can, for example, have multiple trees with
90 the same package in). These subdirectories are also added to the list
91 of places where `Cargo.toml` should be massaged.
96 It is often desirable to run builds in a way that does not write to
97 the source tree. cargo's enthusiastic approach to the dependency
98 management task means that it is a good idea to try to insulate your
99 main working environment from the many things cargo has decided to
100 download and execute.
102 However, when you tell cargo to do an out of tree build (using
103 `--manifest-path`) it will insist on `Cargo.lock` being in the source
104 directory, and often will insist on writing to it.
106 How nailing-cargo helps with out-of-tree builds
107 -----------------------------------------------
109 nailing-cargo (configured appropriately) copies files back and forth
110 to between the source and build directories, and runs cargo as your
113 The `Cargo.lock` must still be saved in your source tree somewhere.
114 nailing-cargo arranges this for you. You can either put this file in
115 `.gitignore`; or commit it to git; or you can tell nailing-cargo to
116 save it as something like `Cargo.lock.example`.
118 Configuring out-of-tree builds
119 ------------------------------
121 To enable out-of-tree-builds, put an `[oot]` section in your
122 `Cargo.nail` or one of nailing-cargo's other config files.
123 In that section, specify at least `use`.
125 The primary config keys here are:
127 * `dir`: The build directory. If relative, it is relative to the
128 parent of the invocation directory (and could be a symlink then).
129 Default is `Build` (assuming `use` is specified).
131 * `use`: How to become the build user. Needs to be combined
132 with other setting(s):
134 * `ssh`: Use ssh. `user` must be given as well and can be
135 a username on localhost, or the `<user>@<host>`
138 * `command_args`: `command` must be specified as a list,
139 specifying a command and arguments which work like `nice`.
141 * `command_sh`: `command` must be specified as a list,
142 specifying a command and arguments which work like `sh -c`.
144 * `null`: Run builds as the same user.
146 * `really`: Use `really` from `chiark-really.deb`.
147 `user` must be given as well.
149 Target architecture convenience aliases
150 =======================================
152 If you are cross-building you may need to tell cargo `--target=`.
153 The architecture names are quite long and inconvenient.
155 A simple shell alias would help a lot, except that cargo rejects
156 `--target=` when it thinks it's not needed.
158 In your nailing-cargo config, you can write something like
159 `arch.RPI='arm-unknown-linux-gnueabihf'`. Then `nailing-cargo -ARPI`
160 will DTRT. In fact, you do not even need to specify that particular
161 arch alias, since it is built-in to nailing-cargo.
163 Default change to offline mode
164 ==============================
166 It seems to me that build tools should be explicit about their use of
167 the network. So by default, nailing-cargo passes `--offline` to
170 If you disagree with my opinion, write `misc.online=true` in your
171 nailing-cargo configuration. `misc.online=false`, and command line
172 options, are also available, for overriding.
177 * `-v`: Increase verbosity. Default is 1.
179 * `-q`: Set verbosity to 0.
181 * `-D`: Increase amount of debugging dump.
183 * `-n`: "No action": stop after writing `Cargo.toml.nailing~`
184 everywhere, and do not run any build command.
186 * `-A<arch>` | `--arch=<arch>` | `--target=<arch>`
188 Specify target architecture.
190 This option translates to a `--target=<arch>` option to the
191 ultimate command, unless that is a cargo subcommand which we
192 know would reject it. `--arch` and `--target` are simply
195 If `<arch>` starts with a capital ascii letter, it is an alias
196 for some other arch: it is looked up in the configuration, and
197 then in the builtin arch alias list. The builtin list is
198 equivalent to: `[arch]` `RPI='arm-unknown-linux-gnueabihf'`.
200 * `-u` | `--cargo-lock-update` | `-U` | `--no-cargo-lock-update`
202 Enables, or disables, the dance to allow `Cargo.lock` (or
203 alternative) to be updated in the source directory.
205 With this dance enabled the `Cargo.lock` and `Cargo.toml` are
206 copied to the build directory along with a skeleton just big
207 enough to fool cargo. After cargo has run, the resulting
208 `Cargo.lock` is copied back to the source tree.
210 This makes no sense with in-tree builds.
212 Default is no update unless the ultimate command is a
213 cargo subcommand which we know needs it.
215 * `-m` | `--cargo-manifest-args` | `-M` | `--no-cargo-manifest-args`
217 Controls whether we add cargo command line options, relating to
218 finding `Cargo.toml`, to the command to run.
220 Default is to add them if we are doing an out-of-tree build,
221 unless we are doing the dance to update the `Cargo.lock` (see
222 above) since in that case all the relevant files can be found
223 by cargo in the build directory.
225 The arguments added are
227 --manifest-path=<path/to/Cargo.toml>
231 * `-T` | `--no-cargo-target-dir-arg` | `-t` | `--cargo-target-dir-arg`
233 `-T` suppresses `--target-dir`; `-t` un-suppresses it. Only
234 makes any difference with `-m`, since otherwise no
235 `--target-dir` would be passed anyway. Additionally this is
236 done automatically when nailing-cargo sees that the cargo
237 subcommand is one which needs it, eg `fetch`.
239 * `-o` | `--online` | `-O` | `--offline`
241 Whether to allow cargo to make network access. nailing-cargo
242 always passes `--offline` to cargo, unless `--online` is in
243 force. The default is offline, unless the cargo subcommand is
244 one which implies online (currently, `fetch`).
249 nailing-cargo reads these configuration files:
251 /etc/nailing-cargo/cfg.toml
252 ~/.nailing-cargo.toml
253 ./.nailing-cargo.toml
254 ../Nailing-Cargo.toml
257 Settings in later-mentioned files override ones in earlier-mentioned
260 Note that unlike everything else, `packages` and `subdirs` are read
261 only from `Cargo.nail` (see "Limitations and bugs", below).
263 `[alt_cargolock]`: Alternative `Cargo.lock` filename
264 ----------------------------------------------------
266 To control use of alternative `Cargo.lock` filename, use the section
267 `[alt_cargolock]`. Settings here:
269 * `file = <some leafname>`.
271 * `file = true`: Equivalent to `file = "Cargo.lock.example"`.
272 (This is the default.)
274 * `file = false`: Disables this feature.
276 * `force = false`: Uses the alternative filename only if it
277 already exists. (This is the default.)
279 * `force = true`: Always uses the alternative filename.
284 Normally you pass cargo as an argument to nailing-cargo. But you
285 can also pass make or any other command. You may need to pass
286 `--no-cargo-manifest-args` (aka `-M`) to nailing-cargo, to avoid
287 passing options like `--manifest-path` to make or whatever.
289 nailing-cargo passes these environment variables to the build command:
291 * `NAILINGCARGO_WORKSPHERE`: invocation `..` (parent)
292 * `NAILINGCARGO_MANIFEST_DIR`: invocation `.` (invocation directory)
293 * `NAILINGCARGO_BUILD_DIR`: build directory (even if same as source)
294 * `NAILINGCARGO_BUILDSPHERE`: only set if out of tree: parent of build dir.
296 All of these are absolute paths.
301 * nailing-cargo temporarily dirties your source trees, including
302 particularly `Cargo.toml` and `Cargo.lock`; and if nailing-cargo
303 crashes or is interrupted these changes may be left behind.
304 Unfortunately it is not possible to avoid this temporary dirtying
305 because the cargo team have deliberately made cargo inflexible -
306 [issue#6715](https://github.com/rust-lang/cargo/issues/6715).
307 At least, running nailing-cargo again will clean up any mess
308 left by an interrupted run.
310 * Out of tree builds require a unified filesystem view: eg, different
311 users on the same host, NFS, or something.
313 Specifically, the invocation and build execution environments must
314 both have visibility of the source and build directories, at the
315 same absolute pathnames. The invocation environment must be able
316 to write to the build environment (but vice versa is not
319 This could be improved.
321 * The alternative `Cargo.lock` filename must currently be a leafname. I
322 think fixing this just involves review to check other values work
325 * The alternative `Cargo.lock` file must be on the same filesystem
326 as the source tree. This is not so easy to fix; we would want the
327 existing algorithm but a fallback for the different-filsystem case.
329 * `Cargo.nail` is unconditionally looked for in the parent directory.
330 Ideally this should be configurable, and also perhaps be able to
331 combine multiple `Cargo.nail` files? Relatedly, although
332 nailing-cargo can read multiple config files, it can only handle
333 one file specifying directories and packages.
335 * nailing-cargo uses a single lockfile alongside your `Cargo.nail`,
336 rather than a more sophisticated scheme involving locking
337 particular directories. This means that if you run multiple
338 copies of nailing-cargo at once, in different directories, but
339 with `Cargo.nail` files which imply overlapping sets of package
340 directories, things will go Badly Wrong.
342 Contributing and legal
343 ======================
345 nailing-cargo is Free Software.
347 Please help improve it. Contributions (to address the limitations, or
348 to add new facilities to help work with cargo) are welcome by email to
349 `ijackson@chiark.greenend.org.uk` or via the [Salsa
350 project](https://salsa.debian.org/iwj/nailing-cargo).
352 If you plan to do substantial work, please do get in touch with a
353 sketch of your proposed changes.
358 This project accepts contributions based on the git commit
359 Signed-off-by convention, by which the contributors certify their
360 contributions according to the Developer Certificate of Origin version
361 1.1 - see the file DEVELOPER-CERTIFICATE.
363 Copyright (C) 2019-2020 Ian Jackson and others
365 This program is free software: you can redistribute it and/or modify
366 it under the terms of the GNU Affero General Public License as
367 published by the Free Software Foundation, either version 3 of the
368 License, or (at your option) any later version.
370 This program is distributed in the hope that it will be useful,
371 but WITHOUT ANY WARRANTY; without even the implied warranty of
372 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
373 GNU Affero General Public License for more details.
375 You should have received a copy of the GNU Affero General Public License
376 along with this program. If not, see <http://www.gnu.org/licenses/>.
378 Individual files generally contain the following tag in the copyright
379 notice, instead of the full licence grant text:
381 SPDX-License-Identifier: AGPL-3.0-or-later
383 As is conventional, this should be read as a licence grant.