chiark / gitweb /
README.md: oot config: discuss build dir contents
[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
10  * Perform out-of-tree builds, including in an account with
11    no write access to the source tree.
12
13  * Provide convenience aliases for target architecture names.
14
15  * Make the default be offline (ie, not to access the internet)
16
17 These functions are of course configurable.
18
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.
24
25 Installing
26 ----------
27
28 nailing-cargo is designed to be run out of a git clone:
29
30 ```
31 $ git clone https://salsa.debian.org/iwj/nailing-cargo.git
32 $ ln -s `pwd`/nailing-cargo/nailing-cargo ~/bin
33 ```
34
35 It is self-contained, depending only on a reasonably functional Perl
36 installation.
37
38 Most basic example usage
39 ------------------------
40
41 ```
42 $ cd myproject
43 $ cat >../Cargo.nail
44 subdirs="""
45 myproject
46 mylibrary
47 """
48 $ nailing-cargo cargo generate-lockfile
49 $ nailing-cargo cargo build
50 ```
51
52 Using local crates, or locally modified crates
53 ==============================================
54
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).)
61
62 Using a local version of a crate should be possible without putting
63 paths into your `Cargo.toml` and without editing complex
64 configuration.
65
66 How nailing-cargo helps with using local crates
67 -----------------------------------------------
68
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.
72
73 Telling nailing-cargo how to massage `Cargo.toml`
74 -------------------------------------------------
75
76 To find the subdirectories, and the packages, it looks for `subdirs`
77 and `packages` in `Cargo.nail`.
78
79 For straightforward use, write `subdirs` as a multi-line string
80 containing a list of subdirectory names one per line.  In each of
81 these directories `Cargo.toml` will be massaged, and the package there
82 will be used for other massaged `Cargo.toml`s.
83
84 See "Configuration", below, for the full reference.
85
86 Out-of-tree builds
87 ==================
88
89 It is often desirable to run builds in a way that does not write to
90 the source tree.  cargo's enthusiastic approach to the dependency
91 management task means that it is a good idea to try to insulate your
92 main working environment from the many things cargo has decided to
93 download and execute.
94
95 However, when you tell cargo to do an out of tree build (using
96 `--manifest-path`) it will insist on `Cargo.lock` being in the source
97 directory, and often will insist on writing to it.
98
99 How nailing-cargo helps with out-of-tree builds
100 -----------------------------------------------
101
102 nailing-cargo (configured appropriately) copies files back and forth
103 to between the source and build directories, and runs cargo as your
104 build user.
105
106 The `Cargo.lock` must still be saved in your source tree somewhere.
107 nailing-cargo arranges this for you.  You can either put this file in
108 `.gitignore`; or commit it to git; or you can tell nailing-cargo to
109 save it as something like `Cargo.lock.example`.
110
111 Configuring out-of-tree builds
112 ------------------------------
113
114 To enable out-of-tree-builds, put an `[oot]` section in your
115 `Cargo.nail` or one of nailing-cargo's other config files.
116 In that section, specify at least `use`.
117
118 Also, specify `dir`, or create a symlink `Build` next to `Cargo.nail`,
119 pointing to to your build area.
120
121 For example,
122 ```
123 [oot]
124 use='ssh'
125 user='rustcargo'
126 ```
127 will have nailing-cargo run `ssh rustcargo@localhost` to
128 run build commands.
129
130 Target architecture convenience aliases
131 =======================================
132
133 If you are cross-building you may need to tell cargo `--target=`.
134 The architecture names are quite long and inconvenient.
135
136 A simple shell alias would help a lot, except that cargo rejects
137 `--target=` when it thinks it's not needed.
138
139 In your nailing-cargo config, you can write something like
140 `arch.RPI='arm-unknown-linux-gnueabihf'`.  Then `nailing-cargo -ARPI`
141 will DTRT.  In fact, you do not even need to specify that particular
142 arch alias, since it is built-in to nailing-cargo.
143
144 Default change to offline mode
145 ==============================
146
147 It seems to me that build tools should be explicit about their use of
148 the network.  So by default, nailing-cargo passes `--offline` to
149 cargo.
150
151 If you disagree with my opinion, write `misc.online=true` in your
152 nailing-cargo configuration.  `misc.online=false`, and command line
153 options, are also available, for overriding.
154
155 Command-line options
156 ====================
157
158   * `-v`: Increase verbosity.  Default is 1.
159
160   * `-q`: Set verbosity to 0.
161
162   * `-D`: Increase amount of debugging dump.
163
164   * `-n`: "No action": stop after writing `Cargo.toml.nailing~`
165        everywhere, and do not run any build command.
166
167   * `-A<arch>` | `--arch=<arch>` | `--target=<arch>`
168
169        Specify target architecture.
170
171        This option translates to a `--target=<arch>` option to the
172        ultimate command, unless that is a cargo subcommand which we
173        know would reject it.  `--arch` and `--target` are simply
174        aliases.
175
176        If `<arch>` starts with a capital ascii letter, it is an alias
177        for some other arch: it is looked up in the configuration, and
178        then in the builtin arch alias list.  The builtin list is
179        equivalent to: `[arch]` `RPI='arm-unknown-linux-gnueabihf'`.
180
181   * `-u` | `--cargo-lock-update` | `-U` | `--no-cargo-lock-update`
182
183        Enables, or disables, the dance to allow `Cargo.lock` (or
184        alternative) to be updated in the source directory.
185
186        With this dance enabled the `Cargo.lock` and `Cargo.toml` are
187        copied to the build directory along with a skeleton just big
188        enough to fool cargo.  After cargo has run, the resulting
189        `Cargo.lock` is copied back to the source tree.
190
191        This makes no sense with in-tree builds.
192
193        Default is no update unless the ultimate command is a
194        cargo subcommand which we know needs it.
195
196   * `-m` | `--cargo-manifest-args` | `-M` | `--no-cargo-manifest-args`
197
198        Controls whether we add cargo command line options, relating to
199        finding `Cargo.toml`, to the command to run.
200
201        Default is to add them if we are doing an out-of-tree build,
202        unless we are doing the dance to update the `Cargo.lock` (see
203        above) since in that case all the relevant files can be found
204        by cargo in the build directory.
205
206        The arguments added are
207
208            --manifest-path=<path/to/Cargo.toml>
209            --locked
210            --target-dir=target
211
212   * `-T` | `--no-cargo-target-dir-arg` | `-t` | `--cargo-target-dir-arg`
213
214        `-T` suppresses `--target-dir`; `-t` un-suppresses it.  Only
215        makes any difference with `-m`, since otherwise no
216        `--target-dir` would be passed anyway.  Additionally this is
217        done automatically when nailing-cargo sees that the cargo
218        subcommand is one which needs it, eg `fetch`.
219
220   * `-o` | `--online` | `-O` | `--offline`
221
222        Whether to allow cargo to make network access.  nailing-cargo
223        always passes `--offline` to cargo, unless `--online` is in
224        force.  The default is offline, unless the cargo subcommand is
225        one which implies online (currently, `fetch`).
226
227 Configuration
228 =============
229
230 nailing-cargo reads these configuration files:
231 ```
232     /etc/nailing-cargo/cfg.toml
233     ~/.nailing-cargo.toml
234     ./.nailing-cargo.toml
235     ../Nailing-Cargo.toml
236     ../Cargo.nail
237 ```
238 Settings in later-mentioned files override ones in earlier-mentioned
239 files.
240
241 Source directories and packages (toplevel)
242 ------------------------------------------
243
244 Note that unlike everything else, these keys `packages` and `subdirs`
245 are read only from `Cargo.nail` (see "Limitations and bugs", below).
246
247 These keys specify a combination of (i) a mapping from package name to
248 source subdirectory (ii) a set of subdirectories whose `Cargo.toml`
249 must be massaged.
250
251   * `packages`: a map keyed by package name, giving the subdirectory
252     for each one.
253
254     This causes each mentioned subdirectory's `Cargo.toml` to be
255     massaged, and records that subdirectory as the source for that
256     package.  (nailing-cargo will check that subdirectory actually
257     contains the indicated package.)
258
259     Each value can be just the subdirectory name (eg `[packages]`
260     `mylibrary='mylibrary-test'`) or itself a map with the key `subdir`
261     (eg `[packages.mylibrary]` `subdir='mylibrary-test'`).
262
263   * `subdirs`: a list of subdirectory names to process.
264
265     Each subdirectory's `Cargo.toml` will be massaged; also, the
266     subdirectory will be examined to see what package it contains and
267     it will be used as the source for that package, unless that
268     package appears in an entry in `packages`, or an earlier entry in
269     `subdirs`.
270
271     This can be a list of strings (eg `subdirs =
272     ['myproject','mylibrary']`).  Or it can be single multi-line
273     string containing one subdirectory name per line; in that
274     case, `#`-comments are supported and tabs and spaces are ignored
275     (See "Most basic example usage" above.)
276
277 In each case the subdirectory should usually be a relative pathname;
278 it is relative to the directory containing `Cargo.nail`.
279
280 `[alt_cargolock]`: Alternative `Cargo.lock` filename
281 ----------------------------------------------------
282
283 To control use of alternative `Cargo.lock` filename, use the section
284 `[alt_cargolock]`.  Settings here:
285
286   * `file = <some leafname>`.
287
288   * `file = true`: Equivalent to `file = "Cargo.lock.example"`.
289     (This is the default.)
290
291   * `file = false`: Disables this feature.
292
293   * `force = false`: Uses the alternative filename only if it
294      already exists.  (This is the default.)
295
296   * `force = true`: Always uses the alternative filename.
297
298 `[oot]`: Out-of-tree build support
299 ----------------------------------
300
301   * `dir`: The build directory.  If relative, it is relative to the
302    parent of the invocation directory (and could be a symlink then).
303    Default is `Build` (assuming `use` is specified).
304
305    The build directory will contain one subdir for each package: each
306    subdir in the build dir corresponds to one source dir where
307    nailing-cargo was invoked.  nailing-cargo will arrange to create
308    these subdirectories, so the build directory can start out empty.
309
310   * `use`: How to become the build user.  Needs to be combined
311     with other setting(s):
312
313     * `ssh`: Use ssh.  `user` must be given as well and can be
314        a username on localhost, or the `<user>@<host>`
315        argument to ssh.
316
317     * `command_args`: `command` must be specified as a list,
318        specifying a command and arguments which work like `nice`.
319
320     * `command_sh`: `command` must be specified as a list,
321        specifying a command and arguments which work like `sh -c`.
322
323     * `null`: Run builds as the same user.
324
325     * `really`: Use `really` from `chiark-really.deb`.
326        `user` must be given as well.
327
328  * `command`: The command to run for `command_sh` or `command_args`.
329
330  * `user`: The local username for `really` and `ssh`, or
331    `<user>@<host>` for `ssh`.
332
333 Running the command
334 ===================
335
336 Normally you pass cargo as an argument to nailing-cargo.  But you
337 can also pass make or any other command.  You may need to pass
338 `--no-cargo-manifest-args` (aka `-M`) to nailing-cargo, to avoid
339 passing options like `--manifest-path` to make or whatever.
340
341 nailing-cargo passes these environment variables to the build command:
342
343   * `NAILINGCARGO_WORKSPHERE`: invocation `..` (parent)
344   * `NAILINGCARGO_MANIFEST_DIR`: invocation `.` (invocation directory)
345   * `NAILINGCARGO_BUILD_DIR`: build directory (even if same as source)
346   * `NAILINGCARGO_BUILDSPHERE`: only set if out of tree: parent of build dir.
347
348 All of these are absolute paths.
349
350 Limitations and bugs
351 ====================
352
353   * nailing-cargo temporarily dirties your source trees, including
354     particularly `Cargo.toml` and `Cargo.lock`; and if nailing-cargo
355     crashes or is interrupted these changes may be left behind.
356     Unfortunately it is not possible to avoid this temporary dirtying
357     because the cargo team have deliberately made cargo inflexible -
358     [issue#6715](https://github.com/rust-lang/cargo/issues/6715).  
359     At least, running nailing-cargo again will clean up any mess
360     left by an interrupted run.
361
362   * Out of tree builds require a unified filesystem view: eg, different
363     users on the same host, NFS, or something.
364
365     Specifically, the invocation and build execution environments must
366     both have visibility of the source and build directories, at the
367     same absolute pathnames.  The invocation environment must be able
368     to write to the build environment (but vice versa is not
369     required).
370
371     This could be improved.
372
373   * The alternative `Cargo.lock` filename must currently be a leafname.  I
374     think fixing this just involves review to check other values work
375     properly.
376
377   * The alternative `Cargo.lock` file must be on the same filesystem
378     as the source tree.  This is not so easy to fix; we would want the
379     existing algorithm but a fallback for the different-filsystem case.
380
381   * `Cargo.nail` is unconditionally looked for in the parent directory.
382     Ideally this should be configurable, and also perhaps be able to
383     combine multiple `Cargo.nail` files?  Relatedly, although
384     nailing-cargo can read multiple config files, it can only handle
385     one file specifying directories and packages.
386
387   * nailing-cargo uses a single lockfile alongside your `Cargo.nail`,
388     rather than a more sophisticated scheme involving locking
389     particular directories.  This means that if you run multiple
390     copies of nailing-cargo at once, in different directories, but
391     with `Cargo.nail` files which imply overlapping sets of package
392     directories, things will go Badly Wrong.
393
394 Contributing and legal
395 ======================
396
397 nailing-cargo is Free Software.
398
399 Please help improve it.  Contributions (to address the limitations, or
400 to add new facilities to help work with cargo) are welcome by email to
401 `ijackson@chiark.greenend.org.uk` or via the [Salsa
402 project](https://salsa.debian.org/iwj/nailing-cargo).
403
404 If you plan to do substantial work, please do get in touch with a
405 sketch of your proposed changes.
406
407 Legal
408 -----
409
410 This project accepts contributions based on the git commit
411 Signed-off-by convention, by which the contributors certify their
412 contributions according to the Developer Certificate of Origin version
413 1.1 - see the file DEVELOPER-CERTIFICATE.
414
415 Copyright (C) 2019-2020 Ian Jackson and others
416
417 This program is free software: you can redistribute it and/or modify
418 it under the terms of the GNU Affero General Public License as
419 published by the Free Software Foundation, either version 3 of the
420 License, or (at your option) any later version.
421
422 This program is distributed in the hope that it will be useful,
423 but WITHOUT ANY WARRANTY; without even the implied warranty of
424 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
425 GNU Affero General Public License for more details.
426
427 You should have received a copy of the GNU Affero General Public License
428 along with this program.  If not, see <http://www.gnu.org/licenses/>.
429
430 Individual files generally contain the following tag in the copyright
431 notice, instead of the full licence grant text:
432 ```
433    SPDX-License-Identifier: AGPL-3.0-or-later
434 ```
435 As is conventional, this should be read as a licence grant.