Call out rule of relative path of `--config KEY=VALUE`

[cargo.git] / src / doc / src / reference / config.md

diff --git a/src/doc/src/reference/config.md b/src/doc/src/reference/config.md
index f4749457e7a52a94e634fa91f621cfddc26db400..e9eefc082723598c6fffbf3d4b348dd77e2dba5e 100644 (file)
--- a/src/doc/src/reference/config.md
+++ b/src/doc/src/reference/config.md
@@ -59,6 +59,7 @@ c = "check"
 t = "test"
 r = "run"
 rr = "run --release"
+recursive_example = "rr --example recursions"
 space_example = ["run", "--release", "--", "\"command list\""]
 
 [build]
@@ -237,13 +238,28 @@ precedence rules as other options specified directly with `--config`.
 
 ### Config-relative paths
 
-Paths in config files may be absolute, relative, or a bare name without any
-path separators. Paths for executables without a path separator will use the
-`PATH` environment variable to search for the executable. Paths for
-non-executables will be relative to where the config value is defined. For
-config files, that is relative to the parent directory of the `.cargo`
-directory where the value was defined. For environment variables it is
-relative to the current working directory.
+Paths in config files may be absolute, relative, or a bare name without any path separators.
+Paths for executables without a path separator will use the `PATH` environment variable to search for the executable. 
+Paths for non-executables will be relative to where the config value is defined.
+
+In particular, rules are:
+
+* For environment variables, paths are relative to the current working directory.
+* For config values loaded directly from the [`--config KEY=VALUE`](#command-line-overrides) option,
+  paths are relative to the current working directory.
+* For config files, paths are relative to the parent directory of the directory where the config files were defined,
+  no matter those files are from either the [hierarchical probing](#hierarchical-structure)
+  or the [`--config <path>`](#command-line-overrides) option.
+
+> **Note:** To maintain consistency with existing `.cargo/config.toml` probing behavior,
+> it is by design that a path in a config file passed via `--config <path>`
+> is also relative to two levels up from the config file itself.
+>
+> To avoid unexpected results, the rule of thumb is putting your extra config files
+> at the same level of discovered `.cargo/config.toml` in your porject.
+> For instance, given a project `/my/project`, 
+> it is recommended to put config files under `/my/project/.cargo`
+> or a new directory at the same level, such as `/my/project/.config`.
 
 ```toml
 # Relative path examples.
@@ -335,6 +351,14 @@ r = "run"
 
 Aliases are not allowed to redefine existing built-in commands.
 
+Aliases are recursive:
+
+```toml
+[alias]
+rr = "run --release"
+recursive_example = "rr --example recursions"
+```
+
 #### `[build]`
 
 The `[build]` table controls build-time operations and compiler settings.
@@ -344,7 +368,9 @@ The `[build]` table controls build-time operations and compiler settings.
 * Default: number of logical CPUs
 * Environment: `CARGO_BUILD_JOBS`
 
-Sets the maximum number of compiler processes to run in parallel.
+Sets the maximum number of compiler processes to run in parallel. If negative,
+it sets the maximum number of compiler processes to the number of logical CPUs
+plus provided value. Should not be 0.
 
 Can be overridden with the `--jobs` CLI option.
 
@@ -361,7 +387,8 @@ Sets the executable to use for `rustc`.
 * Environment: `CARGO_BUILD_RUSTC_WRAPPER` or `RUSTC_WRAPPER`
 
 Sets a wrapper to execute instead of `rustc`. The first argument passed to the
-wrapper is the path to the actual `rustc`.
+wrapper is the path to the actual executable to use
+(i.e., `build.rustc`, if that is set, or `"rustc"` otherwise).
 
 ##### `build.rustc-workspace-wrapper`
 * Type: string (program path)
@@ -369,7 +396,8 @@ wrapper is the path to the actual `rustc`.
 * Environment: `CARGO_BUILD_RUSTC_WORKSPACE_WRAPPER` or `RUSTC_WORKSPACE_WRAPPER`
 
 Sets a wrapper to execute instead of `rustc`, for workspace members only.
-The first argument passed to the wrapper is the path to the actual `rustc`.
+The first argument passed to the wrapper is the path to the actual
+executable to use (i.e., `build.rustc`, if that is set, or `"rustc"` otherwise).
 It affects the filename hash so that artifacts produced by the wrapper are cached separately.
 
 ##### `build.rustdoc`
@@ -380,16 +408,25 @@ It affects the filename hash so that artifacts produced by the wrapper are cache
 Sets the executable to use for `rustdoc`.
 
 ##### `build.target`
-* Type: string
+* Type: string or array of strings
 * Default: host platform
 * Environment: `CARGO_BUILD_TARGET`
 
-The default target platform triple to compile to.
+The default target platform triples to compile to.
+
+This allows passing either a string or an array of strings. Each string value
+is a target platform triple. The selected build targets will be built for each
+of the selected architectures.
 
-This may also be a relative path to a `.json` target spec file.
+The string value may also be a relative path to a `.json` target spec file.
 
 Can be overridden with the `--target` CLI option.
 
+```toml
+[build]
+target = ["x86_64-unknown-linux-gnu", "i686-unknown-linux-gnu"]
+```
+
 ##### `build.target-dir`
 * Type: string (path)
 * Default: "target"