chiark / gitweb /
a2602a8217bea81d5406ca25da320b108c3b601e
[nailing-cargo.git] / README.md
1 nailing-cargo
2 =============
3
4 This is a wrapper tool for cargo, the Rust build tool and package
5 manager.  Functions:
6
7  * Conveniently use local crates, including completely
8    unpublished crates.
9  * Perform out-of-tree builds, including in an account with
10    no write access to the source tree.
11  * Provide convenience aliases for target architecture names.
12  * Make the default be offline (ie, not to access the internet).
13
14 These functions are of course configurable.
15
16 The primary source of information for nailing-cargo is the file
17 `../Cargo.nail` (which is in TOML syntax).  You put `Cargo.nail`
18 alongside the top-level git repositories you are working with, and
19 invoke nailing-cargo from the git directory containing the Rust
20 package you want to build.
21
22 Installing
23 ----------
24
25 nailing-cargo is designed to be run out of a git clone:
26
27 ```
28 $ git clone https://salsa.debian.org/iwj/nailing-cargo.git
29 $ ln -s `pwd`/nailing-cargo/nailing-cargo ~/bin
30 ```
31
32 It is self-contained, depending only on a reasonably functional Perl
33 installation.
34
35 Most basic example usage
36 ------------------------
37
38 ```
39 $ cd myproject
40 $ cat >../Cargo.nail
41 subdirs="""
42 myproject
43 mylibrary
44 """
45 $ nailing-cargo -u fetch
46 $ nailing-cargo build
47 ```
48
49 Documentation table of contents
50 -------------------------------
51
52 <!-- TOC autogenerated by ./markdown-toc-filter, do not edit -->
53
54   * [Introduction](#nailing-cargo)
55     * [Installing](#installing)
56     * [Most basic example usage](#most-basic-example-usage)
57     * [Documentation table of contents](#documentation-table-of-contents)
58   * [Using local crates, or locally modified crates](#using-local-crates-or-locally-modified-crates)
59     * [How nailing-cargo helps with using local crates](#how-nailing-cargo-helps-with-using-local-crates)
60     * [Telling nailing-cargo how to massage `Cargo.toml`](#telling-nailing-cargo-how-to-massage-cargo.toml)
61   * [Out-of-tree builds](#out-of-tree-builds)
62     * [How nailing-cargo helps with out-of-tree builds](#how-nailing-cargo-helps-with-out-of-tree-builds)
63     * [Configuring out-of-tree builds](#configuring-out-of-tree-builds)
64   * [Target architecture convenience aliases](#target-architecture-convenience-aliases)
65   * [Default change to offline mode](#default-change-to-offline-mode)
66   * [Invocation and command-line option reference](#invocation-and-command-line-option-reference)
67     * [Usages](#usages)
68     * [Options](#options)
69     * [Environment of the build command](#environment-of-the-build-command)
70   * [Configuration reference](#configuration-reference)
71     * [Source directories and packages (toplevel)](#source-directories-and-packages-toplevel)
72     * [`[alt_cargolock]`: Alternative `Cargo.lock` filename](#alt_cargolock-alternative-cargo.lock-filename)
73     * [`[oot]`: Out-of-tree build support](#oot-out-of-tree-build-support)
74     * [`[arch]`: Architecture convenience aliases](#arch-architecture-convenience-aliases)
75     * [`[misc]`: Miscellaneous individual nailing-cargo config](#misc-miscellaneous-individual-nailing-cargo-config)
76   * [Limitations and bugs](#limitations-and-bugs)
77   * [Contributing and legal](#contributing-and-legal)
78     * [Legal](#legal)
79
80 Using local crates, or locally modified crates
81 ==============================================
82
83 cargo does not work well with local crates,
84 especially completely unpublished ones.
85 (See [issue#6713](https://github.com/rust-lang/cargo/issues/6713),
86 [stackoverflow](https://stackoverflow.com/questions/33025887/how-to-use-a-local-unpublished-crate),
87 [issue#1481](https://github.com/rust-lang/cargo/issues/1481),
88 [my blog](https://diziet.dreamwidth.org/1805.html).)
89
90 Using a local version of a crate should be possible without putting
91 paths into your `Cargo.toml` and without editing complex
92 configuration.
93
94 How nailing-cargo helps with using local crates
95 -----------------------------------------------
96
97 nailing-cargo temporarily edits all the `Cargo.toml` files in all the
98 subdirectories you mention, to refer to each other; then it runs
99 cargo; and then it puts everything back.
100
101 Telling nailing-cargo how to massage `Cargo.toml`
102 -------------------------------------------------
103
104 To find the subdirectories, and the packages, nailing-cargo looks for
105 `subdirs` and `packages` in `Cargo.nail`.
106
107 For straightforward use, write `subdirs` as a multi-line string
108 containing a list of subdirectory names one per line.  In each of
109 these directories `Cargo.toml` will be massaged, and the package there
110 will be used for other massaged `Cargo.toml`s.
111
112 See the [Configuration reference](#configuration-reference) for full details.
113
114 Scope of nailing-cargo's local crate functionality
115 --------------------------------------------------
116
117 nailing-cargo's `Cargo.toml` massaging will allow you to easily build
118 an interdepending set of local packages, possibly even including
119 private unpublished packages, and/or locally-modified versions of
120 published packages.  These local packages can freely depend on
121 published packages (eg from `crates.io`) in the usual way.
122
123 Compared to the corresponding cargo feature, nailing-cargo's approach:
124 (i) works even for local crates that have not been published anywhere; and
125 (ii) is a lot simpler to configure.
126
127 But nailing-cargo's local crate support won't work if any non-local
128 crate needs to be rebuilt against a local crate (ie, a local version
129 of one of its dependencies).  If that is your requirement, either make
130 local versions of the intermediate crates in the dependency graph, or
131 use the cargo override facility --- see [Overriding
132 Dependencies](https://doc.rust-lang.org/cargo/reference/overriding-dependencies.html)
133 in the Cargo Book.
134
135 Out-of-tree builds
136 ==================
137
138 It is often desirable to run builds in a way that does not write to
139 the source tree.  cargo's enthusiastic approach to the dependency
140 management task means that it is a good idea to try to insulate your
141 main working environment from the many things cargo has decided to
142 download and execute.
143
144 However, when you tell cargo to do an out of tree build (using
145 `--manifest-path`) it will insist on `Cargo.lock` being in the source
146 directory, and often will insist on writing to it.
147
148 How nailing-cargo helps with out-of-tree builds
149 -----------------------------------------------
150
151 nailing-cargo (configured appropriately) copies files back and forth
152 to between the source and build directories, and runs cargo as your
153 build user.
154
155 The `Cargo.lock` must still be saved in your source tree somewhere.
156 nailing-cargo arranges this for you.  You can either put this file in
157 `.gitignore`; or commit it to git; or you can tell nailing-cargo to
158 save it as something like `Cargo.lock.example`.
159
160 Configuring out-of-tree builds
161 ------------------------------
162
163 To enable out-of-tree-builds, put an `[oot]` section in your
164 `Cargo.nail` or one of nailing-cargo's other config files.
165 In that section, specify at least `use`.
166
167 Also, specify `dir`, or create a symlink `Build` next to `Cargo.nail`,
168 pointing to to your build area.
169
170 For example,
171 ```
172 [oot]
173 use='ssh'
174 user='rustcargo'
175 ```
176 will have nailing-cargo run `ssh rustcargo@localhost` to
177 run build commands.
178
179 Target architecture convenience aliases
180 =======================================
181
182 If you are cross-building you may need to tell cargo `--target=`.
183 The architecture names are quite long and inconvenient.
184
185 A simple shell alias would help a lot, except that cargo rejects
186 `--target=` when it thinks it's not needed.
187
188 In your nailing-cargo config, you can write something like
189 `arch.RPI='arm-unknown-linux-gnueabihf'`.  Then `nailing-cargo -TRPI`
190 will DTRT.  In fact, you do not even need to specify that particular
191 arch alias, since it is built-in to nailing-cargo.
192
193 Default change to offline mode
194 ==============================
195
196 It seems to me that build tools should be explicit about their use of
197 the network.  So by default, nailing-cargo passes `--offline` to
198 cargo.
199
200 If you disagree with my opinion, write `misc.online=true` in your
201 nailing-cargo configuration.  `misc.online=false`, and command line
202 options, are also available, for overriding.
203
204 If you agree with me, you may wish to use `nailing-cargo
205 generate-lockfile`, which can update (even an existing) `Cargo.lock`
206 without going online, instead of `update`.
207
208 Invocation and command-line option reference
209 ============================================
210
211 Usages
212 ------
213
214 ```
215 1$ nailing-cargo <nailing-opts> <cargo-opts> [--] <subcmd>...
216 2$ nailing-cargo <nailing-opts> --- <cargo> <cargo-opts> [--] <subcmd>...
217 3$ nailing-cargo <nailing-opts> --- [--] <build-command>...
218 ```
219 Ususally the `--` is not needed.  (It should generally be passed by
220 programs which wrap nailing-cargo.  See [Invocation argument disambiguation rules](#invocation-argument-disambiguation-rules), below.)
221
222 In usage 1, nailing-cargo runs `cargo` (from `PATH`).  In the usage 2
223 nailing-cargo runs `<cargo>`.  In both these cases it adds its own
224 options to control cargo's behaviour.  In both of these cases
225 nailing-cargo looks at `<subcmd>` to determine the cargo subcommand
226 being run: this controls various defaults, to try to do the right
227 things.
228
229 In the third syntax, nailing-cargo runs `<build-command>...` without
230 additional arguments and does not attempt to identify the cargo
231 subcommand(s) that it will run.  Possibly it will be necessary to pass
232 `--online` or `--cargo-lock-update`, or even `--cargo-*arg*`
233
234 ### Invocation argument disambiguation rules ###
235
236 For authors of tools which call nailing-cargo (and pedants):
237
238 The usages overlap in syntax!  nailing-cargo follows the following
239 rules when interpreting its command line:
240
241   * The first option not recognised as a nailing-cargo option is
242     treated as the start of the `<cargo-opts>`.
243
244   * `<cargo-opts>` are terminated by `--` (which is removed) or the
245     first argument which does not start with a `-`.
246
247     (It is not possible to get nailing-cargo to pass the value `--`
248     as a separate argument to a cargo global option, but cargo global
249     options can typically take the values cuddled with `=`, so doing
250     that is not necessary.)
251
252   * After `---`, nailing-cargo will search for a `--`, to the end of
253     the arguments if necessary.  The position of the `--` determines
254     whether this is usage 2 or usage 3, and what `<subcmd>` is.
255
256     If the arguments after `nailing-cargo ... ---` might contain `--`
257     anywhere, an explicit `--` should be passed.
258
259   * If no `--` appears after `---`, the word after `---` is the
260     command to run; if its final pathname component contains the
261     string `cargo`, it is treated as `<cargo>` (implying usage 2 and
262     the search for `<subcmd>`).  Otherwise it is treated as
263     `<build-command>` (usage 3).
264
265 Options
266 -------
267
268   * `-v`: Increase verbosity.  Default is 1.
269
270   * `-q`: Set verbosity to 0.
271
272   * `-D`: Increase amount of debugging dump.
273
274   * `-n`: "No action": stop after writing `Cargo.toml.nailing~`
275        everywhere, and do not run any build command.
276
277   * `-T<arch>` | `--target=<arch>`
278
279     Specify target architecture.
280
281     This option translates to a `--target=<arch>` option to cargo
282     (when the subcommand accepts it).
283
284     If `<arch>` starts with a capital ascii letter, it is an alias
285     for some other arch: it is looked up in the configuration, and
286     then in the builtin arch alias list.  The builtin list is
287     equivalent to: `[arch]` `RPI='arm-unknown-linux-gnueabihf'`.
288
289   * `-o` | `--online` | `-O` | `--offline`
290
291     Whether to allow cargo to make network access.  nailing-cargo
292     always passes `--offline` to cargo, unless `--online` is in
293     force.  The default value depends on the configuration and the
294     cargo subcommand - see [`[misc]` `online`](#misc_online),
295     under Configuration.
296
297   * `-u` | `--cargo-lock-update` | `-U` | `--no-cargo-lock-update`
298
299     Allows (or disallows) cargo to update `Cargo.lock` in the source
300     directory.  Without this enabled, nailing-cargo passes `--locked`
301     to cargo.
302
303     With this enabled, in an out-of-tree build the `Cargo.lock` and
304     `Cargo.toml` are copied to the build directory along with a
305     linkfarm, to fool cargo.  After cargo has run, the resulting
306     `Cargo.lock` is copied back to the source tree.
307
308     Default is no update unless the whole point of the cargo
309     subcommand is to update `Cargo.lock`.
310
311   * `-c` | `-C`
312
313     Controls the addition of cargo command line options; ie,
314     whether nailing-cargo should treat the build command as if it
315     were cargo.
316     With `-C`, nailing-cargo will not add additional options
317     to the build command.  With `-c` it will pass those options
318     after the cargo subcommand (usages 1 and 2) or right
319     after the build command (usage 3).
320
321     The cargo options are in any case also passed in the
322     environment - see [Environment of the build command](#environment-of-the-build-command).
323
324     The default is to pass cargo options if the command line
325     parsing yielded a cargo command and options (usages 1 and 2),
326     rather than a non-cargo build command (usage 3).  `-C` and `-c`
327     do not affect the parsing of nailing-cargo's command line.
328
329   * <a name="s_subcommand">`-s<subcommand>`</a>
330
331     Behave as if the build command were `cargo <subcommand>`.
332     This influences the logic which tries to determine which
333     options to pass to cargo, whether cargo needs to be online, and
334     whether cargo might want to update `Cargo.lock`.
335
336     nailing-cargo knows about `update`, `generate-lockfile` and
337     `fetch`; all other subcommands are (silently) treated the same way
338     as `build` (ie, no subcommand properties).  See
339     `--subcommand-props` for more detail about how the
340     subcommand affects nailing-cargo's behaviour.
341
342     The default is to use the cargo subcommand found from parsing
343     nailing-cargo's command line.  NB: `-s` does not affect
344     which build command (and which cargo subcommand) is actually run.
345
346   * <a name="subcommand_props">`--subcommand-props=<prop>,...`</a>
347
348     Specify the properties of the subcommand.  This is an
349     alternative to `-s<subcmd>`.  The usual properties are:
350
351     * `lock_update`: cargo will want to update `Cargo.lock`.  (The `-u` and `-U` options override this.)
352     * `online`: this subcommand makes no sense to run offline.  (The `-o` and `-O` options, and the configuration, can override this.)
353     * `!target`: cargo would reject `--target=<arch>`; in this case nailing-cargo's `-T` option is ineffective.
354     * `!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`.)
355
356
357     There are also some properties which should not be needed, but are
358     provided for completeness.  Do not use these to solve the problem
359     of nailing-cargo passing cargo options to a build command which is
360     not cargo - use `-C` for that.  The properties whose use is discouraged:
361
362     * `!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`.
363     * `!locked`: cargo would reject `--locked`, so don't pass it.  Hazardous.
364     * `!offline`: the build command would reject `--offline`, so never pass it.  *Not* overridden by configuration or command line.
365
366   * `-h` | `--help`: Print usage summary.
367
368 Environment of the build command
369 --------------------------------
370
371 nailing-cargo passes these environment variables to the build command:
372
373   * `CARGO_MANIFEST_DIR`: invocation `.` (invocation directory)
374   * `NAILINGCARGO_MANIFEST_DIR`: same as `CARGO_MANIFEST_DIR`
375   * `NAILINGCARGO_WORKSPHERE`: invocation `..` (parent)
376   * `NAILINGCARGO_BUILD_DIR`: build directory (even if same as source)
377   * `NAILINGCARGO_BUILDSPHERE`: parent of build dir (only set if out-of-tree)
378   * `NAILINGCARGO_CARGO_OPTIONS`: additional options that nailing-cargo passed (or would pass) to cargo.  Space-separated; does not include `--manifest-path`.
379
380 All of these are absolute paths.
381
382 ### Build commands which wrap cargo ###
383
384 If you specify a build command which eventually runs cargo, you may
385 wish to pass on to your cargo the options which nailing-cargo would
386 have passed.  This will definitely be necessary if you are using nailing-cargo's out-of-tree facility.
387
388 In such a situation, do it like this:
389 ```
390   cargo build --manifest-path="${CARGO_MANIFEST_DIR-.}"/Cargo.toml $NAILINGCARGO_CARGO_OPTIONS
391 ```
392
393 If you need to run a cargo subcommand which doesn't understand some of
394 nailing-cargo's options, currently, you must strip them out of
395 `NAILINGCARGO_CARGO_OPTIONS` yourself - or pass some `-s` or
396 `--subcmd-props` option to nailing-cargo (but that is a layering
397 violation and may not work if one build command runs various different
398 cargo runes).
399
400 Configuration reference
401 =======================
402
403 nailing-cargo reads these configuration files:
404 ```
405     /etc/nailing-cargo/cfg.toml
406     ~/.nailing-cargo.toml
407     ./.nailing-cargo.toml
408     ../Nailing-Cargo.toml
409     ../Cargo.nail
410 ```
411 Settings in later-mentioned files override ones in earlier-mentioned
412 files.
413
414 Source directories and packages (toplevel)
415 ------------------------------------------
416
417 Note that unlike everything else, these keys (`packages` and
418 `subdirs`) are read only from `Cargo.nail` (see "Limitations and
419 bugs", below).
420
421 These keys specify a combination of (i) a mapping from package name to
422 source subdirectory (ii) a set of subdirectories whose `Cargo.toml`
423 must be massaged.
424
425   * `packages`: a map keyed by package name, giving the subdirectory
426     for each one.
427
428     This causes each mentioned subdirectory's `Cargo.toml` to be
429     massaged, and records that subdirectory as the source for that
430     package.  (nailing-cargo will check that subdirectory actually
431     contains the indicated package.)
432
433     Each value can be just the subdirectory name (eg `[packages]`
434     `mylibrary='mylibrary-test'`) or itself a map with the key `subdir`
435     (eg `[packages.mylibrary]` `subdir='mylibrary-test'`).
436
437   * `subdirs`: a list of subdirectory names to process.
438
439     Each subdirectory's `Cargo.toml` will be massaged.  Also, the
440     subdirectory will be examined to see what package it contains; it
441     will then be used as the source for that package, unless that
442     package appears in an entry in `packages`, or an earlier entry in
443     `subdirs`.
444
445     This can be a list of strings (eg `subdirs =
446     ['myproject','mylibrary']`).  Or it can be single multi-line
447     string containing one subdirectory name per line; in that
448     case, `#`-comments are supported and tabs and spaces are ignored
449     (see "Most basic example usage" above.)
450
451 In each case the subdirectory should usually be a relative pathname;
452 it is relative to the directory containing `Cargo.nail`.
453
454 `[alt_cargolock]`: Alternative `Cargo.lock` filename
455 ----------------------------------------------------
456
457 To control use of alternative `Cargo.lock` filename, use the section
458 `[alt_cargolock]`.  Settings here:
459
460   * `file = <some leafname>`.
461
462   * `file = true`: Equivalent to `file = "Cargo.lock.example"`.
463     (This is the default.)
464
465   * `file = false`: Disables this feature.
466
467   * `force = false`: Uses the alternative filename only if it
468      already exists.  (This is the default.)
469
470   * `force = true`: Always uses the alternative filename.
471
472 `[oot]`: Out-of-tree build support
473 ----------------------------------
474
475   * `dir`: The build directory.  If relative, it is relative to the
476    parent of the invocation directory (and could be a symlink then).
477    Default is `Build` (assuming `use` is specified).
478
479    The build directory will contain one subdir for each package: each
480    subdir in the build dir corresponds to one source dir where
481    nailing-cargo was invoked.  nailing-cargo will arrange to create
482    these subdirectories, so the build directory can start out empty.
483
484   * `use`: How to become the build user.  Needs to be combined
485     with other setting(s):
486
487     * `ssh`: Use ssh.  `user` must be given as well and can be
488        a username on localhost, or the `<user>@<host>`
489        argument to ssh.
490
491     * `command_args`: `command` must be specified as a list,
492        specifying a command and arguments which work like `nice`.
493
494     * `command_sh`: `command` must be specified as a list,
495        specifying a command and arguments which work like `sh -c`.
496
497     * `null`: Run builds as the same user.
498
499     * `really`: Use `really` from `chiark-really.deb`.
500        `user` must be given as well.
501
502     * `disable': Disable this feature, even if `dir` is set.
503
504  * `command`: The command to run for `command_sh` or `command_args`.
505
506    In both cases, this is a command and its arguments/options.  The
507    list will be passed to `execvp`.  The difference between
508    `command_args` and `command_sh` is in what nailing-cargo appends to
509    the specified `command` list:
510
511    For `command_args`, nailing cargo appends multiple more arguments;
512    each one should be passed as-is as a single argument to the actual
513    build command.  This is correct if `command` is a program like
514    `nice` or `really`, which takes a command and its arguments and
515    does not go via the shell.
516
517    For `command_sh`, nailing-cargo appends one single further
518    argument.  That argument is a shell command; nailing-cargo
519    constructs it by shell-quoting the real command and arguments and
520    wrapping them up in a small script, the text of which becomes the
521    extra argument to `command`.  This is correct if `command` will
522    pass its argument to a bournelike shell - for example, if `command`
523    is an ssh rune for a remote account whose shell is `/bin/sh` or
524    `/bin/bash`.
525
526  * `user`: The build username, for `really` and `ssh`.  For `ssh`, can
527    be just the local username (meaning `@localhost`), or
528    `<user>@<host>`.
529
530 `[arch]`: Architecture convenience aliases
531 ------------------------------------------
532
533 This is a map from archictecture aliases to full cargo architecture
534 names.  The keys are the aliases; each entry should be a string, the
535 cargo architecture name.
536
537 Only keys starting with an ascii uppercase letter are relevant, since
538 other names are not looked up in this alias map.
539
540 `[misc]`: Miscellaneous individual nailing-cargo config
541 -------------------------------------------------------
542
543  * <a name="misc_online">`online`</a>:
544
545    Specifies whether to allow or prevent cargo from accessing the
546    network.  Value is a boolean or `'auto'`.  `'auto'` permits online
547    access if the cargo subcommand being invoked is one whose main
548    purpose involves online access.
549
550    Implemented by passing `--offline` to cargo when necessary ---
551    cargo's default is online.  nailing-cargo's default is
552    `'auto'`.
553
554 Limitations and bugs
555 ====================
556
557   * nailing-cargo temporarily dirties your source trees, including
558     particularly `Cargo.toml` and `Cargo.lock`; and if nailing-cargo
559     crashes or is interrupted these changes may be left behind.
560     Unfortunately it is not possible to avoid this temporary dirtying
561     because the cargo team have deliberately made cargo inflexible -
562     [issue#6715](https://github.com/rust-lang/cargo/issues/6715).  
563     At least, running nailing-cargo again will clean up any mess
564     left by an interrupted run.
565
566   * nailing-cargo needs to understand the behaviour of the cargo
567     subcommand you are running - especially for out-of-tree builds.
568     nailing-cargo only has a short builtin list of commands it knows
569     about (see [`-s<subcommand`](#s_subcommand)).  For other commands, you may need to
570     add an entry to `@subcmd_props` in the source, or use
571     [`--subcommand-props`](#subcommand_props).
572
573     Contributions of additonal entries to `@subcmd_props` (or bug
574     reports about missing entries) are of course very welcome.
575
576   * Out-of-tree builds ought to support `sudo`.  Patches welcome.
577
578   * Out-of-tree builds require a unified filesystem view: eg, different
579     users on the same host, NFS, or something.
580
581     Specifically, the invocation and build execution environments must
582     both have visibility of the source and build directories, at the
583     same absolute pathnames.  The invocation environment must be able
584     to write to the build environment (but vice versa is not
585     required).
586
587     This could be improved.
588
589   * The alternative `Cargo.lock` filename must currently be a leafname.  I
590     think fixing this just involves review to check other values work
591     properly.
592
593   * The alternative `Cargo.lock` file must be on the same filesystem
594     as the source tree.  This is not so easy to fix; we would want the
595     existing algorithm but a fallback for the different-filsystem case.
596
597   * `Cargo.nail` is unconditionally looked for in the parent directory.
598     Ideally this should be configurable, and also perhaps be able to
599     combine multiple `Cargo.nail` files?  Relatedly, although
600     nailing-cargo can read multiple config files, it can only handle
601     one file specifying directories and packages.
602
603   * nailing-cargo uses a single lockfile alongside your `Cargo.nail`,
604     rather than a more sophisticated scheme involving locking
605     particular directories.  This means that if you run multiple
606     copies of nailing-cargo at once, in different directories, but
607     with `Cargo.nail` files which imply overlapping sets of package
608     directories, things will go Badly Wrong.
609
610 Contributing and legal
611 ======================
612
613 nailing-cargo is Free Software.
614
615 Please help improve it.  Contributions (to address the limitations, or
616 to add new facilities to help work with cargo) are welcome by email to
617 `ijackson@chiark.greenend.org.uk` or via the [Salsa
618 project](https://salsa.debian.org/iwj/nailing-cargo).
619
620 If you plan to do substantial work, please do get in touch with a
621 sketch of your proposed changes.
622
623 Legal
624 -----
625
626 This project accepts contributions based on the git commit
627 Signed-off-by convention, by which the contributors certify their
628 contributions according to the Developer Certificate of Origin version
629 1.1 - see the file DEVELOPER-CERTIFICATE.
630
631 Copyright (C) 2019-2020 Ian Jackson and others
632
633 This program is free software: you can redistribute it and/or modify
634 it under the terms of the GNU Affero General Public License as
635 published by the Free Software Foundation, either version 3 of the
636 License, or (at your option) any later version.
637
638 This program is distributed in the hope that it will be useful,
639 but WITHOUT ANY WARRANTY; without even the implied warranty of
640 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
641 GNU Affero General Public License for more details.
642
643 You should have received a copy of the GNU Affero General Public License
644 along with this program.  If not, see <http://www.gnu.org/licenses/>.
645
646 Individual files generally contain the following tag in the copyright
647 notice, instead of the full licence grant text:
648 ```
649    SPDX-License-Identifier: AGPL-3.0-or-later
650 ```
651 As is conventional, this should be read as a licence grant.