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 * Makes 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 eveyrthing 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 `packages` is a mapping from package names to dictionaries (e.g. in
86 `Cargo.nail`, write something like: `[packages.mylibrary]`
87 `subdir='mylibrary-test'` or `[packages]` `mylibrary='mylibrary-test'`).
88 These override the locations for the specified packages (so you can,
89 for example, have multiple trees with the same package in). The
90 `subdir` values are also added to the list of directories where
91 `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 is
135 the `<user>@<host>` argument to ssh.
137 * `command_args`: `command` must be specified as a list,
138 specifying a command and arguments which work like `nice`.
140 * `command_sh`: `command` must be specified as a list,
141 specifying a command and arguments which work like `sh -c`.
143 * `null`: Run builds as the same user.
145 * `really`: Use `really` from `chiark-really.deb`.
146 `user` must be given as well.
148 Target architecture convenience aliases
149 =======================================
151 If you are cross-building you may need to tell cargo `--target=`.
152 The architecture names are quite long and inconvenient.
154 A simple shell alias would help a lot, except that cargo rejects
155 `--target=` when it thinks it's not needed.
157 In your nailing-cargo config, you can write soemthing like
158 `arch.RPI='arm-unknown-linux-gnueabihf'`. Then `nailing-cargo -ARPI`
159 will DTRT. In fact, you do not even need to specify that particular
160 arch alias, since it is built-in to nailing-cargo.
162 Default change to offline mode
163 ==============================
165 It seems to me that build tools should be explicit about their use of
166 the network. So by default, nailing-cargo passes `--offline` to
169 If you disagree with my opinion, write `misc.online=true` in your
170 nailing-cargo configuration. `misc.online=false`, and command line
171 options, are also available, for overriding.
176 * `-v`: Increase verbosity. Default is 1.
178 * `-q`: Set verbosity ot 0.
180 * `-D`: Increase amount of debugging dump.
182 * `-n`: "No action": stop after writing Cargo.toml.nailing~
183 everywhere, and do not run any build command.
185 * `-A<arch>` | `--arch=<arch>` | `--target=<arch>`
187 Specify target architecture. If `<arch>` starts with a capital
188 ascii letter, is an alias for some other arch: it is looked up
189 in the configuration, and then in the builtin arch alias list.
190 The builtin list is equivalent to: `[arch]`
191 `RPI='arm-unknown-linux-gnueabihf'`.
193 This option translates to a --target= option to the ultimate
194 command, unless that is a cargo subcommand which would reject
195 it. `--arch` and `--target` are simply aliases.
197 * `-u` | `--cargo-lock-update` | `-U` | `--no-cargo-lock-update`
199 Enables, or disables, the dance to allow Cargo.lock (or
200 alternative) to be updated in the source directory.
202 With this dance enabled the Cargo.lock and Cargo.toml are
203 copied to the build directory along with a skeleton just big
204 enough to fool cargo. After cargo has run, the resulting
205 Cargo.lock is copied back to the source tree.
207 This makes no sense with in-tree builds.
209 Default is no update unless the ultimate command is a
210 cargo subcommand which we know needs it.
212 * `-m` | `--cargo-manifest-args` | `-M` | `--no-cargo-manifest-args`
214 Controls whether we add cargo command line options relating to
215 finding `Cargo.toml`, to the command to run.
217 Default is to add them iff we are doing an out-of-tree build,
218 unless we are doing the dance to update the `Cargo.lock` (see
219 above) in which case the only relevant files are to be found in
220 the build directory).
222 The arguments added are
224 --manifest-path=<path/to/Cargo.toml>
228 * `-T` | `--no-cargo-target-dir-arg` | `-t` | `--cargo-target-dir-arg`
230 `-T` suppresses `--target-dir`; `-t` un-suppresses it. Only
231 makes any difference with `-m`, since otherwise no
232 `--target-dir` would be passed anyway. Additionally this is
233 done automatically when nailing-cargo sees that the cargo
234 subcommand is one which needs it, eg `fetch'.
236 * `-o` | `--online` | `--offline` | `-O`
238 Whether to allow cargo to make network access. nailing-cargo
239 always passes `--offline` to cargo, unless `--online` is in
240 force. The default is offline, unless the cargo subcommand is
241 one which implies online (currently, `fetch').
246 nailing-cargo reads these configuration files:
248 /etc/nailing-cargo/cfg.toml
249 ~/.nailing-cargo.toml
250 ./.nailing-cargo.toml
251 ../Nailing-Cargo.toml
254 Settings in later-mentioned files override ones in earlier-mentioned
257 Note that unlike everything else, `packages` and `subdirs` are read
258 only from `Cargo.nail` (see "Limitations and bugs", below).
260 Alternative `Cargo.lock` filename
261 ---------------------------------
263 To control use of alternative Cargo.lock filename, use the section
264 `[alt_cargolock]`. Settings here:
266 * `file = false`: disables this feature
268 * `file = true`: equivalent to `file = "Cargo.lock.example"`
270 * `file = <some leafname>`
272 * `force = false`: Use the alternative file only if it
273 already exists. (This is the default.)
275 * `force = true`: Always uses the alternative filename.
280 Normally you pass `cargo` as an argument to `nailing-cargo`. But you
281 can also pass `make` or any other command. You may need to pass
282 `--no-cargo-manifest-args` to nailing-cargo.
284 nailing-cargo passes these environment variables to the build command:
286 * `NAILINGCARGO_WORKSPHERE`: invocation `..` (parent)
287 * `NAILINGCARGO_MANIFEST_DIR`: invocation `.` (invocation directory)
288 * `NAILINGCARGO_BUILD_DIR`: build directory (even if same as source)
289 * `NAILINGCARGO_BUILDSPHERE`: only set if out of tree: parent of build dir.
291 All of these are absolute paths.
296 * nailing-cargo dirties your source trees, including particularly
297 `Cargo.toml` and `Cargo.lock`, temporarily. If nailing-cargo crashes
298 or is interrupted these changes may be left behind; running
299 nailing-cargo again should clean up such a mess. Unfortunately it is
300 not possible to fix this bug because the cargo team have deliberately
301 made cargo inflexible -
302 [issue#6715](https://github.com/rust-lang/cargo/issues/6715).)
304 * Out of tree builds require a unified filesystem view: eg, different
305 users on the same host, NFS, or something. This could be improved.
307 The alternative Cargo.lock filename must currently be a leafname. I
308 think fixing this just involves review to check other values work
311 * The alternative Cargo.lock file must be on same filesystem. This is
312 not so easy to fix; we would want the existing algorithm but a
313 fallback for this case.
315 * Cargo.nail is unconditionally looked for in `..`. Ideally should be
316 configurable, and also perhaps be able to combine multiple Cargo.nail
317 files? Relatedly, although nailing-cargo can read multiple config
318 filos, it can only handle one file specifying directories and
321 * Contributions to address these would be welcome, of course. If you
322 plan to do substantial work, please do get in touch with a sketch of
323 your proposed changes.
325 * nailing-cargo uses a single lockfile alongside your `Cargo.nail`,
326 rather than a more sophisticated scheme involving locking
327 particular directories. This means that if you run multiple
328 copies of nailing-cargo at once, in different directories, but
329 with `Cargo.nail` files which imply overlapping sets of package
330 directories, things will go Badly Wrong.
332 Contributing and legal
333 ======================
335 nailing-cargo is Free Software.
337 Please help improve it. Contributions are welcome by email to
338 `ijackson@chiark.greenend.org.uk` or via the
339 [Salsa project](https://salsa.debian.org/iwj/nailing-cargo).
341 Legally, the project accepts contributions which follow the git commit
342 Signed-off-by convention, by which the contributors certify their
343 contributions according to the Developer Certificate of Origin version
344 1.1 - see the file DEVELOPER-CERTIFICATE.
346 Copyright (C) 2019-2020 Ian Jackson and others
348 This program is free software: you can redistribute it and/or modify
349 it under the terms of the GNU Affero General Public License as
350 published by the Free Software Foundation, either version 3 of the
351 License, or (at your option) any later version.
353 This program is distributed in the hope that it will be useful,
354 but WITHOUT ANY WARRANTY; without even the implied warranty of
355 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
356 GNU Affero General Public License for more details.
358 You should have received a copy of the GNU Affero General Public License
359 along with this program. If not, see <http://www.gnu.org/licenses/>.
361 Individual files generally contain the following tag in the copyright
362 notice, instead of the full licence grant text:
364 SPDX-License-Identifier: AGPL-3.0-or-later
366 As is conventional, this should be read as a licence grant.