Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: Clarify [doc].browser docs, document PathAndArgs better #9747

Merged
merged 1 commit into from
Jul 29, 2021
Merged

doc: Clarify [doc].browser docs, document PathAndArgs better #9747

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 20 additions & 7 deletions src/doc/src/reference/config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -195,6 +195,20 @@ runner = "foo" # Searches `PATH` for `foo`.
directory = "vendor"
```

### Executable paths with arguments

Some Cargo commands invoke external programs, which can be configured as a path
and some number of arguments.

The value may be an array of strings like `['/path/to/program', 'somearg']` or
a space-separated string like `'/path/to/program somearg'`. If the path to the
executable contains a space, the list form must be used.

If Cargo is passing other arguments to the program such as a path to open or
run, they will be passed after the last specified argument in the value of an
option of this format. If the specified program does not have path separators,
Cargo will search `PATH` for its executable.

### Credentials

Configuration values with sensitive information are stored in the
Expand Down Expand Up @@ -406,6 +420,10 @@ The `[doc]` table defines options for the [`cargo doc`] command.

##### `doc.browser`

* Type: string or array of strings ([program path and args])
* Default: `BROWSER` environment variable, or, if that is missing,
opening the link in a system specific way

This option sets the browser to be used by [`cargo doc`], overriding the
`BROWSER` environment variable when opening documentation with the `--open`
option.
Expand Down Expand Up @@ -837,7 +855,7 @@ Specifies the linker which is passed to `rustc` (via [`-C linker`]) when the
`<triple>` is being compiled for. By default, the linker is not overridden.

##### `target.<triple>.runner`
* Type: string or array of strings (program path and args)
* Type: string or array of strings ([program path and args])
* Default: none
* Environment: `CARGO_TARGET_<triple>_RUNNER`

Expand All @@ -846,12 +864,6 @@ executed by invoking the specified runner with the actual executable passed as
an argument. This applies to [`cargo run`], [`cargo test`] and [`cargo bench`]
commands. By default, compiled executables are executed directly.

The value may be an array of strings like `['/path/to/program', 'somearg']` or
a space-separated string like `'/path/to/program somearg'`. The arguments will
be passed to the runner with the executable to run as the last argument. If
the runner program does not have path separators, it will search `PATH` for
the runner executable.

##### `target.<cfg>.runner`

This is similar to the [target runner](#targettriplerunner), but using
Expand Down Expand Up @@ -958,6 +970,7 @@ Sets the width for progress bar.
[toml]: https://toml.io/
[incremental compilation]: profiles.md#incremental
[profile]: profiles.md
[program path with args]: #executable-paths-with-arguments
[libcurl format]: https://ec.haxx.se/usingcurl-proxies.html
[source replacement]: source-replacement.md
[revision]: https://git-scm.com/docs/gitrevisions
Expand Down