README.md: wip new argument parsing control spec

[nailing-cargo.git] / README.md

nailing-cargo
=============

This is a wrapper tool for cargo, the Rust build tool and package
manager.  Functions:

 * Conveniently use local crates, including completely
   unpublished crates.

 * Perform out-of-tree builds, including in an account with
   no write access to the source tree.

 * Provide convenience aliases for target architecture names.

 * Make the default be offline (ie, not to access the internet)

These functions are of course configurable.

The primary source of information for nailing-cargo is the file
`../Cargo.nail` (which is in TOML syntax).  You put `Cargo.nail`
alongside the top-level git repositories you are working with, and
invoke nailing-cargo from the git directory containing the Rust
package you want to build.

Installing
----------

nailing-cargo is designed to be run out of a git clone:

```
$ git clone https://salsa.debian.org/iwj/nailing-cargo.git
$ ln -s `pwd`/nailing-cargo/nailing-cargo ~/bin
```

It is self-contained, depending only on a reasonably functional Perl
installation.

Most basic example usage
------------------------

```
$ cd myproject
$ cat >../Cargo.nail
subdirs="""
myproject
mylibrary
"""
$ nailing-cargo generate-lockfile
$ nailing-cargo build
```

Documentation table of contents
-------------------------------

<!-- TOC autogenerated by ./markdown-toc-filter, do not edit -->

  * [Introduction](#nailing-cargo)
    * [Installing](#installing)
    * [Most basic example usage](#most-basic-example-usage)
    * [Documentation table of contents](#documentation-table-of-contents)
  * [Using local crates, or locally modified crates](#using-local-crates-or-locally-modified-crates)
    * [How nailing-cargo helps with using local crates](#how-nailing-cargo-helps-with-using-local-crates)
    * [Telling nailing-cargo how to massage `Cargo.toml`](#telling-nailing-cargo-how-to-massage-cargo.toml)
  * [Out-of-tree builds](#out-of-tree-builds)
    * [How nailing-cargo helps with out-of-tree builds](#how-nailing-cargo-helps-with-out-of-tree-builds)
    * [Configuring out-of-tree builds](#configuring-out-of-tree-builds)
  * [Target architecture convenience aliases](#target-architecture-convenience-aliases)
  * [Default change to offline mode](#default-change-to-offline-mode)
  * [Invocation and command-line option reference](#invocation-and-command-line-option-reference)
    * [Usages](#usages)
    * [Options](#options)
    * [Environment of the build command](#environment-of-the-build-command)
  * [Configuration reference](#configuration-reference)
    * [Source directories and packages (toplevel)](#source-directories-and-packages-toplevel)
    * [`[alt_cargolock]`: Alternative `Cargo.lock` filename](#alt_cargolock-alternative-cargo.lock-filename)
    * [`[oot]`: Out-of-tree build support](#oot-out-of-tree-build-support)
    * [`[arch]`: Architecture convenience aliases](#arch-architecture-convenience-aliases)
    * [`[misc]`: Miscellaneous individual nailing-cargo config](#misc-miscellaneous-individual-nailing-cargo-config)
  * [Limitations and bugs](#limitations-and-bugs)
  * [Contributing and legal](#contributing-and-legal)
    * [Legal](#legal)

Using local crates, or locally modified crates
==============================================

cargo does not work well with local crates,
especially completely unpublished ones.
(See [issue#6713](https://github.com/rust-lang/cargo/issues/6713),
[stackoverflow](https://stackoverflow.com/questions/33025887/how-to-use-a-local-unpublished-crate),
[issue#1481](https://github.com/rust-lang/cargo/issues/1481),
[my blog](https://diziet.dreamwidth.org/1805.html).)

Using a local version of a crate should be possible without putting
paths into your `Cargo.toml` and without editing complex
configuration.

How nailing-cargo helps with using local crates
-----------------------------------------------

nailing-cargo temporarily edits all the `Cargo.toml` files in all the
subdirectories you mention, to refer to each other; then it runs
cargo; and then it puts everything back.

Telling nailing-cargo how to massage `Cargo.toml`
-------------------------------------------------

To find the subdirectories, and the packages, it looks for `subdirs`
and `packages` in `Cargo.nail`.

For straightforward use, write `subdirs` as a multi-line string
containing a list of subdirectory names one per line.  In each of
these directories `Cargo.toml` will be massaged, and the package there
will be used for other massaged `Cargo.toml`s.

See "Configuration reference", below, for full details.

Out-of-tree builds
==================

It is often desirable to run builds in a way that does not write to
the source tree.  cargo's enthusiastic approach to the dependency
management task means that it is a good idea to try to insulate your
main working environment from the many things cargo has decided to
download and execute.

However, when you tell cargo to do an out of tree build (using
`--manifest-path`) it will insist on `Cargo.lock` being in the source
directory, and often will insist on writing to it.

How nailing-cargo helps with out-of-tree builds
-----------------------------------------------

nailing-cargo (configured appropriately) copies files back and forth
to between the source and build directories, and runs cargo as your
build user.

The `Cargo.lock` must still be saved in your source tree somewhere.
nailing-cargo arranges this for you.  You can either put this file in
`.gitignore`; or commit it to git; or you can tell nailing-cargo to
save it as something like `Cargo.lock.example`.

Configuring out-of-tree builds
------------------------------

To enable out-of-tree-builds, put an `[oot]` section in your
`Cargo.nail` or one of nailing-cargo's other config files.
In that section, specify at least `use`.

Also, specify `dir`, or create a symlink `Build` next to `Cargo.nail`,
pointing to to your build area.

For example,
```
[oot]
use='ssh'
user='rustcargo'
```
will have nailing-cargo run `ssh rustcargo@localhost` to
run build commands.

Target architecture convenience aliases
=======================================

If you are cross-building you may need to tell cargo `--target=`.
The architecture names are quite long and inconvenient.

A simple shell alias would help a lot, except that cargo rejects
`--target=` when it thinks it's not needed.

In your nailing-cargo config, you can write something like
`arch.RPI='arm-unknown-linux-gnueabihf'`.  Then `nailing-cargo -ARPI`
will DTRT.  In fact, you do not even need to specify that particular
arch alias, since it is built-in to nailing-cargo.

Default change to offline mode
==============================

It seems to me that build tools should be explicit about their use of
the network.  So by default, nailing-cargo passes `--offline` to
cargo.

If you disagree with my opinion, write `misc.online=true` in your
nailing-cargo configuration.  `misc.online=false`, and command line
options, are also available, for overriding.

Invocation and command-line option reference
============================================

Usages
------

```
1$ nailing-cargo <nailing-opts> <cargo-opts> [--] <subcmd>...
2$ nailing-cargo <nailing-opts> --- <cargo> <cargo-opts> [--] <subcmd>...
3$ nailing-cargo <nailing-opts> --- [--] <build-command>...
```
Ususally the `--` is not needed.  (It should generally be passed by
programs which wrap nailing-cargo.  See below.)

In usage 1, nailing-cargo runs `cargo` (from `PATH`).  In the usage 2
nailing-cargo runs `<cargo>`.  In both these cases it adds its own
options to control cargo's behaviour.  In both of these cases
nailing-cargo looks at `<subcmd>` to determine the cargo subcommand
being run: this controls various defaults, to try to do the right
things.

In the third syntax, nailing-cargo runs `<build-command>...` without
additional arguments and does not attempt to identify the cargo
subcommand(s) that it will run.  Possibly it will be necessary to pass
`--online` or `--cargo-lock-update`, or even `--cargo-*arg*`

### Invocation argument disambiguation rules ###

For authors of tools which call nailing-cargo (and pedants):

The usages overlap in syntax!  nailing-cargo follows the following
rules when interpreting its command line:

   * The first option not recognised as a nailing-cargo option is
     treated as the start of the `<cargo-opts>`.

   * `<cargo-opts>` are terminated by `--` (which is removed) or the
     first argument which does not start with a `-`.

     (It is not possible to get nailing-cargo to pass the value `--`
     as a separate argument to a cargo global option, but cargo global
     options can typically take the values cuddled with `=`, so doing
     that is not necessary.)

   * After `---`, nailing-cargo will search for a `--`, to the end of
     the arguments if necessary.  The position of the `--` determines
     whether this is usage 2 or usage 3, and what `<subcmd>` is.

     If the arguments after `nailing-cargo ... ---` might contain `--`
     anywhere, an explicit `--` should be passed.

   * If no `--` appears after `---`, the word after `---` is the
     command to run; if its final pathname component contains the
     string `cargo`, it is treated as `<cargo>` (implying usage 2 and
     the search for `<subcmd>`).  Otherwise it is treated as
     `<build-command>` (usage 3).

Options
-------

  * `-v`: Increase verbosity.  Default is 1.

  * `-q`: Set verbosity to 0.

  * `-D`: Increase amount of debugging dump.

  * `-n`: "No action": stop after writing `Cargo.toml.nailing~`
       everywhere, and do not run any build command.

  * `-T<arch>` | `--target=<arch>`

       Specify target architecture.

       This option translates to a `--target=<arch>` option to cargo
       (when the subcommand accepts it).

       If `<arch>` starts with a capital ascii letter, it is an alias
       for some other arch: it is looked up in the configuration, and
       then in the builtin arch alias list.  The builtin list is
       equivalent to: `[arch]` `RPI='arm-unknown-linux-gnueabihf'`.

  * `-c<subcommand>`

       Behave as if the build command were `cargo <subcommand>`.

       This influences the logic which tries to determine which
       options to pass to cargo, whether cargo needs to be online, and
       whether cargo might want to update `Cargo.lock`.

       But this option does not affect which build command (and which
       cargo subcommand) is actually run.

  * `-C`

       Behave as if the build command will not run cargo.

       This suppresses the addition of cargo command line options and
       makes nailing-cargo assumes that the build command will not
       need to update `Cargo.lock`.
       But this option does not affect which build command is actually
       run.

  * `-u` | `--cargo-lock-update` | `-U` | `--no-cargo-lock-update`

       Enables, or disables, the dance to allow `Cargo.lock` (or
       alternative) to be updated in the source directory.

       With this dance enabled the `Cargo.lock` and `Cargo.toml` are
       copied to the build directory along with a skeleton just big
       enough to fool cargo.  After cargo has run, the resulting
       `Cargo.lock` is copied back to the source tree.

       This makes no sense with in-tree builds.

       Default is no update unless the cargo subcommand will want it.

  * `--cargo-args=<ena><opt>[,<ena><opt>...]`

       Overrides the logic for choosing which cargo options should be
       passed to the build command.
       The value is a comma-separated list of `<ena><opt>`.

       `<opt>` is one of the arguments that nailing-cargo might pass
       to cargo: `manifest-path`, `locked`, `target-dir`, `offline`,
       `arch`.
       (Note these must be specified
       without the leading `--` and without any value.)  `<opt>` may
       also be `all` in which case the setting for all options is
       changed.

       The specs (maybe multiple `--cargo-args` options) are
       cumulative and are processed in order.  These options override
       `-c`, `-C`.  They can also effectively override other options
       to nailing-cargo, such as `--offline` or `--target`.

       `<ena>` is one of:

    * `@`: Decide automatically for this option (default).
    * `+`: Definitely pass this option
    * `-`: Definitely do not pass this option
    * `_`: Definitely do not pass this option - and do not mind if `<opt>` is not known to nailing-cargo.

  * `-T` | `--no-cargo-target-dir-arg` | `-t` | `--cargo-target-dir-arg`

       `-T` suppresses `--target-dir`; `-t` un-suppresses it.  Only
       makes any difference with `-m`, since otherwise no
       `--target-dir` would be passed anyway.  Additionally this is
       done automatically when nailing-cargo sees that the cargo
       subcommand is one which needs it, eg `fetch`.

  * `-o` | `--online` | `-O` | `--offline`

       Whether to allow cargo to make network access.  nailing-cargo
       always passes `--offline` to cargo, unless `--online` is in
       force.  The default value depends on the configuration and the
       cargo subcommand - see `[misc]` `online` in "Configuration".

Arguments to the build command
------------------------------

xxx
  * `-m` | `--cargo-manifest-args` | `-M` | `--no-cargo-manifest-args`

       Controls whether we add cargo command line options, relating to
       finding `Cargo.toml`, to the command to run.

       Default is to add them if we are doing an out-of-tree build,
       unless we are doing the dance to update the `Cargo.lock` (see
       above) since in that case all the relevant files can be found
       by cargo in the build directory.

       The arguments added are

           --manifest-path=<path/to/Cargo.toml>
           --locked
           --target-dir=target

Environment of the build command
--------------------------------

nailing-cargo passes these environment variables to the build command:

  * `NAILINGCARGO_WORKSPHERE`: invocation `..` (parent)
  * `NAILINGCARGO_MANIFEST_DIR`: invocation `.` (invocation directory)
  * `NAILINGCARGO_BUILD_DIR`: build directory (even if same as source)
  * `NAILINGCARGO_BUILDSPHERE`: only set if out of tree: parent of build dir.

All of these are absolute paths.

Configuration reference
=======================

nailing-cargo reads these configuration files:
```
    /etc/nailing-cargo/cfg.toml
    ~/.nailing-cargo.toml
    ./.nailing-cargo.toml
    ../Nailing-Cargo.toml
    ../Cargo.nail
```
Settings in later-mentioned files override ones in earlier-mentioned
files.

Source directories and packages (toplevel)
------------------------------------------

Note that unlike everything else, these keys (`packages` and
`subdirs`) are read only from `Cargo.nail` (see "Limitations and
bugs", below).

These keys specify a combination of (i) a mapping from package name to
source subdirectory (ii) a set of subdirectories whose `Cargo.toml`
must be massaged.

  * `packages`: a map keyed by package name, giving the subdirectory
    for each one.

    This causes each mentioned subdirectory's `Cargo.toml` to be
    massaged, and records that subdirectory as the source for that
    package.  (nailing-cargo will check that subdirectory actually
    contains the indicated package.)

    Each value can be just the subdirectory name (eg `[packages]`
    `mylibrary='mylibrary-test'`) or itself a map with the key `subdir`
    (eg `[packages.mylibrary]` `subdir='mylibrary-test'`).

  * `subdirs`: a list of subdirectory names to process.

    Each subdirectory's `Cargo.toml` will be massaged.  Also, the
    subdirectory will be examined to see what package it contains; it
    will then be used as the source for that package, unless that
    package appears in an entry in `packages`, or an earlier entry in
    `subdirs`.

    This can be a list of strings (eg `subdirs =
    ['myproject','mylibrary']`).  Or it can be single multi-line
    string containing one subdirectory name per line; in that
    case, `#`-comments are supported and tabs and spaces are ignored
    (see "Most basic example usage" above.)

In each case the subdirectory should usually be a relative pathname;
it is relative to the directory containing `Cargo.nail`.

`[alt_cargolock]`: Alternative `Cargo.lock` filename
----------------------------------------------------

To control use of alternative `Cargo.lock` filename, use the section
`[alt_cargolock]`.  Settings here:

  * `file = <some leafname>`.

  * `file = true`: Equivalent to `file = "Cargo.lock.example"`.
    (This is the default.)

  * `file = false`: Disables this feature.

  * `force = false`: Uses the alternative filename only if it
     already exists.  (This is the default.)

  * `force = true`: Always uses the alternative filename.

`[oot]`: Out-of-tree build support
----------------------------------

  * `dir`: The build directory.  If relative, it is relative to the
   parent of the invocation directory (and could be a symlink then).
   Default is `Build` (assuming `use` is specified).

   The build directory will contain one subdir for each package: each
   subdir in the build dir corresponds to one source dir where
   nailing-cargo was invoked.  nailing-cargo will arrange to create
   these subdirectories, so the build directory can start out empty.

  * `use`: How to become the build user.  Needs to be combined
    with other setting(s):

    * `ssh`: Use ssh.  `user` must be given as well and can be
       a username on localhost, or the `<user>@<host>`
       argument to ssh.

    * `command_args`: `command` must be specified as a list,
       specifying a command and arguments which work like `nice`.

    * `command_sh`: `command` must be specified as a list,
       specifying a command and arguments which work like `sh -c`.

    * `null`: Run builds as the same user.

    * `really`: Use `really` from `chiark-really.deb`.
       `user` must be given as well.

    * `disable': Disable this feature, even if `dir` is set.

 * `command`: The command to run for `command_sh` or `command_args`.

 * `user`: The local username for `really` and `ssh`, or
   `<user>@<host>` for `ssh`.

`[arch]`: Architecture convenience aliases
------------------------------------------

This is a map from archictecture aliases to full cargo architecture
names.  The keys are the aliases; each entry should be a string, the
cargo architecture name.

Only keys starting with an ascii uppercase letter are relevant, since
other names are not looked up in this alias map.

`[misc]`: Miscellaneous individual nailing-cargo config
-------------------------------------------------------

 * `online`: boolean, specifying whether to pass `--offline` to cargo
   (cargo's default is online mode).  The default is offline, unless
   nailing-cargo can see that the cargo subcommand being invoked is
   one which requires online access (currently, `fetch`), in which
   case the default is online.

Limitations and bugs
====================

  * nailing-cargo temporarily dirties your source trees, including
    particularly `Cargo.toml` and `Cargo.lock`; and if nailing-cargo
    crashes or is interrupted these changes may be left behind.
    Unfortunately it is not possible to avoid this temporary dirtying
    because the cargo team have deliberately made cargo inflexible -
    [issue#6715](https://github.com/rust-lang/cargo/issues/6715).  
    At least, running nailing-cargo again will clean up any mess
    left by an interrupted run.

  * Out of tree builds require a unified filesystem view: eg, different
    users on the same host, NFS, or something.

    Specifically, the invocation and build execution environments must
    both have visibility of the source and build directories, at the
    same absolute pathnames.  The invocation environment must be able
    to write to the build environment (but vice versa is not
    required).

    This could be improved.

  * The alternative `Cargo.lock` filename must currently be a leafname.  I
    think fixing this just involves review to check other values work
    properly.

  * The alternative `Cargo.lock` file must be on the same filesystem
    as the source tree.  This is not so easy to fix; we would want the
    existing algorithm but a fallback for the different-filsystem case.

  * `Cargo.nail` is unconditionally looked for in the parent directory.
    Ideally this should be configurable, and also perhaps be able to
    combine multiple `Cargo.nail` files?  Relatedly, although
    nailing-cargo can read multiple config files, it can only handle
    one file specifying directories and packages.

  * nailing-cargo uses a single lockfile alongside your `Cargo.nail`,
    rather than a more sophisticated scheme involving locking
    particular directories.  This means that if you run multiple
    copies of nailing-cargo at once, in different directories, but
    with `Cargo.nail` files which imply overlapping sets of package
    directories, things will go Badly Wrong.

Contributing and legal
======================

nailing-cargo is Free Software.

Please help improve it.  Contributions (to address the limitations, or
to add new facilities to help work with cargo) are welcome by email to
`ijackson@chiark.greenend.org.uk` or via the [Salsa
project](https://salsa.debian.org/iwj/nailing-cargo).

If you plan to do substantial work, please do get in touch with a
sketch of your proposed changes.

Legal
-----

This project accepts contributions based on the git commit
Signed-off-by convention, by which the contributors certify their
contributions according to the Developer Certificate of Origin version
1.1 - see the file DEVELOPER-CERTIFICATE.

Copyright (C) 2019-2020 Ian Jackson and others

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

Individual files generally contain the following tag in the copyright
notice, instead of the full licence grant text:
```
   SPDX-License-Identifier: AGPL-3.0-or-later
```
As is conventional, this should be read as a licence grant.