Add -Z json-target-spec by ehuss · Pull Request #16557 · rust-lang/cargo

ehuss · 2026-01-25T01:53:13Z

This adds the -Z json-target-spec CLI flag to assist with using custom .json target spec files. rustc recently switched so that it requires -Z unstable-options when using custom spec files (rust-lang/rust#151534). This can make it rather awkward to use spec files with cargo because it then requires setting RUSTFLAGS and RUSTDOCFLAGS to pass -Zunstable-options. It also ends up causing some confusing error messages.

See the individual commits for more details.

This ended up being a larger diff than I wanted. I'm not 100% certain this is worth it, but I think it significantly improves the experience using .json files, so I I'm leaning towards it.

How to test and review this PR?

Testing can be done with rustc built from rust-lang/rust#151534 to ensure that everything passes after that PR (including setting CARGO_RUN_BUILD_STD_TESTS=1).

This changes the index parsing code to pass around CliUnstable instead of the bindeps bool to make it easier to check for multiple unstable options.

This changes CompileTarget to an enum to better differentiate when it is a JSON path versus when it is a target tuple. This should help ensure that the correct behavior is being used without constantly needing to check if the suffix is `.json`. This also adds an `CompileKind::add_target_arg` helper to centralize where the `--target` arg adding is done.

This adds the `-Z json-target-spec` CLI flag to assist with using custom `.json` target spec files. `rustc` recently switched so that it requires `-Z unstable-options` when using custom spec files (rust-lang/rust#151534). This can make it rather awkward to use spec files with cargo because it then requires setting RUSTFLAGS and RUSTDOCFLAGS to pass `-Zunstable-options`. It also ends up causing some confusing error messages. Now, using `--target` with `.json` extension files generates an error that explains you need `-Zjson-target-spec`. The only thing this flag does is disable that error, and automatically passes `-Zunstable-options` with the `--target` flag. This does not 100% cover json target spec files, because they can be placed in RUST_TARGET_PATH or the sysroot, and `rustc` will automatically search for them (without the `.json` extension in the `--target` arg). The user will just need to use RUSTFLAGS/RUSTDOCFLAGS in that situation (but I expect that to be rare). The majority of this change is changing `CompileTarget::new` to take a flag if `-Zjson-target-spec` is enabled, and then threading through all the places that call it. `CompileTarget::new` is responsible for generating an error if json is used without the Z flag.

rustbot · 2026-01-25T01:53:18Z

r? @epage

rustbot has assigned @epage.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

weihanglo

Thanks!

View changes since this review

weihanglo · 2026-01-25T02:48:40Z

Ah Ed got it already

This adds the `-Z json-target-spec` CLI flag to assist with using custom `.json` target spec files. `rustc` recently switched so that it requires `-Z unstable-options` when using custom spec files (rust-lang/rust#151534). This can make it rather awkward to use spec files with cargo because it then requires setting RUSTFLAGS and RUSTDOCFLAGS to pass `-Zunstable-options`. It also ends up causing some confusing error messages. See the individual commits for more details. This ended up being a larger diff than I wanted. I'm not 100% certain this is worth it, but I think it significantly improves the experience using `.json` files, so I I'm leaning towards it. Testing can be done with `rustc` built from rust-lang/rust#151534 to ensure that everything passes after that PR (including setting `CARGO_RUN_BUILD_STD_TESTS=1`).

Update cargo submodule 11 commits in efcd9f58636c1990393d495159045d9c35e43b8f..0f3a1e9099aecdf95f144e842d96dc1827c1985 2026-01-23 13:50:59 +0000 to 2026-01-27 20:14:45 +0000 - feat(lints): Add redundant_homepage lint (rust-lang/cargo#16561) - feat(lints): Add `non_*_case_features` (rust-lang/cargo#16560) - Update build_std::basic test to ensure index doesn't update (rust-lang/cargo#16559) - feat(lints): Add mutually exclusive `non_{kebab,snake}_case_packages` (rust-lang/cargo#16554) - fix(lints): Pluralize non_kebab_case_bins (rust-lang/cargo#16553) - Add -Z json-target-spec (rust-lang/cargo#16557) - feat(lint): Add redundant_readme lint (rust-lang/cargo#16552) - chore(deps): update msrv (rust-lang/cargo#16387) - tests: add regression test for --artifact-dir on stable (rust-lang/cargo#16541) - Don't check the specific build-std output (rust-lang/cargo#16551) - Fix build-std lto test to run on other platforms (rust-lang/cargo#16550)

Update cargo submodule 18 commits in efcd9f58636c1990393d495159045d9c35e43b8f..fe2f314aef06e688a9517da1ac0577bb1854d01f 2026-01-23 13:50:59 +0000 to 2026-01-30 21:52:01 +0000 - feat(lints): Add unused workspace dependency lint (rust-lang/cargo#16571) - docs: Remove redundant homepage link (rust-lang/cargo#16572) - refactor: Remove unused workspace dependencies (rust-lang/cargo#16573) - Re-downgrade curl-sys (rust-lang/cargo#16570) - docs(report): enhance man pages for `cargo report *` (rust-lang/cargo#16430) - fix(lints): Refine redundant metadata lints (rust-lang/cargo#16564) - Prevent `cargo init` in home directory (rust-lang/cargo#16566) - feat(lints): Add redundant_homepage lint (rust-lang/cargo#16561) - feat(lints): Add `non_*_case_features` (rust-lang/cargo#16560) - Update build_std::basic test to ensure index doesn't update (rust-lang/cargo#16559) - feat(lints): Add mutually exclusive `non_{kebab,snake}_case_packages` (rust-lang/cargo#16554) - fix(lints): Pluralize non_kebab_case_bins (rust-lang/cargo#16553) - Add -Z json-target-spec (rust-lang/cargo#16557) - feat(lint): Add redundant_readme lint (rust-lang/cargo#16552) - chore(deps): update msrv (rust-lang/cargo#16387) - tests: add regression test for --artifact-dir on stable (rust-lang/cargo#16541) - Don't check the specific build-std output (rust-lang/cargo#16551) - Fix build-std lto test to run on other platforms (rust-lang/cargo#16550)

JSON target specs were destabilized in rust-lang#150151 and rust-lang#151534. However, this broke trying to build rustc itself with a JSON target spec. This is because in a few places bootstrap is manually calling `rustc` without the ability for the user to provide additional flags (primarily, `-Zunstable-options` to enable JSON targets). There's a few different ways to fix this. One would be to change these calls to `rustc` to include flags provided by the user (such as `RUSTFLAGS_NOT_BOOTSTRAP`). Just to keep things simple, this PR proposes to just unconditionally pass `-Zunstable-options`. Another consideration here is how maintainable this is. A possible improvement here would be to have a function somewhere (BootstrapCommand, TargetSelection, free function) that would handle appropriately adding the `--target` flag. For example, that's what cargo does in [`CompileKind::add_target_arg`](https://github.com/rust-lang/cargo/blob/592058c7ce08a2ba2628b01e7dc4ce1e72b6bdff/src/cargo/core/compiler/compile_kind.rs#L144-L154). I have only tested building the compiler and a few tools like rustdoc. I have not tested doing things like building other tools, running tests, etc. This would be much easier if there was a Docker image for testing the use case of building rustc with a custom target spec (and even better if that ran in CI). After the next beta branch, using target JSON specs will become more cumbersome because target specs with the `.json` extension will now require passing `-Zjson-target-spec` (from rust-lang/cargo#16557). This does not affect target specs without the `.json` extension (such as those from RUST_TARGET_PATH). From my testing, it should be sufficient to pass `CARGOFLAGS_NOT_BOOTSTRAP="-Zjson-target-spec"`. I think that should be fine, since this is not a particularly common use case AFAIK. We could extend bootstrap to auto-detect if the target is a file path, and pass `-Zjson-target-spec` appropriately. I tried something similar in f0bdd35, which could be adapted if desired. It would be nice if all of this is documented somewhere. https://rustc-dev-guide.rust-lang.org/building/new-target.html does not really say how to build the compiler with a custom json target. Fixes rust-lang#151729

Update cargo submodule 18 commits in efcd9f58636c1990393d495159045d9c35e43b8f..fe2f314aef06e688a9517da1ac0577bb1854d01f 2026-01-23 13:50:59 +0000 to 2026-01-30 21:52:01 +0000 - feat(lints): Add unused workspace dependency lint (rust-lang/cargo#16571) - docs: Remove redundant homepage link (rust-lang/cargo#16572) - refactor: Remove unused workspace dependencies (rust-lang/cargo#16573) - Re-downgrade curl-sys (rust-lang/cargo#16570) - docs(report): enhance man pages for `cargo report *` (rust-lang/cargo#16430) - fix(lints): Refine redundant metadata lints (rust-lang/cargo#16564) - Prevent `cargo init` in home directory (rust-lang/cargo#16566) - feat(lints): Add redundant_homepage lint (rust-lang/cargo#16561) - feat(lints): Add `non_*_case_features` (rust-lang/cargo#16560) - Update build_std::basic test to ensure index doesn't update (rust-lang/cargo#16559) - feat(lints): Add mutually exclusive `non_{kebab,snake}_case_packages` (rust-lang/cargo#16554) - fix(lints): Pluralize non_kebab_case_bins (rust-lang/cargo#16553) - Add -Z json-target-spec (rust-lang/cargo#16557) - feat(lint): Add redundant_readme lint (rust-lang/cargo#16552) - chore(deps): update msrv (rust-lang/cargo#16387) - tests: add regression test for --artifact-dir on stable (rust-lang/cargo#16541) - Don't check the specific build-std output (rust-lang/cargo#16551) - Fix build-std lto test to run on other platforms (rust-lang/cargo#16550)

JSON target specs were destabilized in rust-lang#150151 and rust-lang#151534. However, this broke trying to build rustc itself with a JSON target spec. This is because in a few places bootstrap is manually calling `rustc` without the ability for the user to provide additional flags (primarily, `-Zunstable-options` to enable JSON targets). There's a few different ways to fix this. One would be to change these calls to `rustc` to include flags provided by the user (such as `RUSTFLAGS_NOT_BOOTSTRAP`). Just to keep things simple, this PR proposes to just unconditionally pass `-Zunstable-options`. Another consideration here is how maintainable this is. A possible improvement here would be to have a function somewhere (BootstrapCommand, TargetSelection, free function) that would handle appropriately adding the `--target` flag. For example, that's what cargo does in [`CompileKind::add_target_arg`](https://github.com/rust-lang/cargo/blob/592058c7ce08a2ba2628b01e7dc4ce1e72b6bdff/src/cargo/core/compiler/compile_kind.rs#L144-L154). I have only tested building the compiler and a few tools like rustdoc. I have not tested doing things like building other tools, running tests, etc. This would be much easier if there was a Docker image for testing the use case of building rustc with a custom target spec (and even better if that ran in CI). After the next beta branch, using target JSON specs will become more cumbersome because target specs with the `.json` extension will now require passing `-Zjson-target-spec` (from rust-lang/cargo#16557). This does not affect target specs without the `.json` extension (such as those from RUST_TARGET_PATH). From my testing, it should be sufficient to pass `CARGOFLAGS_NOT_BOOTSTRAP="-Zjson-target-spec"`. I think that should be fine, since this is not a particularly common use case AFAIK. We could extend bootstrap to auto-detect if the target is a file path, and pass `-Zjson-target-spec` appropriately. I tried something similar in f0bdd35, which could be adapted if desired. It would be nice if all of this is documented somewhere. https://rustc-dev-guide.rust-lang.org/building/new-target.html does not really say how to build the compiler with a custom json target. Fixes rust-lang#151729

This reverts rust-lang#150151 in order to deal with rust-lang#151729 where the destabilization caused a problem with building rustc itself with JSON target specs. There's a fix at rust-lang#152677, but we would prefer to not backport that, and instead give ourselves more time to work out the kinks. Also, the destabilization was incomplete, and the rest of the changes are in 1.95 (rust-lang#151534 and rust-lang/cargo#16557), so it would be nice to keep all the changes together in one release. This reverts commit a89683d, reversing changes made to 2f1bd3f.

…,jieyouxu Support JSON target specs in bootstrap JSON target specs were destabilized in #150151 and #151534. However, this broke trying to build rustc itself with a JSON target spec. This is because in a few places bootstrap is manually calling `rustc` without the ability for the user to provide additional flags (primarily, `-Zunstable-options` to enable JSON targets). There's a few different ways to fix this. One would be to change these calls to `rustc` to include flags provided by the user (such as `RUSTFLAGS_NOT_BOOTSTRAP`). Just to keep things simple, this PR proposes to just unconditionally pass `-Zunstable-options`. Another consideration here is how maintainable this is. A possible improvement here would be to have a function somewhere (BootstrapCommand, TargetSelection, free function) that would handle appropriately adding the `--target` flag. For example, that's what cargo does in [`CompileKind::add_target_arg`](https://github.com/rust-lang/cargo/blob/592058c7ce08a2ba2628b01e7dc4ce1e72b6bdff/src/cargo/core/compiler/compile_kind.rs#L144-L154). I have only tested building the compiler and a few tools like rustdoc. I have not tested doing things like building other tools, running tests, etc. This would be much easier if there was a Docker image for testing the use case of building rustc with a custom target spec (and even better if that ran in CI). After the next beta branch, using target JSON specs will become more cumbersome because target specs with the `.json` extension will now require passing `-Zjson-target-spec` (from rust-lang/cargo#16557). This does not affect target specs without the `.json` extension (such as those from RUST_TARGET_PATH). From my testing, it should be sufficient to pass `CARGOFLAGS_NOT_BOOTSTRAP="-Zjson-target-spec"`. I think that should be fine, since this is not a particularly common use case AFAIK. We could extend bootstrap to auto-detect if the target is a file path, and pass `-Zjson-target-spec` appropriately. I tried something similar in ehuss@f0bdd35, which could be adapted if desired. It would be nice if all of this is documented somewhere. https://rustc-dev-guide.rust-lang.org/building/new-target.html does not really say how to build the compiler with a custom json target. Fixes #151729

[beta] Revert destabilise target-spec-json This reverts #150151 in order to deal with #151729 where the destabilization caused a problem with building rustc itself with JSON target specs. There's a fix at #152677, but we would prefer to not backport that, and instead give ourselves more time to work out the kinks. Also, the destabilization was incomplete, and the rest of the changes are in 1.95 (#151534 and rust-lang/cargo#16557), so it would be nice to keep all the changes together in one release. This reverts commit a89683d, reversing changes made to 2f1bd3f.

…,jieyouxu Support JSON target specs in bootstrap JSON target specs were destabilized in rust-lang/rust#150151 and rust-lang/rust#151534. However, this broke trying to build rustc itself with a JSON target spec. This is because in a few places bootstrap is manually calling `rustc` without the ability for the user to provide additional flags (primarily, `-Zunstable-options` to enable JSON targets). There's a few different ways to fix this. One would be to change these calls to `rustc` to include flags provided by the user (such as `RUSTFLAGS_NOT_BOOTSTRAP`). Just to keep things simple, this PR proposes to just unconditionally pass `-Zunstable-options`. Another consideration here is how maintainable this is. A possible improvement here would be to have a function somewhere (BootstrapCommand, TargetSelection, free function) that would handle appropriately adding the `--target` flag. For example, that's what cargo does in [`CompileKind::add_target_arg`](https://github.com/rust-lang/cargo/blob/592058c7ce08a2ba2628b01e7dc4ce1e72b6bdff/src/cargo/core/compiler/compile_kind.rs#L144-L154). I have only tested building the compiler and a few tools like rustdoc. I have not tested doing things like building other tools, running tests, etc. This would be much easier if there was a Docker image for testing the use case of building rustc with a custom target spec (and even better if that ran in CI). After the next beta branch, using target JSON specs will become more cumbersome because target specs with the `.json` extension will now require passing `-Zjson-target-spec` (from rust-lang/cargo#16557). This does not affect target specs without the `.json` extension (such as those from RUST_TARGET_PATH). From my testing, it should be sufficient to pass `CARGOFLAGS_NOT_BOOTSTRAP="-Zjson-target-spec"`. I think that should be fine, since this is not a particularly common use case AFAIK. We could extend bootstrap to auto-detect if the target is a file path, and pass `-Zjson-target-spec` appropriately. I tried something similar in ehuss/rust@f0bdd35, which could be adapted if desired. It would be nice if all of this is documented somewhere. https://rustc-dev-guide.rust-lang.org/building/new-target.html does not really say how to build the compiler with a custom json target. Fixes rust-lang/rust#151729

[beta] Revert destabilise target-spec-json This reverts #150151 in order to deal with #151729 where the destabilization caused a problem with building rustc itself with JSON target specs. There's a fix at #152677, but we would prefer to not backport that, and instead give ourselves more time to work out the kinks. Also, the destabilization was incomplete, and the rest of the changes are in 1.95 (#151534 and rust-lang/cargo#16557), so it would be nice to keep all the changes together in one release. This reverts commit a89683d, reversing changes made to 2f1bd3f.

ehuss added 3 commits January 24, 2026 17:30

Pass CliUnstable instead of bindeps

bee215d

This changes the index parsing code to pass around CliUnstable instead of the bindeps bool to make it easier to check for multiple unstable options.

rustbot assigned epage Jan 25, 2026

epage approved these changes Jan 25, 2026

View reviewed changes

epage added this pull request to the merge queue Jan 25, 2026

weihanglo approved these changes Jan 25, 2026

View reviewed changes

Merged via the queue into rust-lang:master with commit 3a1b3fc Jan 25, 2026
29 checks passed

rustbot removed the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jan 25, 2026

weihanglo mentioned this pull request Jan 27, 2026

Update cargo submodule rust-lang/rust#151764

Merged

rustbot added this to the 1.95.0 milestone Jan 31, 2026

ehuss mentioned this pull request Feb 15, 2026

Support JSON target specs in bootstrap rust-lang/rust#152677

Merged

ehuss mentioned this pull request Feb 16, 2026

[beta] Revert destabilise target-spec-json rust-lang/rust#152721

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add -Z json-target-spec#16557

Add -Z json-target-spec#16557
epage merged 3 commits intorust-lang:masterfrom
ehuss:z-target-spec-json

ehuss commented Jan 25, 2026

Uh oh!

rustbot commented Jan 25, 2026

Uh oh!

weihanglo left a comment •

edited by rustbot

Loading

Uh oh!

weihanglo commented Jan 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Comments

Conversation

ehuss commented Jan 25, 2026

How to test and review this PR?

Uh oh!

rustbot commented Jan 25, 2026

Uh oh!

weihanglo left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

weihanglo commented Jan 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Comments

weihanglo left a comment •

edited by rustbot

Loading