From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Sat, 20 Jun 2020 22:02:56 +0000 (+0100)
Subject: README.md: wip new argument parsing control spec
X-Git-Tag: nailing-cargo/1.0.0~128
X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=4576b05ff7b772ec79cd04251f95f3cac89398cf;p=nailing-cargo.git

README.md: wip new argument parsing control spec

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
---

diff --git a/README.md b/README.md
index 517dcc9..7351b9e 100644
--- a/README.md
+++ b/README.md
@@ -252,20 +252,39 @@ Options
   * `-n`: "No action": stop after writing `Cargo.toml.nailing~`
        everywhere, and do not run any build command.
 
-  * `-A<arch>` | `--arch=<arch>` | `--target=<arch>`
+  * `-T<arch>` | `--target=<arch>`
 
        Specify target architecture.
 
-       This option translates to a `--target=<arch>` option to the
-       ultimate command, unless that is a cargo subcommand which we
-       know would reject it.  `--arch` and `--target` are simply
-       aliases.
+       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
@@ -278,24 +297,33 @@ Options
 
        This makes no sense with in-tree builds.
 
-       Default is no update unless the ultimate command is a
-       cargo subcommand which we know needs it.
+       Default is no update unless the cargo subcommand will want it.
 
-  * `-m` | `--cargo-manifest-args` | `-M` | `--no-cargo-manifest-args`
+  * `--cargo-args=<ena><opt>[,<ena><opt>...]`
 
-       Controls whether we add cargo command line options, relating to
-       finding `Cargo.toml`, to the command to run.
+       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>`.
 
-       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.
+       `<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 arguments added are
+       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`.
 
-           --manifest-path=<path/to/Cargo.toml>
-           --locked
-           --target-dir=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`
 
@@ -312,6 +340,26 @@ Options
        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
 --------------------------------