-
-
Notifications
You must be signed in to change notification settings - Fork 31
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.
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
Make cargo +custom public-api
build rustdoc JSON with toolchain custom
#113
Conversation
e7353f2
to
31a6225
Compare
7ff0ff1
to
3d31ee5
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thank you so much. Looking forward to collaborate with you to get this merged. I think this change makes sense.
At first I wasn't sure if the +
syntax was canonical, since typically +
means a different binary will be used (e.g. nightly rustdoc vs stable rustdoc), whereas in our case the same top-level binary is always used: "cargo-public-api". But I think this makes enough sense to go ahead with, because INDRECTLY a different rustdoc
binary is used.
Another inconsistency and potential source of confusion: omitting +
normally means "use stable", which is not the case for us. But again, I think we can get away with that.
I added some comments. I am by no means all-knowledgeble, so if you think I am on the wrong track on some or all of my comments, please speak up.
Thanks again! Looking forward to getting this merged after we have sorted out the open questions!
052c7aa
to
a553ad3
Compare
will squash if all looks good one comment from me as a contributor, I'd hugely recommend adding a |
a553ad3
to
47502aa
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thank you for the update! I did another review round and the new enum look good to me. Had some more questions/comments though.
cargo-public-api/src/main.rs
Outdated
@@ -135,6 +129,11 @@ struct PostProcessing { | |||
fn main_() -> Result<()> { | |||
let args = get_args(); | |||
|
|||
// check if using a stable compiler, and if not use nightly. | |||
if probably_stable() && std::env::var("CARGO_PUBLIC_API_NO_RUN_NIGHTLY").is_err() { | |||
std::env::set_var("RUSTUP_TOOLCHAIN", "nightly"); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Using cargo-expand
as a role model makes a lot of sense, but I am a bit confused, because when I git grep in cargo-expand
it does not seem to read RUSTUP_TOOLCHAIN
. Do you know if it uses some helper crate for that perhaps?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
cargo-expand
reruns itself but invoked as rustup run nightly cargo expand
(or simply put cargo +nightly expand
. It's not strictly needed, and setting RUSTUP_TOOLCHAIN=nightly
achieves the same result once a rustup shim is called.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I did a bit of a rushed review this morning since I wanted to give you some feedback before taking kids to school and going to my day job. I've done some more thinking during the day, and here is where my thoughts currently are:
My initial idea with FromRustupToolchainEnvVar
was to let the library read RUSTUP_TOOLCHAIN
. Shouldn't that work? I think that will allow us to get rid of the override
in CI. In fact, the current enum is only semantically different over Option<String>
, isn't it? Default
= None
, Named(foo)
= Some(foo)
.
Also, what is CARGO_PUBLIC_API_NO_RUN_NIGHTLY
about?
Again, I really appreciate you working on this, and I hope you don't mind us discussing this a bit back and forth.
I'll wait with another detailed review round until we have settled these higher-level questions.
I did see your other PRs 🎉 I will take a look right away!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why would the library read RUSTUP_TOOLCHAIN
? It's already set in env, and doing cargo +$RUSTUP_TOOLCHAIN <cmd>
just does the same thing as cargo <cmd>
CARGO_PUBLIC_API_NO_RUN_NIGHTLY
is for not setting the toolchain to nightly if the current toolchain is stable, this is to make it possible to use a stable compiler with the binary. Technically not needed, as -Z unstable-options
will always need a unstable toolchain
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Shouldn't that work? I think that will allow us to get rid of the override in CI
Try running cargo test
with a stable toolchain and you'll see the issue.
❯ cargo test
Compiling rustdoc-json v0.3.1 (/Users/emil/workspace/cargo-public-api/rustdoc-json)
Compiling cargo-public-api v0.14.0 (/Users/emil/workspace/cargo-public-api/cargo-public-api)
Compiling public-api v0.15.0 (/Users/emil/workspace/cargo-public-api/public-api)
Finished test [unoptimized + debuginfo] target(s) in 2.51s
Running unittests src/lib.rs (target/debug/deps/cargo_public_api-cad645bec020de87)
running 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Running unittests src/main.rs (target/debug/deps/cargo_public_api-fdca03bee1ae1ceb)
running 3 tests
test arg_types::tests::test_deny_added ... ok
test arg_types::tests::test_deny_changed ... ok
test arg_types::tests::test_deny_removed ... ok
test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Running tests/cargo-public-api-bin-tests.rs (target/debug/deps/cargo_public_api_bin_tests-9b155849dae31082)
running 31 tests
test deny_with_invalid_arg ... ok
test deny_added_when_not_diffing ... ok
test deny_when_not_diffing ... ok
test deny_removed_when_not_diffing ... ok
test deny_changed_when_not_diffing ... ok
test deny_combination_when_not_diffing ... ok
test diff_public_items_from_files ... ok
test diff_public_items_missing_one_arg ... ok
test deny_removed_with_diff ... ok
test deny_added_with_diff ... ok
test deny_without_diff ... ok
test deny_changed_with_diff ... ok
test deny_with_diff ... ok
test diff_public_items_without_git_root ... ok
test diff_public_items_with_dirty_tree_fails ... ok
test diff_public_items_markdown ... ok
test diff_public_items ... ok
test long_help ... ok
test short_help ... ok
test diff_public_items_markdown_no_changes ... ok
test diff_public_items_detached_head ... ok
test virtual_manifest_error ... ok
test diff_public_items_with_color ... ok
test list_public_items ... ok
test diff_public_items_with_manifest_path ... ok
test list_public_items_with_lint_error ... ok
test list_public_items_markdown ... ok
test list_public_items_explicit_manifest_path ... ok
test target_arg ... ok
test list_public_items_with_color ... ok
test verbose ... ok
test result: ok. 31 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 4.62s
Running tests/cargo-public-api-readme-tests.rs (target/debug/deps/cargo_public_api_readme_tests-3dafe32ee512dee9)
running 1 test
test installation_instructions_mentions_minimum_rustdoc_json_version ... ok
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Running unittests src/lib.rs (target/debug/deps/public_api-bda5eb184e903f0e)
running 25 tests
test diff::tests::no_diff_means_empty_diff ... ok
test diff::tests::single_and_only_item_removed ... ok
test diff::tests::middle_item_added ... ok
test diff::tests::middle_item_removed ... ok
test diff::tests::single_and_only_item_added ... ok
test render::test::test_type_generic ... ok
test render::test::test_type_infer ... ok
test render::test::test_type_array ... ok
test render::test::test_type_path ... ok
test diff::tests::no_off_by_one_diff_skewing ... ok
test render::test::test_type_pointer ... ok
test render::test::test_type_pointer_mut ... ok
test render::test::test_type_primitive ... ok
test diff::tests::many_identical_items ... ok
test render::test::test_type_ref ... ok
test render::test::test_type_ref_lt ... ok
test render::test::test_type_ref_lt_mut ... ok
test render::test::test_type_ref_mut ... ok
test render::test::test_type_resolved_crate_name ... ok
test render::test::test_type_resolved_long_name ... ok
test render::test::test_type_resolved_simple ... ok
test render::test::test_type_slice ... ok
test render::test::test_type_resolved_name_crate ... ok
test render::test::test_type_tuple_empty ... ok
test render::test::test_type_tuple ... ok
test result: ok. 25 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Running unittests src/main.rs (target/debug/deps/public_api-67745131aabc0095)
running 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Running tests/public-api-bin-tests.rs (target/debug/deps/public_api_bin_tests-7c1cbce8c2f73565)
running 10 tests
error: the option `Z` is only accepted on the nightly compiler
error: the option `Z` is only accepted on the nightly compiler
error: could not document `example_api`
Caused by:
process didn't exit successfully: `rustdoc --edition=2021 --crate-type lib --crate-name example_api src/lib.rs -o /Users/emil/workspace/cargo-public-api/test-apis/example_api-v0.1.0/target/doc --error-format=json --json=diagnostic-rendered-ansi,artifacts,future-incompat -Z unstable-options --output-format json --cap-lints warn -C metadata=e7754d7af416a103 -L dependency=/Users/emil/workspace/cargo-public-api/test-apis/example_api-v0.1.0/target/debug/deps --crate-version 0.1.0` (exit status: 1)
error: could not document `example_api`
Caused by:
process didn't exit successfully: `rustdoc --edition=2021 --crate-type lib --crate-name example_api src/lib.rs -o /Users/emil/workspace/cargo-public-api/test-apis/example_api-v0.2.0/target/doc --error-format=json --json=diagnostic-rendered-ansi,artifacts,future-incompat -Z unstable-options --output-format json --cap-lints warn -C metadata=f9e99507877cdd94 -L dependency=/Users/emil/workspace/cargo-public-api/test-apis/example_api-v0.2.0/target/debug/deps --crate-version 0.2.0` (exit status: 1)
test print_diff ... FAILED
test print_public_api_with_blanket_implementations ... FAILED
test no_args_shows_help ... ok
test long_help ... ok
test too_many_args_shows_help ... ok
test short_help ... ok
error: the option `Z` is only accepted on the nightly compiler
error: could not document `example_api`
Caused by:
process didn't exit successfully: `rustdoc --edition=2021 --crate-type lib --crate-name example_api src/lib.rs -o /Users/emil/workspace/cargo-public-api/test-apis/example_api-v0.2.0/target/doc --error-format=json --json=diagnostic-rendered-ansi,artifacts,future-incompat -Z unstable-options --output-format json --cap-lints warn -C metadata=f9e99507877cdd94 -L dependency=/Users/emil/workspace/cargo-public-api/test-apis/example_api-v0.2.0/target/debug/deps --crate-version 0.2.0` (exit status: 1)
test print_diff_reversed ... FAILED
error: the option `Z` is only accepted on the nightly compiler
error: could not document `comprehensive_api`
Caused by:
process didn't exit successfully: `rustdoc --edition=2021 --crate-type lib --crate-name comprehensive_api src/lib.rs -o /Users/emil/workspace/cargo-public-api/test-apis/comprehensive_api/target/doc --error-format=json --json=diagnostic-rendered-ansi,artifacts,future-incompat -Z unstable-options --output-format json --cap-lints warn -C metadata=cc391f1f93a5e47e -L dependency=/Users/emil/workspace/cargo-public-api/test-apis/comprehensive_api/target/debug/deps --extern rand=/Users/emil/workspace/cargo-public-api/test-apis/comprehensive_api/target/debug/deps/librand-c26db38e8be2dce6.rmeta --crate-version 0.1.0` (exit status: 1)
test broken_pipe ... FAILED
error: the option `Z` is only accepted on the nightly compiler
error: could not document `example_api`
Caused by:
process didn't exit successfully: `rustdoc --edition=2021 --crate-type lib --crate-name example_api src/lib.rs -o /Users/emil/workspace/cargo-public-api/test-apis/example_api-v0.2.0/target/doc --error-format=json --json=diagnostic-rendered-ansi,artifacts,future-incompat -Z unstable-options --output-format json --cap-lints warn -C metadata=f9e99507877cdd94 -L dependency=/Users/emil/workspace/cargo-public-api/test-apis/example_api-v0.2.0/target/debug/deps --crate-version 0.2.0` (exit status: 1)
test print_no_diff ... FAILED
error: the option `Z` is only accepted on the nightly compiler
error: could not document `comprehensive_api`
Caused by:
process didn't exit successfully: `rustdoc --edition=2021 --crate-type lib --crate-name comprehensive_api src/lib.rs -o /Users/emil/workspace/cargo-public-api/test-apis/comprehensive_api/target/doc --error-format=json --json=diagnostic-rendered-ansi,artifacts,future-incompat -Z unstable-options --output-format json --cap-lints warn -C metadata=cc391f1f93a5e47e -L dependency=/Users/emil/workspace/cargo-public-api/test-apis/comprehensive_api/target/debug/deps --extern rand=/Users/emil/workspace/cargo-public-api/test-apis/comprehensive_api/target/debug/deps/librand-c26db38e8be2dce6.rmeta --crate-version 0.1.0` (exit status: 1)
test print_public_api ... FAILED
failures:
---- print_diff stdout ----
thread 'print_diff' panicked at 'called `Result::unwrap()` on an `Err` value: General("See above")', public-api/tests/utils/mod.rs:16:6
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
---- print_public_api_with_blanket_implementations stdout ----
thread 'print_public_api_with_blanket_implementations' panicked at 'called `Result::unwrap()` on an `Err` value: General("See above")', public-api/tests/utils/mod.rs:16:6
---- print_diff_reversed stdout ----
thread 'print_diff_reversed' panicked at 'called `Result::unwrap()` on an `Err` value: General("See above")', public-api/tests/utils/mod.rs:16:6
---- broken_pipe stdout ----
thread 'broken_pipe' panicked at 'called `Result::unwrap()` on an `Err` value: General("See above")', public-api/tests/utils/mod.rs:16:6
---- print_no_diff stdout ----
thread 'print_no_diff' panicked at 'called `Result::unwrap()` on an `Err` value: General("See above")', public-api/tests/utils/mod.rs:16:6
---- print_public_api stdout ----
thread 'print_public_api' panicked at 'called `Result::unwrap()` on an `Err` value: General("See above")', public-api/tests/utils/mod.rs:16:6
failures:
broken_pipe
print_diff
print_diff_reversed
print_no_diff
print_public_api
print_public_api_with_blanket_implementations
test result: FAILED. 4 passed; 6 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.21s
I don't think it makes sense to run the tests using another toolchain than the current one.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ah, right, I didn't consider the effect of RUSTUP_TOOLCHAIN
being inherited by the cargo
process spawned from inside rustdoc_json
. But in that case, why do we need to change the rustdoc_json
API at all? I think it makes sense to still be able to manually specify a toolchain with the lib, because that has higher prio than RUSTUP_TOOLCHAIN
when looking at https://rust-lang.github.io/rustup/overrides.html.
And if we do that, I wonder if it wouldn't be more elegant to pass +nightly
as toolchain
from cargo-public-api
if probably_stable()
, instead of setting RUSTUP_TOOLCHAIN
?
And do we even need probably_stable()
in its current "complicated" form? Couldn't we just check if RUSTUP_TOOLCHAIN
is "stable" inside of it?
When I run
cargo +nightly run -- --manifest-path cargo-public-api/Cargo.toml
I get:
RUSTUP_TOOLCHAIN=nightly-aarch64-apple-darwin
in the env, and with
cargo run -- --manifest-path cargo-public-api/Cargo.toml
I get
RUSTUP_TOOLCHAIN=1.63-aarch64-apple-darwin
Seems like we can use that instead of running cargo
inside of probably_stable()
.
I added this in main.rs to inspect env:
std::process::Command::new("env").spawn().unwrap().wait().unwrap();
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The problem with using RUSTUP_TOOLCHAIN
is that it gives no real information about the version of the toolchain. --version
or reading the multirust-channel-manifest.toml
file is the only reliable way (and reading multirust-channel-manifest.toml
only works on normal toolchains, not linked ones (rustup toolchain link
))
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it makes sense to still be able to manually specify a toolchain with the lib
...
And if we do that, I wonder if it wouldn't be more elegant to pass +nightly as toolchain from cargo-public-api if probably_stable(), instead of setting RUSTUP_TOOLCHAIN?
I'd then have to reintroduce the --toolchain
flag to be able to hand it down, or have it as a argument to some methods. Could also keep it but make it hidden (and unsettable)
also, the overrides doc is a bit misleading here. +toolchain
only has one effect, setting the RUSTUP_TOOLCHAIN
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've readded toolchain but made it skipped by clap
.github/workflows/CI.yml
Outdated
@@ -48,6 +48,7 @@ jobs: | |||
with: | |||
toolchain: nightly | |||
profile: minimal | |||
override: true |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You forgot to remove this it seems?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It needs to be left in as (some of) the tests assume that the toolchain is changed in the code, but the toolchain is only changed in main_
and not in the tests
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Isn't that solved by not stopping to specify +nightly
? See other comment
@@ -34,13 +34,6 @@ fn list_public_items_with_lint_error() { | |||
.success(); | |||
} | |||
|
|||
#[test] | |||
fn custom_toolchain() { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd like us to keep this test since it is important to make sure that cargo public-api
can use a custom toolchain. Couldn't we just change invocation here to match? If it becomes a non-sensical test to test with +nightly
I think we should also install nightly-2022-08-15
(current MINIMUM_RUSTDOC_JSON_VERSION
) so we can pass that instead.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
what about
#[test]
#[ignore]
fn minimum_toolchain() {
// set BuildOptions.toolchain to `nightly-2022-08-15`, do the other stuff.
}
Adding a CI test for this makes sense
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I opted with adding this to test-invocation-variants.sh
8e23927
to
32e7110
Compare
cargo +toolchain public-api
and deprecate --toolchain
specifiercargo +toolchain public-api
So far I have deliberately stayed away from enforcing lints in code, because that makes e.g. I weight your input as a contributor very high, so I will add Feel free to create a PR for that too! (But you are absolutely not required to do so of course, I will do it myself as soon as I get time) |
Yep, deny in code is generally bad, warn is fine though. See https://github.com/rust-unofficial/patterns/blob/main/anti_patterns/deny-warnings.md using deny can also make it so that consumers will fail if new lints are added and you deny on a group (like |
.github/workflows/CI.yml
Outdated
@@ -48,6 +48,7 @@ jobs: | |||
with: | |||
toolchain: nightly | |||
profile: minimal | |||
override: true |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Isn't that solved by not stopping to specify +nightly
? See other comment
cargo-public-api/src/main.rs
Outdated
@@ -135,6 +129,11 @@ struct PostProcessing { | |||
fn main_() -> Result<()> { | |||
let args = get_args(); | |||
|
|||
// check if using a stable compiler, and if not use nightly. | |||
if probably_stable() && std::env::var("CARGO_PUBLIC_API_NO_RUN_NIGHTLY").is_err() { | |||
std::env::set_var("RUSTUP_TOOLCHAIN", "nightly"); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ah, right, I didn't consider the effect of RUSTUP_TOOLCHAIN
being inherited by the cargo
process spawned from inside rustdoc_json
. But in that case, why do we need to change the rustdoc_json
API at all? I think it makes sense to still be able to manually specify a toolchain with the lib, because that has higher prio than RUSTUP_TOOLCHAIN
when looking at https://rust-lang.github.io/rustup/overrides.html.
And if we do that, I wonder if it wouldn't be more elegant to pass +nightly
as toolchain
from cargo-public-api
if probably_stable()
, instead of setting RUSTUP_TOOLCHAIN
?
And do we even need probably_stable()
in its current "complicated" form? Couldn't we just check if RUSTUP_TOOLCHAIN
is "stable" inside of it?
When I run
cargo +nightly run -- --manifest-path cargo-public-api/Cargo.toml
I get:
RUSTUP_TOOLCHAIN=nightly-aarch64-apple-darwin
in the env, and with
cargo run -- --manifest-path cargo-public-api/Cargo.toml
I get
RUSTUP_TOOLCHAIN=1.63-aarch64-apple-darwin
Seems like we can use that instead of running cargo
inside of probably_stable()
.
I added this in main.rs to inspect env:
std::process::Command::new("env").spawn().unwrap().wait().unwrap();
29c2f03
to
fd28fb2
Compare
One thing I could do, is set the tests
behind a use rustc_version::{version, version_meta, Channel};
fn main() {
// Assert we haven't travelled back in time
assert!(version().unwrap().major >= 1);
if matches!(version_meta().unwrap().channel, Channel::Nightly | Channel::Dev) {
println!("cargo:rustc-cfg=nightly");
}
} |
This is prototype quality code that is heavily influenced by #113 and a large portion of credit should be given to @Emilgardis
It became too complex to continue with code review comments to communicate my vision for how to solve this problem, so I wrote some code instead: #119 Looking forward to your input! |
09a8119
to
02fe3e0
Compare
I've revamped this a bit, I now understand what you were going for with your comments after seeing #119 and I think this should satisfy that now |
02fe3e0
to
da7def5
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I did another review round. No big remarks. Thanks!
After comments have been addressed I think we can merge this, unless anyone of us thinks of more things to tweak.
dfeff2e
to
2078490
Compare
Co-authored-by: Martin Nordholts <[email protected]>
2078490
to
a4945ab
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thank you! Let's merge!
I plan to make a release in the coming days. I think I'll do some minor cleanups first, like adding more elaborate --help texts to all new CLI args.
But it should not take many days for a release to happen.
Thank you again for your large batch of very useful PRs :)
cargo +toolchain public-api
cargo +custom public-api
build rustdoc JSON with toolchain custom
Meh, who wants to wait for releases? Not me. Released as https://github.com/Enselic/cargo-public-api/releases/tag/v0.15.0 (🥳) |
When using rustup shims, rustup sets and uses the
RUSTUP_TOOLCHAIN
variable which rustup and its shims use to get the specified or defaulted+toolchain
.With this change,
cargo +nightly public-api
orcargo +stage2 public-api
etc. will work as expected.This pr deprecates the
--toolchain
command as it's no longer needed.