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 value depends on the configuration and the
 225        cargo subcommand - see `[misc]` `online` in "Configuration".
 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
 245 `subdirs`) are read only from `Cargo.nail` (see "Limitations and
 246 bugs", below).
 247
 248 These keys specify a combination of (i) a mapping from package name to
 249 source subdirectory (ii) a set of subdirectories whose `Cargo.toml`
 250 must be massaged.
 251
 252   * `packages`: a map keyed by package name, giving the subdirectory
 253     for each one.
 254
 255     This causes each mentioned subdirectory's `Cargo.toml` to be
 256     massaged, and records that subdirectory as the source for that
 257     package.  (nailing-cargo will check that subdirectory actually
 258     contains the indicated package.)
 259
 260     Each value can be just the subdirectory name (eg `[packages]`
 261     `mylibrary='mylibrary-test'`) or itself a map with the key `subdir`
 262     (eg `[packages.mylibrary]` `subdir='mylibrary-test'`).
 263
 264   * `subdirs`: a list of subdirectory names to process.
 265
 266     Each subdirectory's `Cargo.toml` will be massaged.  Also, the
 267     subdirectory will be examined to see what package it contains; it
 268     will then be used as the source for that package, unless that
 269     package appears in an entry in `packages`, or an earlier entry in
 270     `subdirs`.
 271
 272     This can be a list of strings (eg `subdirs =
 273     ['myproject','mylibrary']`).  Or it can be single multi-line
 274     string containing one subdirectory name per line; in that
 275     case, `#`-comments are supported and tabs and spaces are ignored
 276     (see "Most basic example usage" above.)
 277
 278 In each case the subdirectory should usually be a relative pathname;
 279 it is relative to the directory containing `Cargo.nail`.
 280
 281 `[alt_cargolock]`: Alternative `Cargo.lock` filename
 282 ----------------------------------------------------
 283
 284 To control use of alternative `Cargo.lock` filename, use the section
 285 `[alt_cargolock]`.  Settings here:
 286
 287   * `file = <some leafname>`.
 288
 289   * `file = true`: Equivalent to `file = "Cargo.lock.example"`.
 290     (This is the default.)
 291
 292   * `file = false`: Disables this feature.
 293
 294   * `force = false`: Uses the alternative filename only if it
 295      already exists.  (This is the default.)
 296
 297   * `force = true`: Always uses the alternative filename.
 298
 299 `[oot]`: Out-of-tree build support
 300 ----------------------------------
 301
 302   * `dir`: The build directory.  If relative, it is relative to the
 303    parent of the invocation directory (and could be a symlink then).
 304    Default is `Build` (assuming `use` is specified).
 305
 306    The build directory will contain one subdir for each package: each
 307    subdir in the build dir corresponds to one source dir where
 308    nailing-cargo was invoked.  nailing-cargo will arrange to create
 309    these subdirectories, so the build directory can start out empty.
 310
 311   * `use`: How to become the build user.  Needs to be combined
 312     with other setting(s):
 313
 314     * `ssh`: Use ssh.  `user` must be given as well and can be
 315        a username on localhost, or the `<user>@<host>`
 316        argument to ssh.
 317
 318     * `command_args`: `command` must be specified as a list,
 319        specifying a command and arguments which work like `nice`.
 320
 321     * `command_sh`: `command` must be specified as a list,
 322        specifying a command and arguments which work like `sh -c`.
 323
 324     * `null`: Run builds as the same user.
 325
 326     * `really`: Use `really` from `chiark-really.deb`.
 327        `user` must be given as well.
 328
 329  * `command`: The command to run for `command_sh` or `command_args`.
 330
 331  * `user`: The local username for `really` and `ssh`, or
 332    `<user>@<host>` for `ssh`.
 333
 334 `[arch]`: Architecture convenience aliases
 335 ------------------------------------------
 336
 337 This is a map from archictecture aliases to full cargo architecture
 338 names.  The keys are the aliases; each entry should be a string, the
 339 cargo architecture name.
 340
 341 Only keys starting with an ascii uppercase letter are relevant, since
 342 other names are not looked up in this alias map.
 343
 344 `[misc]`: Miscellaneous individual nailing-cargo config
 345 -------------------------------------------------------
 346
 347  * `online`: boolean, specifying whether to pass `--offline` to cargo
 348    (cargo's default is online mode).  The default is offline, unless
 349    nailing-cargo can see that the cargo subcommand being invoked is
 350    one which requires online access (currently, `fetch`), in which
 351    case the default is online.
 352
 353 Running the command
 354 ===================
 355
 356 Normally you pass cargo as an argument to nailing-cargo.  But you
 357 can also pass make or any other command.  You may need to pass
 358 `--no-cargo-manifest-args` (aka `-M`) to nailing-cargo, to avoid
 359 passing options like `--manifest-path` to make or whatever.
 360
 361 nailing-cargo passes these environment variables to the build command:
 362
 363   * `NAILINGCARGO_WORKSPHERE`: invocation `..` (parent)
 364   * `NAILINGCARGO_MANIFEST_DIR`: invocation `.` (invocation directory)
 365   * `NAILINGCARGO_BUILD_DIR`: build directory (even if same as source)
 366   * `NAILINGCARGO_BUILDSPHERE`: only set if out of tree: parent of build dir.
 367
 368 All of these are absolute paths.
 369
 370 Limitations and bugs
 371 ====================
 372
 373   * nailing-cargo temporarily dirties your source trees, including
 374     particularly `Cargo.toml` and `Cargo.lock`; and if nailing-cargo
 375     crashes or is interrupted these changes may be left behind.
 376     Unfortunately it is not possible to avoid this temporary dirtying
 377     because the cargo team have deliberately made cargo inflexible -
 378     [issue#6715](https://github.com/rust-lang/cargo/issues/6715).
 379     At least, running nailing-cargo again will clean up any mess
 380     left by an interrupted run.
 381
 382   * Out of tree builds require a unified filesystem view: eg, different
 383     users on the same host, NFS, or something.
 384
 385     Specifically, the invocation and build execution environments must
 386     both have visibility of the source and build directories, at the
 387     same absolute pathnames.  The invocation environment must be able
 388     to write to the build environment (but vice versa is not
 389     required).
 390
 391     This could be improved.
 392
 393   * The alternative `Cargo.lock` filename must currently be a leafname.  I
 394     think fixing this just involves review to check other values work
 395     properly.
 396
 397   * The alternative `Cargo.lock` file must be on the same filesystem
 398     as the source tree.  This is not so easy to fix; we would want the
 399     existing algorithm but a fallback for the different-filsystem case.
 400
 401   * `Cargo.nail` is unconditionally looked for in the parent directory.
 402     Ideally this should be configurable, and also perhaps be able to
 403     combine multiple `Cargo.nail` files?  Relatedly, although
 404     nailing-cargo can read multiple config files, it can only handle
 405     one file specifying directories and packages.
 406
 407   * nailing-cargo uses a single lockfile alongside your `Cargo.nail`,
 408     rather than a more sophisticated scheme involving locking
 409     particular directories.  This means that if you run multiple
 410     copies of nailing-cargo at once, in different directories, but
 411     with `Cargo.nail` files which imply overlapping sets of package
 412     directories, things will go Badly Wrong.
 413
 414 Contributing and legal
 415 ======================
 416
 417 nailing-cargo is Free Software.
 418
 419 Please help improve it.  Contributions (to address the limitations, or
 420 to add new facilities to help work with cargo) are welcome by email to
 421 `ijackson@chiark.greenend.org.uk` or via the [Salsa
 422 project](https://salsa.debian.org/iwj/nailing-cargo).
 423
 424 If you plan to do substantial work, please do get in touch with a
 425 sketch of your proposed changes.
 426
 427 Legal
 428 -----
 429
 430 This project accepts contributions based on the git commit
 431 Signed-off-by convention, by which the contributors certify their
 432 contributions according to the Developer Certificate of Origin version
 433 1.1 - see the file DEVELOPER-CERTIFICATE.
 434
 435 Copyright (C) 2019-2020 Ian Jackson and others
 436
 437 This program is free software: you can redistribute it and/or modify
 438 it under the terms of the GNU Affero General Public License as
 439 published by the Free Software Foundation, either version 3 of the
 440 License, or (at your option) any later version.
 441
 442 This program is distributed in the hope that it will be useful,
 443 but WITHOUT ANY WARRANTY; without even the implied warranty of
 444 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 445 GNU Affero General Public License for more details.
 446
 447 You should have received a copy of the GNU Affero General Public License
 448 along with this program.  If not, see <http://www.gnu.org/licenses/>.
 449
 450 Individual files generally contain the following tag in the copyright
 451 notice, instead of the full licence grant text:
 452 ```
 453    SPDX-License-Identifier: AGPL-3.0-or-later
 454 ```
 455 As is conventional, this should be read as a licence grant.