README.md: Proposed invocation rework

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

diff --git a/README.md b/README.md
index 97ff6f1dd94f3efb0826af9b4f20afcb50624834..ac2857d45956cfdcf7415f2b61e2fcc8c53de55b 100644 (file)
--- a/README.md
+++ b/README.md
@@ -45,8 +45,8 @@ subdirs="""
 myproject
 mylibrary
 """
-$ nailing-cargo cargo generate-lockfile
-$ nailing-cargo cargo build
+$ nailing-cargo generate-lockfile
+$ nailing-cargo build
 ```
 
 Using local crates, or locally modified crates
@@ -81,7 +81,7 @@ 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", below, for the full reference.
+See "Configuration reference", below, for full details.
 
 Out-of-tree builds
 ==================
@@ -152,8 +152,65 @@ 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.
 
-Command-line options
-====================
+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):
+NB: 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.
 
@@ -224,8 +281,20 @@ Command-line options
        force.  The default value depends on the configuration and the
        cargo subcommand - see `[misc]` `online` in "Configuration".
 
-Configuration
-=============
+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:
 ```
@@ -350,23 +419,6 @@ other names are not looked up in this alias map.
    one which requires online access (currently, `fetch`), in which
    case the default is online.
 
-Running the command
-===================
-
-Normally you pass cargo as an argument to nailing-cargo.  But you
-can also pass make or any other command.  You may need to pass
-`--no-cargo-manifest-args` (aka `-M`) to nailing-cargo, to avoid
-passing options like `--manifest-path` to make or whatever.
-
-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.
-
 Limitations and bugs
 ====================