* `-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
+ nailing-cargo knows about `update`, `generate-lockfile` and
+ `fetch`; all other subcommands are (silently) treated the
+ same way as `build`. See `--subcommand-props`, below, for
+ more detail about how the subcommand affects nailing-cargo's
+ behaviour.
+
+ This option does not affect which build command (and which
cargo subcommand) is actually run.
+ The default is to look into the command line to find the cargo
+ subcommand.
* `-C`
But this option does not affect which build command is actually
run.
+ The default is to treat the build command as cargo unless a
+ build command is specified whose leafname does not contains the
+ string `cargo`.
+
+ * `-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".
+
* `-u` | `--cargo-lock-update` | `-U` | `--no-cargo-lock-update`
Enables, or disables, the dance to allow `Cargo.lock` (or
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.
+ * `--subcommand-props=<prop>,...`
- 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`.
+ Specify the properties of the subcommand. This is an
+ alternative to `-c<subcmd>`. The properties are:
- `<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
+ * `lock_update`: cargo will want to update `Cargo.lock`. (The `-u` and `-U` options override this.)
+ * `online`: this subcommand makes no sense to run offline. (The `-o` and `-O` options, and the configuration, can override this.)
+ * `!target`: cargo would reject `--target=<arch>`; in this case nailing-cargo's `-T` option is ineffective.
+ * `!target-dir`: cargo would reject `--target-dir`, so don't pass it. (Usually we pass `--target-dir=target` when we pass `--manifest-path`, since cargo's default is `target` in the same directory as `Cargo.toml`.)
+ * `!manifest-path`: cargo would reject `--manifest-path`, so don't pass it (and don't pass `--target-dir` either). Only makes any difference for out-of-tree builds. Things will probably go wrong unless the build command looks at `NAILINGCARGO_MANIFEST_DIR`.
+ * `!locked`: cargo would reject `--locked`, so don't pass it (hazardous).
+ * `!offline`: the build command would reject `--offline`, so never pass it. *Not* overridden by configuration or command line. Primarily for non-cargo build commands.
Environment of the build command
--------------------------------
All of these are absolute paths.
+For out-of-tree builds it is always necessary to pass --manifest-path
+to cargo, so non-cargo build commands will need to look at
+`NAILINGCARGO_MANIFEST_DIR` and turn that back into a cargo option;
+they may also need to pass `--target-dir=<target>`.
+
Configuration reference
=======================
At least, running nailing-cargo again will clean up any mess
left by an interrupted run.
+ * nailing-cargo needs to understand the behaviour of the cargo
+ subcommand you are running - especially for out-of-tree builds.
+ nailing-cargo only has a short builtin list of commands it knows
+ about (see the `-c` option). For other commands, you may need to
+ add an entry to `@subcmd_propss` in the source, or use
+ `--subcommand-props`.
+
* Out of tree builds require a unified filesystem view: eg, different
users on the same host, NFS, or something.
~ianmdlvl / nailing-cargo.git / blobdiff