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  * Makes 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).  The `subdir` values are also added to the list
  91 of directories 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 is
 135        the `<user>@<host>` argument to ssh.
 136
 137     * `command_args`: `command` must be specified as a list,
 138        specifying a command and arguments which work like `nice`.
 139
 140     * `command_sh`: `command` must be specified as a list,
 141        specifying a command and arguments which work like `sh -c`.
 142
 143     * `null`: Run builds as the same user.
 144
 145     * `really`: Use `really` from `chiark-really.deb`.
 146        `user` must be given as well.
 147
 148 Target architecture convenience aliases
 149 =======================================
 150
 151 If you are cross-building you may need to tell cargo `--target=`.
 152 The architecture names are quite long and inconvenient.
 153
 154 A simple shell alias would help a lot, except that cargo rejects
 155 `--target=` when it thinks it's not needed.
 156
 157 In your nailing-cargo config, you can write something 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.
 161
 162 Default change to offline mode
 163 ==============================
 164
 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
 167 cargo.
 168
 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.
 172
 173 Command-line options
 174 ====================
 175
 176   * `-v`: Increase verbosity.  Default is 1.
 177
 178   * `-q`: Set verbosity to 0.
 179
 180   * `-D`: Increase amount of debugging dump.
 181
 182   * `-n`: "No action": stop after writing Cargo.toml.nailing~
 183        everywhere, and do not run any build command.
 184
 185   * `-A<arch>` | `--arch=<arch>` | `--target=<arch>`
 186
 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'`.
 192
 193        This option translates to a --target= option to the ultimate
 194        command, unless that is a cargo subcommand which we know
 195        would reject it.  `--arch` and `--target` are simply aliases.
 196
 197   * `-u` | `--cargo-lock-update` | `-U` | `--no-cargo-lock-update`
 198
 199        Enables, or disables, the dance to allow Cargo.lock (or
 200        alternative) to be updated in the source directory.
 201
 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.
 206
 207        This makes no sense with in-tree builds.
 208
 209        Default is no update unless the ultimate command is a
 210        cargo subcommand which we know needs it.
 211
 212   * `-m` | `--cargo-manifest-args` | `-M` | `--no-cargo-manifest-args`
 213
 214        Controls whether we add cargo command line options relating to
 215        finding `Cargo.toml`, to the command to run.
 216
 217        Default is to add them if we are doing an out-of-tree build,
 218        unless we are doing the dance to update the `Cargo.lock` (see
 219        above) since in that case all the relevant files can be found
 220        by cargo in the build directory.
 221
 222        The arguments added are
 223
 224            --manifest-path=<path/to/Cargo.toml>
 225            --locked
 226            --target-dir=target
 227
 228   * `-T` | `--no-cargo-target-dir-arg` | `-t` | `--cargo-target-dir-arg`
 229
 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'.
 235
 236   * `-o` | `--online` | `--offline` | `-O`
 237
 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').
 242
 243 Configuration
 244 =============
 245
 246 nailing-cargo reads these configuration files:
 247 ```
 248     /etc/nailing-cargo/cfg.toml
 249     ~/.nailing-cargo.toml
 250     ./.nailing-cargo.toml
 251     ../Nailing-Cargo.toml
 252     ../Cargo.nail
 253 ```
 254 Settings in later-mentioned files override ones in earlier-mentioned
 255 files.
 256
 257 Note that unlike everything else, `packages` and `subdirs` are read
 258 only from `Cargo.nail` (see "Limitations and bugs", below).
 259
 260 Alternative `Cargo.lock` filename
 261 ---------------------------------
 262
 263 To control use of alternative Cargo.lock filename, use the section
 264 `[alt_cargolock]`.  Settings here:
 265
 266   * `file = false`: disables this feature
 267
 268   * `file = true`: equivalent to `file = "Cargo.lock.example"`
 269     (this is the default).
 270
 271   * `file = <some leafname>`
 272
 273   * `force = false`: Use the alternative file only if it
 274      already exists.  (This is the default.)
 275
 276   * `force = true`: Always uses the alternative filename.
 277
 278 Running the command
 279 ===================
 280
 281 Normally you pass `cargo` as an argument to `nailing-cargo`.  But you
 282 can also pass `make` or any other command.  You may need to pass
 283 `--no-cargo-manifest-args` (aka `-M`) to nailing-cargo, to avoid
 284 passing options like `--manifest-path` to `make` or whatever.
 285
 286 nailing-cargo passes these environment variables to the build command:
 287
 288   * `NAILINGCARGO_WORKSPHERE`: invocation `..` (parent)
 289   * `NAILINGCARGO_MANIFEST_DIR`: invocation `.` (invocation directory)
 290   * `NAILINGCARGO_BUILD_DIR`: build directory (even if same as source)
 291   * `NAILINGCARGO_BUILDSPHERE`: only set if out of tree: parent of build dir.
 292
 293 All of these are absolute paths.
 294
 295 Limitations and bugs
 296 ====================
 297
 298   * nailing-cargo temporarily dirties your source trees, including
 299     particularly `Cargo.toml` and `Cargo.lock`.  If nailing-cargo
 300     crashes or is interrupted these changes may be left behind;
 301     running nailing-cargo again should clean up such a mess.
 302     Unfortunately it is not possible to fix this bug because the cargo
 303     team have deliberately made cargo inflexible -
 304     [issue#6715](https://github.com/rust-lang/cargo/issues/6715).
 305
 306   * Out of tree builds require a unified filesystem view: eg, different
 307     users on the same host, NFS, or something.  This could be improved.
 308
 309     The alternative Cargo.lock filename must currently be a leafname.  I
 310     think fixing this just involves review to check other values work
 311     properly.
 312
 313   * The alternative Cargo.lock file must be on same filesystem.  This is
 314     not so easy to fix; we would want the existing algorithm but a
 315     fallback for this case.
 316
 317   * Cargo.nail is unconditionally looked for in the parent directory.
 318     Ideally this should be configurable, and also perhaps be able to
 319     combine multiple Cargo.nail files?  Relatedly, although
 320     nailing-cargo can read multiple config files, it can only handle
 321     one file specifying directories and packages.
 322
 323   * nailing-cargo uses a single lockfile alongside your `Cargo.nail`,
 324     rather than a more sophisticated scheme involving locking
 325     particular directories.  This means that if you run multiple
 326     copies of nailing-cargo at once, in different directories, but
 327     with `Cargo.nail` files which imply overlapping sets of package
 328     directories, things will go Badly Wrong.
 329
 330 Contributing and legal
 331 ======================
 332
 333 nailing-cargo is Free Software.
 334
 335 Please help improve it.  Contributions (to address the limitations, or
 336 to add new facilities to help work with cargo) are welcome by email to
 337 `ijackson@chiark.greenend.org.uk` or via the [Salsa
 338 project](https://salsa.debian.org/iwj/nailing-cargo).
 339
 340 If you plan to do substantial work, please do get in touch with a
 341 sketch of your proposed changes.
 342
 343 Legal
 344 -----
 345
 346 This project accepts contributions based on the git commit
 347 Signed-off-by convention, by which the contributors certify their
 348 contributions according to the Developer Certificate of Origin version
 349 1.1 - see the file DEVELOPER-CERTIFICATE.
 350
 351 Copyright (C) 2019-2020 Ian Jackson and others
 352
 353 This program is free software: you can redistribute it and/or modify
 354 it under the terms of the GNU Affero General Public License as
 355 published by the Free Software Foundation, either version 3 of the
 356 License, or (at your option) any later version.
 357
 358 This program is distributed in the hope that it will be useful,
 359 but WITHOUT ANY WARRANTY; without even the implied warranty of
 360 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 361 GNU Affero General Public License for more details.
 362
 363 You should have received a copy of the GNU Affero General Public License
 364 along with this program.  If not, see <http://www.gnu.org/licenses/>.
 365
 366 Individual files generally contain the following tag in the copyright
 367 notice, instead of the full licence grant text:
 368 ```
 369    SPDX-License-Identifier: AGPL-3.0-or-later
 370 ```
 371 As is conventional, this should be read as a licence grant.