Skip to content

Commit 14415c7

Browse files
tgross35tgross35
authored
Rollup merge of #146199 - Kobzol:bootstrap-cargo-doc, r=jieyouxu
Document Cargo with in-tree rustdoc Fixes https://rust-lang.zulipchat.com/#narrow/channel/266220-t-rustdoc/topic/nightly.20rust.20doc.20seem.20corrupted. r? `@jieyouxu` try-job: dist-x86_64-linux-alt
2 parents 6c699a3 + b5c139b commit 14415c7

File tree

3 files changed

+145
-27
lines changed

3 files changed

+145
-27
lines changed

‎src/bootstrap/src/core/build_steps/doc.rs

Lines changed: 64 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -965,9 +965,11 @@ macro_rules! tool_doc {
965965
(
966966
$tool: ident,
967967
$path: literal,
968-
$(rustc_private_tool = $rustc_private_tool:literal, )?
969-
$(is_library = $is_library:expr,)?
970-
$(crates = $crates:expr)?
968+
mode = $mode:expr
969+
$(, is_library = $is_library:expr )?
970+
$(, crates = $crates:expr )?
971+
// Subset of nightly features that are allowed to be used when documenting
972+
$(, allow_features: $allow_features:expr )?
971973
) => {
972974
#[derive(Debug, Clone, Hash, PartialEq, Eq)]
973975
pub struct $tool {
@@ -988,20 +990,29 @@ macro_rules! tool_doc {
988990

989991
fn make_run(run: RunConfig<'_>) {
990992
let target = run.target;
991-
let (build_compiler, mode) = if true $(&& $rustc_private_tool)? {
992-
// Rustdoc needs the rustc sysroot available to build.
993-
let compilers = RustcPrivateCompilers::new(run.builder, run.builder.top_stage, target);
994-
995-
// Build rustc docs so that we generate relative links.
996-
run.builder.ensure(Rustc::from_build_compiler(run.builder, compilers.build_compiler(), target));
997-
998-
(compilers.build_compiler(), Mode::ToolRustcPrivate)
999-
} else {
1000-
// bootstrap/host tools have to be documented with the stage 0 compiler
1001-
(prepare_doc_compiler(run.builder, run.builder.host_target, 1), Mode::ToolBootstrap)
993+
let build_compiler = match $mode {
994+
Mode::ToolRustcPrivate => {
995+
// Rustdoc needs the rustc sysroot available to build.
996+
let compilers = RustcPrivateCompilers::new(run.builder, run.builder.top_stage, target);
997+
998+
// Build rustc docs so that we generate relative links.
999+
run.builder.ensure(Rustc::from_build_compiler(run.builder, compilers.build_compiler(), target));
1000+
compilers.build_compiler()
1001+
}
1002+
Mode::ToolBootstrap => {
1003+
// bootstrap/host tools should be documented with the stage 0 compiler
1004+
prepare_doc_compiler(run.builder, run.builder.host_target, 1)
1005+
}
1006+
Mode::ToolTarget => {
1007+
// target tools should be documented with the in-tree compiler
1008+
prepare_doc_compiler(run.builder, run.builder.host_target, run.builder.top_stage)
1009+
}
1010+
_ => {
1011+
panic!("Unexpected tool mode for documenting: {:?}", $mode);
1012+
}
10021013
};
10031014

1004-
run.builder.ensure($tool { build_compiler, mode, target });
1015+
run.builder.ensure($tool { build_compiler, mode: $mode, target });
10051016
}
10061017

10071018
/// Generates documentation for a tool.
@@ -1032,6 +1043,15 @@ macro_rules! tool_doc {
10321043
source_type,
10331044
&[],
10341045
);
1046+
let allow_features = {
1047+
let mut _value = "";
1048+
$( _value = $allow_features; )?
1049+
_value
1050+
};
1051+
1052+
if !allow_features.is_empty() {
1053+
cargo.allow_features(allow_features);
1054+
}
10351055

10361056
cargo.arg("-Zskip-rustdoc-fingerprint");
10371057
// Only include compiler crates, no dependencies of those, such as `libc`.
@@ -1087,18 +1107,33 @@ macro_rules! tool_doc {
10871107
tool_doc!(
10881108
BuildHelper,
10891109
"src/build_helper",
1090-
rustc_private_tool = false,
1110+
mode = Mode::ToolBootstrap,
10911111
is_library = true,
10921112
crates = ["build_helper"]
10931113
);
1094-
tool_doc!(Rustdoc, "src/tools/rustdoc", crates = ["rustdoc", "rustdoc-json-types"]);
1095-
tool_doc!(Rustfmt, "src/tools/rustfmt", crates = ["rustfmt-nightly", "rustfmt-config_proc_macro"]);
1096-
tool_doc!(Clippy, "src/tools/clippy", crates = ["clippy_config", "clippy_utils"]);
1097-
tool_doc!(Miri, "src/tools/miri", crates = ["miri"]);
1114+
tool_doc!(
1115+
Rustdoc,
1116+
"src/tools/rustdoc",
1117+
mode = Mode::ToolRustcPrivate,
1118+
crates = ["rustdoc", "rustdoc-json-types"]
1119+
);
1120+
tool_doc!(
1121+
Rustfmt,
1122+
"src/tools/rustfmt",
1123+
mode = Mode::ToolRustcPrivate,
1124+
crates = ["rustfmt-nightly", "rustfmt-config_proc_macro"]
1125+
);
1126+
tool_doc!(
1127+
Clippy,
1128+
"src/tools/clippy",
1129+
mode = Mode::ToolRustcPrivate,
1130+
crates = ["clippy_config", "clippy_utils"]
1131+
);
1132+
tool_doc!(Miri, "src/tools/miri", mode = Mode::ToolRustcPrivate, crates = ["miri"]);
10981133
tool_doc!(
10991134
Cargo,
11001135
"src/tools/cargo",
1101-
rustc_private_tool = false,
1136+
mode = Mode::ToolTarget,
11021137
crates = [
11031138
"cargo",
11041139
"cargo-credential",
@@ -1110,27 +1145,30 @@ tool_doc!(
11101145
"crates-io",
11111146
"mdman",
11121147
"rustfix",
1113-
]
1148+
],
1149+
// Required because of the im-rc dependency of Cargo, which automatically opts into the
1150+
// "specialization" feature in its build script when it detects a nightly toolchain.
1151+
allow_features: "specialization"
11141152
);
1115-
tool_doc!(Tidy, "src/tools/tidy", rustc_private_tool = false, crates = ["tidy"]);
1153+
tool_doc!(Tidy, "src/tools/tidy", mode = Mode::ToolBootstrap, crates = ["tidy"]);
11161154
tool_doc!(
11171155
Bootstrap,
11181156
"src/bootstrap",
1119-
rustc_private_tool = false,
1157+
mode = Mode::ToolBootstrap,
11201158
is_library = true,
11211159
crates = ["bootstrap"]
11221160
);
11231161
tool_doc!(
11241162
RunMakeSupport,
11251163
"src/tools/run-make-support",
1126-
rustc_private_tool = false,
1164+
mode = Mode::ToolBootstrap,
11271165
is_library = true,
11281166
crates = ["run_make_support"]
11291167
);
11301168
tool_doc!(
11311169
Compiletest,
11321170
"src/tools/compiletest",
1133-
rustc_private_tool = false,
1171+
mode = Mode::ToolBootstrap,
11341172
is_library = true,
11351173
crates = ["compiletest"]
11361174
);

‎src/bootstrap/src/core/builder/cargo.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -533,7 +533,7 @@ impl Builder<'_> {
533533
if cmd_kind == Kind::Doc {
534534
let my_out = match mode {
535535
// This is the intended out directory for compiler documentation.
536-
Mode::Rustc | Mode::ToolRustcPrivate | Mode::ToolBootstrap => {
536+
Mode::Rustc | Mode::ToolRustcPrivate | Mode::ToolBootstrap | Mode::ToolTarget => {
537537
self.compiler_doc_out(target)
538538
}
539539
Mode::Std => {

‎src/bootstrap/src/core/builder/tests.rs

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1130,6 +1130,59 @@ mod snapshot {
11301130
);
11311131
}
11321132

1133+
#[test]
1134+
fn dist_compiler_docs() {
1135+
let ctx = TestCtx::new();
1136+
insta::assert_snapshot!(
1137+
ctx.config("dist")
1138+
.path("rustc-docs")
1139+
.args(&["--set", "build.compiler-docs=true"])
1140+
.render_steps(), @r"
1141+
[build] rustc 0 <host> -> UnstableBookGen 1 <host>
1142+
[build] rustc 0 <host> -> Rustbook 1 <host>
1143+
[doc] unstable-book (book) <host>
1144+
[build] llvm <host>
1145+
[build] rustc 0 <host> -> rustc 1 <host>
1146+
[build] rustc 1 <host> -> std 1 <host>
1147+
[doc] book (book) <host>
1148+
[doc] book/first-edition (book) <host>
1149+
[doc] book/second-edition (book) <host>
1150+
[doc] book/2018-edition (book) <host>
1151+
[build] rustdoc 1 <host>
1152+
[doc] rustc 1 <host> -> standalone 2 <host>
1153+
[doc] rustc 1 <host> -> std 1 <host> crates=[alloc,compiler_builtins,core,panic_abort,panic_unwind,proc_macro,rustc-std-workspace-core,std,std_detect,sysroot,test,unwind]
1154+
[doc] rustc 1 <host> -> rustc 2 <host>
1155+
[build] rustc 1 <host> -> rustc 2 <host>
1156+
[doc] rustc 1 <host> -> Rustdoc 2 <host>
1157+
[doc] rustc 1 <host> -> Rustfmt 2 <host>
1158+
[build] rustc 1 <host> -> error-index 2 <host>
1159+
[doc] rustc 1 <host> -> error-index 2 <host>
1160+
[doc] nomicon (book) <host>
1161+
[doc] rustc 1 <host> -> reference (book) 2 <host>
1162+
[doc] rustdoc (book) <host>
1163+
[doc] rust-by-example (book) <host>
1164+
[build] rustc 0 <host> -> LintDocs 1 <host>
1165+
[doc] rustc (book) <host>
1166+
[doc] rustc 1 <host> -> Cargo 2 <host>
1167+
[doc] cargo (book) <host>
1168+
[doc] rustc 1 <host> -> Clippy 2 <host>
1169+
[doc] clippy (book) <host>
1170+
[doc] rustc 1 <host> -> Miri 2 <host>
1171+
[doc] embedded-book (book) <host>
1172+
[doc] edition-guide (book) <host>
1173+
[doc] style-guide (book) <host>
1174+
[build] rustdoc 0 <host>
1175+
[doc] rustc 0 <host> -> Tidy 1 <host>
1176+
[doc] rustc 0 <host> -> Bootstrap 1 <host>
1177+
[doc] rustc 1 <host> -> releases 2 <host>
1178+
[doc] rustc 0 <host> -> RunMakeSupport 1 <host>
1179+
[doc] rustc 0 <host> -> BuildHelper 1 <host>
1180+
[doc] rustc 0 <host> -> Compiletest 1 <host>
1181+
[build] rustc 0 <host> -> RustInstaller 1 <host>
1182+
"
1183+
);
1184+
}
1185+
11331186
#[test]
11341187
fn dist_extended() {
11351188
let ctx = TestCtx::new();
@@ -2462,6 +2515,33 @@ mod snapshot {
24622515
");
24632516
}
24642517

2518+
#[test]
2519+
fn doc_cargo_stage_1() {
2520+
let ctx = TestCtx::new();
2521+
insta::assert_snapshot!(
2522+
ctx.config("doc")
2523+
.path("cargo")
2524+
.render_steps(), @r"
2525+
[build] rustdoc 0 <host>
2526+
[doc] rustc 0 <host> -> Cargo 1 <host>
2527+
");
2528+
}
2529+
#[test]
2530+
fn doc_cargo_stage_2() {
2531+
let ctx = TestCtx::new();
2532+
insta::assert_snapshot!(
2533+
ctx.config("doc")
2534+
.path("cargo")
2535+
.stage(2)
2536+
.render_steps(), @r"
2537+
[build] llvm <host>
2538+
[build] rustc 0 <host> -> rustc 1 <host>
2539+
[build] rustc 1 <host> -> std 1 <host>
2540+
[build] rustdoc 1 <host>
2541+
[doc] rustc 1 <host> -> Cargo 2 <host>
2542+
");
2543+
}
2544+
24652545
#[test]
24662546
fn doc_core() {
24672547
let ctx = TestCtx::new();

0 commit comments

Comments
 (0)