rust/tests/run-make/rustc-help/help-v.stdout
Guillaume Gomez 1832bdfe64
Rollup merge of #147611 - stablize-remap-path-scope, r=davidtwco
Stabilize `-Zremap-path-scope`

# Stabilization report of `--remap-path-scope`

## Summary

RFC 3127 trim-paths aims to improve the current status of sanitizing paths emitted by the compiler via the `--remap-path-prefix=FROM=TO` command line flag, by offering a profile setting named `trim-paths` in Cargo to sanitize absolute paths introduced during compilation that may be embedded in the compiled binary executable or library.

As part of that RFC the compiler was asked to add the `--remap-path-scope` command-line flag to control the scoping of how paths get remapped in the resulting binary.

Tracking:

- https://github.com/rust-lang/rust/issues/111540

### What is stabilized

The rustc `--remap-path-scope` flag is being stabilized by this PR. It defines which scopes of paths should be remapped by `--remap-path-prefix`.

This flag accepts a comma-separated list of values and may be specified multiple times, in which case the scopes are aggregated together.

The valid scopes are:

- `macro` - apply remappings to the expansion of `std::file!()` macro. This is where paths in embedded panic messages come from
- `diagnostics` - apply remappings to printed compiler diagnostics
- `debuginfo` - apply remappings to debug informations
- `coverage` - apply remappings to coverage informations
- `object` - apply remappings to all paths in compiled executables or libraries, but not elsewhere. Currently an alias for `macro,coverage,debuginfo`.
- `all` (default) - an alias for all of the above, also equivalent to supplying only `--remap-path-prefix` without `--remap-path-scope`.

#### Example

```sh
# With `object` scope only the build outputs will be remapped, the diagnostics won't be remapped.
rustc --remap-path-prefix=$(PWD)=/remapped --remap-path-scope=object main.rs
```

### What isn't stabilized

None of the Cargo facility is being stabilized in this stabilization PR, only the `--remap-path-scope` flag in `rustc` is being stabilized.

## Design

### RFC history

- [RFC3127 - trim-paths](https://rust-lang.github.io/rfcs/3127-trim-paths.html)

### Answers to unresolved questions

> What questions were left unresolved by the RFC? How have they been answered? Link to any relevant lang decisions.

There are no unresolved questions regarding `--remap-path-scope`.

(The tracking issue list a bunch of unresolved questions but they are for `--remap-path-prefix` or the bigger picture `trim-paths` in Cargo and are not related the functionality provided by `--remap-path-scope`.)

### Post-RFC changes

The RFC described more scopes, in particularly regarding split debuginfo. Those scopes where removed after analysis by `michaelwoerister` of all the possible combinations in https://github.com/rust-lang/rust/issues/111540#issuecomment-1994010274.

### Nightly extensions

There are no nightly extensions.

### Doors closed

We are committing to having to having a flag that control which paths are being remapped based on a "scope".

## Feedback

### Call for testing

> Has a "call for testing" been done? If so, what feedback was received?

No call for testing has been done per se but feedback has been received on both the rust-lang/rust and rust-lang/cargo tracking issue.

The feedback was mainly related to deficiencies in *our best-effort* `--remap-path-prefix` implementation, in particular regarding linkers added paths, which does not change anything for `--remap-path-scope`.

### Nightly use

> Do any known nightly users use this feature? Counting instances of `#![feature(FEATURE_NAME)]` on GitHub with grep might be informative.

Except for Cargo unstable `trim-paths` there doesn't appear any committed use [on GitHub](https://github.com/search?q=%22--remap-path-scope%22+NOT+path%3A%2F%5Esrc%5C%2Fcargo%5C%2Fcore%5C%2Fcompiler%5C%2F%2F+NOT+path%3A%2F%5Etext%5C%2F%2F+NOT+path%3A%2F%5Erust%5C%2Fsrc%5C%2Fdoc%5C%2Funstable-book%5C%2Fsrc%5C%2Fcompiler-flags%5C%2F%2F+NOT+path%3A%2F%5Esrc%5C%2Fdoc%5C%2Funstable-book%5C%2Fsrc%5C%2Fcompiler-flags%5C%2F%2F+NOT+path%3A%2F%5Ecollector%5C%2Fcompile-benchmarks%5C%2Fcargo-0%5C.87%5C.1%5C%2Fsrc%5C%2Fcargo%5C%2Fcore%5C%2Fcompiler%5C%2F%2F&type=code).

## Implementation

### Major parts

- b3f8586fb1/compiler/rustc_session/src/config.rs (L1373-L1384)
- b3f8586fb1/compiler/rustc_session/src/session.rs (L1526)
- b3f8586fb1/compiler/rustc_span/src/lib.rs (L352-L372)

### Coverage

- [`tests/run-make/split-debuginfo/rmake.rs`](9725c4baac/tests/run-make/split-debuginfo/rmake.rs (L7))
- [`tests/ui/errors/remap-path-prefix.rs`](9725c4baac/tests/ui/errors/remap-path-prefix.rs (L4))
- [`tests/ui/errors/remap-path-prefix-macro.rs`](9725c4baac/tests/ui/errors/remap-path-prefix-macro.rs (L1-L4))
- [`tests/run-make/remap-path-prefix-dwarf/rmake.rs
`](9725c4baac/tests/run-make/remap-path-prefix-dwarf/rmake.rs)
- [`tests/run-make/remap-path-prefix/rmake.rs`](9725c4baac/tests/run-make/remap-path-prefix/rmake.rs)
- [`tests/ui/errors/remap-path-prefix-diagnostics.rs`](9725c4baac/tests/ui/errors/remap-path-prefix-diagnostics.rs)

### Outstanding bugs

> What outstanding bugs involve this feature? List them. Should any block the stabilization? Discuss why or why not.

There are no outstanding bugs regarding `--remap-path-scope`.

### Outstanding FIXMEs

> What FIXMEs are still in the code for that feature and why is it OK to leave them there?

There are no FIXME regarding `--remap-path-scope` in it-self.

### Tool changes

> What changes must be made to our other tools to support this feature. Has this work been done? Link to any relevant PRs and issues.

- rustdoc (both JSON, HTML and doctest)
  - `rustdoc` has support for `--remap-path-prefix`, it should probably also get support for `--remap-path-scope`, although rustdoc maybe want to adapt the scopes for it's use (replace `debuginfo` with `documentation` for example).

## History

> List issues and PRs that are important for understanding how we got here.

- https://github.com/rust-lang/rust/pull/115214
- https://github.com/rust-lang/rust/pull/122450
- https://github.com/rust-lang/rust/pull/139550
- https://github.com/rust-lang/rust/pull/140716

## Acknowledgments

> Summarize contributors to the feature by name for recognition and so that those people are notified about the stabilization. Does anyone who worked on this *not* think it should be stabilized right now? We'd like to hear about that if so.

- @cbeuw
- @michaelwoerister
- @weihanglo
- @Urgau

@rustbot labels +T-compiler +needs-fcp +F-trim-paths
r? @davidtwco
2026-01-20 14:36:30 +01:00

95 lines
5.1 KiB
Text

Usage: rustc [OPTIONS] INPUT
Options:
-h, --help Display this message
--cfg <SPEC> Configure the compilation environment.
SPEC supports the syntax `<NAME>[="<VALUE>"]`.
--check-cfg <SPEC>
Provide list of expected cfgs for checking
-L [<KIND>=]<PATH> Add a directory to the library search path. The
optional KIND can be one of
<dependency|crate|native|framework|all> (default:
all).
-l [<KIND>[:<MODIFIERS>]=]<NAME>[:<RENAME>]
Link the generated crate(s) to the specified native
library NAME. The optional KIND can be one of
<static|framework|dylib> (default: dylib).
Optional comma separated MODIFIERS
<bundle|verbatim|whole-archive|as-needed>
may be specified each with a prefix of either '+' to
enable or '-' to disable.
--crate-type <bin|lib|rlib|dylib|cdylib|staticlib|proc-macro>
Comma separated list of types of crates
for the compiler to emit
--crate-name <NAME>
Specify the name of the crate being built
--edition <2015|2018|2021|2024|future>
Specify which edition of the compiler to use when
compiling code. The default is 2015 and the latest
stable edition is 2024.
--emit <TYPE>[=<FILE>]
Comma separated list of types of output for the
compiler to emit.
Each TYPE has the default FILE name:
* asm - CRATE_NAME.s
* llvm-bc - CRATE_NAME.bc
* dep-info - CRATE_NAME.d
* link - (platform and crate-type dependent)
* llvm-ir - CRATE_NAME.ll
* metadata - libCRATE_NAME.rmeta
* mir - CRATE_NAME.mir
* obj - CRATE_NAME.o
* thin-link-bitcode - CRATE_NAME.indexing.o
--print <INFO>[=<FILE>]
Compiler information to print on stdout (or to a file)
INFO may be one of
<all-target-specs-json|backend-has-zstd|calling-conventions|cfg|check-cfg|code-models|crate-name|crate-root-lint-levels|deployment-target|file-names|host-tuple|link-args|native-static-libs|relocation-models|split-debuginfo|stack-protector-strategies|supported-crate-types|sysroot|target-cpus|target-features|target-libdir|target-list|target-spec-json|target-spec-json-schema|tls-models>.
-g Equivalent to -C debuginfo=2
-O Equivalent to -C opt-level=3
-o <FILENAME> Write output to FILENAME
--out-dir <DIR> Write output to compiler-chosen filename in DIR
--explain <OPT> Provide a detailed explanation of an error message
--test Build a test harness
--target <TARGET>
Target tuple for which the code is compiled
-A, --allow <LINT> Set lint allowed
-W, --warn <LINT> Set lint warnings
--force-warn <LINT>
Set lint force-warn
-D, --deny <LINT> Set lint denied
-F, --forbid <LINT> Set lint forbidden
--cap-lints <LEVEL>
Set the most restrictive lint level. More restrictive
lints are capped at this level
-C, --codegen <OPT>[=<VALUE>]
Set a codegen option
-V, --version Print version info and exit
-v, --verbose Use verbose output
--extern <NAME>[=<PATH>]
Specify where an external rust library is located
--sysroot <PATH>
Override the system root
--error-format <human|json|short>
How errors and other messages are produced
--json <CONFIG> Configure the JSON output of the compiler
--color <auto|always|never>
Configure coloring of output:
* auto = colorize, if output goes to a tty (default);
* always = always colorize output;
* never = never colorize output
--diagnostic-width <WIDTH>
Inform rustc of the width of the output so that
diagnostics can be truncated to fit
--remap-path-prefix <FROM>=<TO>
Remap source names in all output (compiler messages
and output files)
--remap-path-scope <macro,diagnostics,debuginfo,coverage,object,all>
Defines which scopes of paths should be remapped by
`--remap-path-prefix`
@path Read newline separated options from `path`
Additional help:
-C help Print codegen options
-W help Print 'lint' options and default settings
-Z help Print unstable compiler options