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 `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
  84
  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.
  92
  93 Out-of-tree builds
  94 ==================
  95
  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.
 101
 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.
 105
 106 How nailing-cargo helps with out-of-tree builds
 107 -----------------------------------------------
 108
 109 nailing-cargo (configured appropriately) copies files back and forth
 110 to between the source and build directories, and runs cargo as your
 111 build user.
 112
 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`.
 117
 118 Configuring out-of-tree builds
 119 ------------------------------
 120
 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`.
 124
 125 The primary config keys here are:
 126
 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).
 130
 131   * `use`: How to become the build user.  Needs to be combined
 132     with other setting(s):
 133
 134     * `ssh`: Use ssh.  `user` must be given as well and can be
 135        a username on localhost, or the `<user>@<host>`
 136        argument to ssh.
 137
 138     * `command_args`: `command` must be specified as a list,
 139        specifying a command and arguments which work like `nice`.
 140
 141     * `command_sh`: `command` must be specified as a list,
 142        specifying a command and arguments which work like `sh -c`.
 143
 144     * `null`: Run builds as the same user.
 145
 146     * `really`: Use `really` from `chiark-really.deb`.
 147        `user` must be given as well.
 148
 149 Target architecture convenience aliases
 150 =======================================
 151
 152 If you are cross-building you may need to tell cargo `--target=`.
 153 The architecture names are quite long and inconvenient.
 154
 155 A simple shell alias would help a lot, except that cargo rejects
 156 `--target=` when it thinks it's not needed.
 157
 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.
 162
 163 Default change to offline mode
 164 ==============================
 165
 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
 168 cargo.
 169
 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.
 173
 174 Command-line options
 175 ====================
 176
 177   * `-v`: Increase verbosity.  Default is 1.
 178
 179   * `-q`: Set verbosity to 0.
 180
 181   * `-D`: Increase amount of debugging dump.
 182
 183   * `-n`: "No action": stop after writing `Cargo.toml.nailing~`
 184        everywhere, and do not run any build command.
 185
 186   * `-A<arch>` | `--arch=<arch>` | `--target=<arch>`
 187
 188        Specify target architecture.
 189
 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
 193        aliases.
 194
 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'`.
 199
 200   * `-u` | `--cargo-lock-update` | `-U` | `--no-cargo-lock-update`
 201
 202        Enables, or disables, the dance to allow `Cargo.lock` (or
 203        alternative) to be updated in the source directory.
 204
 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.
 209
 210        This makes no sense with in-tree builds.
 211
 212        Default is no update unless the ultimate command is a
 213        cargo subcommand which we know needs it.
 214
 215   * `-m` | `--cargo-manifest-args` | `-M` | `--no-cargo-manifest-args`
 216
 217        Controls whether we add cargo command line options, relating to
 218        finding `Cargo.toml`, to the command to run.
 219
 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.
 224
 225        The arguments added are
 226
 227            --manifest-path=<path/to/Cargo.toml>
 228            --locked
 229            --target-dir=target
 230
 231   * `-T` | `--no-cargo-target-dir-arg` | `-t` | `--cargo-target-dir-arg`
 232
 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`.
 238
 239   * `-o` | `--online` | `-O` | `--offline`
 240
 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`).
 245
 246 Configuration
 247 =============
 248
 249 nailing-cargo reads these configuration files:
 250 ```
 251     /etc/nailing-cargo/cfg.toml
 252     ~/.nailing-cargo.toml
 253     ./.nailing-cargo.toml
 254     ../Nailing-Cargo.toml
 255     ../Cargo.nail
 256 ```
 257 Settings in later-mentioned files override ones in earlier-mentioned
 258 files.
 259
 260 Note that unlike everything else, `packages` and `subdirs` are read
 261 only from `Cargo.nail` (see "Limitations and bugs", below).
 262
 263 Alternative `Cargo.lock` filename
 264 ---------------------------------
 265
 266 To control use of alternative `Cargo.lock` filename, use the section
 267 `[alt_cargolock]`.  Settings here:
 268
 269   * `file = <some leafname>`.
 270
 271   * `file = true`: Equivalent to `file = "Cargo.lock.example"`.
 272     (This is the default.)
 273
 274   * `file = false`: Disables this feature.
 275
 276   * `force = false`: Uses the alternative filename only if it
 277      already exists.  (This is the default.)
 278
 279   * `force = true`: Always uses the alternative filename.
 280
 281 Running the command
 282 ===================
 283
 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.
 288
 289 nailing-cargo passes these environment variables to the build command:
 290
 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.
 295
 296 All of these are absolute paths.
 297
 298 Limitations and bugs
 299 ====================
 300
 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.
 309
 310   * Out of tree builds require a unified filesystem view: eg, different
 311     users on the same host, NFS, or something.
 312
 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
 317     required).
 318
 319     This could be improved.
 320
 321   * The alternative `Cargo.lock` filename must currently be a leafname.  I
 322     think fixing this just involves review to check other values work
 323     properly.
 324
 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.
 328
 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.
 334
 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.
 341
 342 Contributing and legal
 343 ======================
 344
 345 nailing-cargo is Free Software.
 346
 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).
 351
 352 If you plan to do substantial work, please do get in touch with a
 353 sketch of your proposed changes.
 354
 355 Legal
 356 -----
 357
 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.
 362
 363 Copyright (C) 2019-2020 Ian Jackson and others
 364
 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.
 369
 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.
 374
 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/>.
 377
 378 Individual files generally contain the following tag in the copyright
 379 notice, instead of the full licence grant text:
 380 ```
 381    SPDX-License-Identifier: AGPL-3.0-or-later
 382 ```
 383 As is conventional, this should be read as a licence grant.