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>`.
+ * 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 `-`.
+ * `<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.)
+ (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.
+ * 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 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).
+ * 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
-------
* `-T<arch>` | `--target=<arch>`
- Specify target architecture.
+ Specify target architecture.
- This option translates to a `--target=<arch>` option to cargo
- (when the subcommand accepts it).
+ 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'`.
+ 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'`.
* `-s<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`.
+ 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`.
- nailing-cargo knows about `update`, `generate-lockfile` and
- `fetch`; all other subcommands are (silently) treated the same
- way as `build` (ie, no subcommand properties). See
- `--subcommand-props`, below, for more detail about how the
- subcommand affects nailing-cargo's behaviour.
+ nailing-cargo knows about `update`, `generate-lockfile` and
+ `fetch`; all other subcommands are (silently) treated the same way
+ as `build` (ie, no subcommand properties). 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 use the
- cargo subcommand found from parsing nailing-cargo's
- command line.
+ The default is to use the cargo subcommand found from parsing
+ nailing-cargo's command line. NB: `-s` does not affect
+ which build command (and which cargo subcommand) is actually run.
* `-c` | `-C`
- Controls the addition of cargo command line options; ie,
- whether nailing-cargo should treat the build command as if it
- were cargo.
- With `-C`, nailing-cargo will not add additional options
- to the build command. With `-c` it will pass those options
- after the cargo subcommand (usages 1 and 2) or right
- after the build command (usage 3).
+ Controls the addition of cargo command line options; ie,
+ whether nailing-cargo should treat the build command as if it
+ were cargo.
+ With `-C`, nailing-cargo will not add additional options
+ to the build command. With `-c` it will pass those options
+ after the cargo subcommand (usages 1 and 2) or right
+ after the build command (usage 3).
- The cargo options are in any case also passed in the
- environment - see [Environment of the build command].
+ The cargo options are in any case also passed in the
+ environment - see [Environment of the build command].
- The default is to pass cargo options if the command line
- parsing yielded a cargo command and options (usages 1 and 2),
- rather than a non-cargo build command (usage 3). `-C` and `-c`
- do not affect the parsing of nailing-cargo's command line.
+ The default is to pass cargo options if the command line
+ parsing yielded a cargo command and options (usages 1 and 2),
+ rather than a non-cargo build command (usage 3). `-C` and `-c`
+ do not affect the parsing of nailing-cargo's command line.
* `-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".
+ 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
- alternative) to be updated in the source directory.
+ 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.
+ 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.
+ This makes no sense with in-tree builds.
- Default is no update unless the cargo subcommand will want it.
+ Default is no update unless the cargo subcommand will want it.
* `--subcommand-props=<prop>,...`
- Specify the properties of the subcommand. This is an
- alternative to `-s<subcmd>`. The usual properties are:
+ Specify the properties of the subcommand. This is an
+ alternative to `-s<subcmd>`. The usual properties are:
* `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.)