* `-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
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`
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
--------------------------------