Repository: rust
Issue: UX bug: apparent Cargo output (from `rustc`) tells me to use a flag that doesn't exist in Cargo, `-Z macro-backtrace`.
Labels: A-diagnostics,A-macros,T-compiler,D-incorrect,A-CLI

### Problem

When I run a build command, Cargo appears to tell me I can add `-Z backtrace` on nightly for more diagnostics. When I try that, it says this is an unknown option.

### Steps

1. I'm writing my first (terrible, messy, proof of concept) proc macro which generates test code. I don't believe my project specific details are relevant for the most part, but they might be, so I describe those in the Notes section below. I believe for this bug the only relevant part is the `= note:` line.

```
$ RUSTFLAGS='--cfg procmacro2_semver_exempt' cargo build --tests                                                                                       
   Compiling use-file-tests v0.1.0 (/home/user/hack/use-file-tests)                                                                                    
error: SourceFile { path: "<parsed string 1>", is_real: false } is not a real file.         
 --> src/lib.rs:3:1                                                                                                                                    
  |                                                                                                                                                    
3 | #[file_tests("my-test-dir")]                                                                                                                       
  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^                                                                                                                       
  |                                                                                                                                                    
  = note: this error originates in the attribute macro `file_tests` (in Nightly builds, run with -Z macro-backtrace for more info)
                                                                                                                                                       
error: could not compile `use-file-tests` due to previous error
```

2. Seeing the `note:`, attempt to do exactly what it says:

```
$ RUSTFLAGS='--cfg procmacro2_semver_exempt' cargo +nightly -Z macro-backtrace build --tests            
error: unknown `-Z` flag specified: macro-backtrace
```

3. Get confused, and check the help, observing no `macro-backtrace` flag appears:

```
$ RUSTFLAGS='--cfg procmacro2_semver_exempt' cargo +nightly -Z help

Available unstable (nightly-only) flags:

    -Z allow-features          -- Allow *only* the listed unstable features
    -Z avoid-dev-deps          -- Avoid installing dev-dependencies if possible
    -Z binary-dep-depinfo      -- Track changes to dependency artifacts
    -Z bindeps                 -- Allow Cargo packages to depend on bin, cdylib, and staticlib crates, and use the artifacts built by those crates
    -Z build-std               -- Enable Cargo to compile the standard library itself as part of a crate graph compilation
    -Z build-std-features      -- Configure features enabled for the standard library itself when building the standard library
    -Z config-include          -- Enable the `include` key in config files
    -Z credential-process      -- Add a config setting to fetch registry authentication tokens by calling an external process
    -Z check-cfg               -- Specify scope of compile-time checking of `cfg` names/values
    -Z doctest-in-workspace    -- Compile doctests with paths relative to the workspace root
    -Z doctest-xcompile        -- Compile and run doctests for non-host target using runner config
    -Z dual-proc-macros        -- Build proc-macros for both the host and the target
    -Z minimal-versions        -- Resolve minimal dependency versions instead of maximum
    -Z mtime-on-use            -- Configure Cargo to update the mtime of used files
    -Z multitarget             -- Allow passing multiple `--target` flags to the cargo subcommand selected
    -Z no-index-update         -- Do not update the registry index even if the cache is outdated
    -Z panic-abort-tests       -- Enable support to run tests with -Cpanic=abort
    -Z host-config             -- Enable the [host] section in the .cargo/config.toml file
    -Z http-registry           -- Support HTTP-based crate registries
    -Z target-applies-to-host  -- Enable the `target-applies-to-host` key in the .cargo/config.toml file
    -Z rustdoc-map             -- Allow passing external documentation mappings to rustdoc
    -Z terminal-width          -- Provide a terminal width to rustc for error truncation
    -Z unstable-options        -- Allow the usage of unstable options
    -Z rustdoc-scrape-examples -- Allow rustdoc to scrape examples from reverse-dependencies for documentation

Run with 'cargo -Z [FLAG] [SUBCOMMAND]'

Unstable flags are only available on the nightly channel of Cargo, but this is the `stable` channel.
See https://doc.rust-lang.org/book/appendix-07-nightly-rust.html for more information about Rust release channels.

See https://doc.rust-lang.org/nightly/cargo/reference/unstable.html for more information about these flags.
```

### Possible Solution(s)

I searched [Cargo open issues for `macro-backtrace`](https://github.com/rust-lang/cargo/issues?q=is%3Aissue+is%3Aopen+macro-backtrace) (as well as closed issues), and based on titles, this was the only potentially relevant ticket:

- https://github.com/rust-lang/cargo/issues/6049

A quick skim of that ticket makes it sound like Cargo is explicitly reifying `rustc` flags, so one explanation for this UX bug is that `rustc` emits the `note:` line, and it *does* provide that flag, but `cargo` doesn't parse/support it.

I just realized that while writing this, and verified:

```
$ rustc +nightly -Z help | grep macro
    -Z                            debug-macros=val -- emit line numbers debug info inside macros (default: no)
    -Z                        dual-proc-macros=val -- load proc macros for both target and host, but only link to the target (default: no)
    -Z                         macro-backtrace=val -- show macro backtraces (default: no)
    -Z                    proc-macro-backtrace=val -- show backtraces for panics during proc-macro execution (default: no)
    -Z                              span-debug=val -- forward proc_macro::Span's `Debug` impl to `Span`
    -Z                            trace-macros=val -- for every macro invocation, print its name and arguments (default: no)

$ rustc +nightly --version
rustc 1.63.0-nightly (9257f5aad 2022-05-21)
```

So now it does seem like this hypothesis is correct. In that case, the solution is obvious: ensure `cargo` supports any flag that `rustc` instructs users to use. This would be the best UX.

An alternative solution: modify `rustc` to help users (like me, who almost never invoke `rustc` directly and aren't very aware of the `cargo` / `rustc` boundary) so that for every flag or configuration `rustc` suggests which `cargo` does not support, the error note explains this is a `rustc` feature, not a `cargo` feature. For example, maybe this note would be changed to:

```
  = note: this error originates in the attribute macro `file_tests` (in Nightly builds, run rustc directly (not cargo) with -Z macro-backtrace for more info)
```

### Notes

My usage of Cargo may be rarer or incorrect for this project. I wrote all of this before realizing the likely issue is that `rustc` is suggesting a flag which `cargo` does not support in the Solutions section above.

Here are details I believe are most relevant:

- I'm writing a proc-macro crate called `file-tests`. It is a standalone crate (not in a workspace).
- I'm manually testing it with a crate called `use-file-tests` in a sibling directory, also outside of a workspace. I am still using relative path dependency: `[dependencies.file-tests] \n path = "../../file-tests` (I've never done this before outside of a workspace.)
- I have been doing development and build on Cargo stable, so if there any build state cache bugs when adding `+nightly` after builds, they may be relevant. This also may be more relevant since the two crates aren't in a shared workspace?
- The funky `RUSTFLAGS='--cfg procmacro2_semver_exempt'` is specific to [`proc-macro2`](https://docs.rs/proc-macro2/1.0.39/proc_macro2/#unstable-features) crate which I'm using for source file tracking.
- The error message `error: SourceFile { path: "<parsed string 1>", is_real: false } is not a real file.` is generated by code in `test-files` because I require poking the FS around the test mod source file.


### Version

```text
$ cargo version --verbose
cargo 1.61.0 (a028ae4 2022-04-29)
release: 1.61.0
commit-hash: a028ae42fc1376571de836be702e840ca8e060c2
commit-date: 2022-04-29
host: x86_64-unknown-linux-gnu
libgit2: 1.4.2 (sys:0.14.2 vendored)
libcurl: 7.80.0-DEV (sys:0.4.51+curl-7.80.0 vendored ssl:OpenSSL/1.1.1m)
os: Debian 11 (bullseye) [64-bit]

$ cargo +nightly version --verbose
cargo 1.63.0-nightly (a4c1cd0eb 2022-05-18)
release: 1.63.0-nightly
commit-hash: a4c1cd0eb6b18082a7e693f5a665548fe1534be4
commit-date: 2022-05-18
host: x86_64-unknown-linux-gnu
libgit2: 1.4.2 (sys:0.14.2 vendored)
libcurl: 7.80.0-DEV (sys:0.4.51+curl-7.80.0 vendored ssl:OpenSSL/1.1.1n)
os: Debian 11 (bullseye) [64-bit]
```