From 014a04faad0307e733559fb8faa25c0dc7ef8eba Mon Sep 17 00:00:00 2001 From: Jesse Braham Date: Wed, 13 Nov 2024 23:38:50 -0800 Subject: [PATCH] Use correct toolchain when building documentation or running doctests via xtask (#2536) * Add an alias for `fmt-packages` (since I always get this wrong) * Use correct toolchain when building documentation or running doc tests --- xtask/src/lib.rs | 23 +++++++++++++++++------ xtask/src/main.rs | 36 ++++++++++++++++++------------------ 2 files changed, 35 insertions(+), 24 deletions(-) diff --git a/xtask/src/lib.rs b/xtask/src/lib.rs index a7d72b76cfd..a6cb19f5ecc 100644 --- a/xtask/src/lib.rs +++ b/xtask/src/lib.rs @@ -103,17 +103,18 @@ pub enum Version { } /// Build the documentation for the specified package and device. -pub fn build_documentation( - workspace: &Path, - package: Package, - chip: Chip, - target: &str, -) -> Result { +pub fn build_documentation(workspace: &Path, package: Package, chip: Chip) -> Result { let package_name = package.to_string(); let package_path = windows_safe_path(&workspace.join(&package_name)); log::info!("Building '{package_name}' documentation targeting '{chip}'"); + // Determine the appropriate build target for the given package and chip: + let target = target_triple(package, &chip)?; + + // We need `nightly` for building the docs, unfortunately: + let toolchain = if chip.is_xtensa() { "esp" } else { "nightly" }; + let mut features = vec![chip.to_string()]; let chip = Config::for_chip(&chip); @@ -122,6 +123,7 @@ pub fn build_documentation( // Build up an array of command-line arguments to pass to `cargo`: let builder = CargoArgsBuilder::default() + .toolchain(toolchain) .subcommand("doc") .target(target) .features(&features) @@ -659,3 +661,12 @@ pub fn package_version(workspace: &Path, package: Package) -> Result PathBuf { PathBuf::from(path.to_str().unwrap().to_string().replace("\\\\?\\", "")) } + +/// Return the target triple for a given package/chip pair. +pub fn target_triple(package: Package, chip: &Chip) -> Result<&str> { + if package == Package::EspLpHal { + chip.lp_target() + } else { + Ok(chip.target()) + } +} diff --git a/xtask/src/main.rs b/xtask/src/main.rs index a1c1e18e61e..8da10fbd4bd 100644 --- a/xtask/src/main.rs +++ b/xtask/src/main.rs @@ -12,6 +12,7 @@ use minijinja::Value; use strum::IntoEnumIterator; use xtask::{ cargo::{CargoAction, CargoArgsBuilder}, + target_triple, Metadata, Package, Version, @@ -35,13 +36,15 @@ enum Cli { /// Bump the version of the specified package(s). BumpVersion(BumpVersionArgs), /// Format all packages in the workspace with rustfmt + #[clap(alias = "format-packages")] FmtPackages(FmtPackagesArgs), /// Generate the eFuse fields source file from a CSV. GenerateEfuseFields(GenerateEfuseFieldsArgs), /// Lint all packages in the workspace with clippy LintPackages(LintPackagesArgs), /// Run doctests for specified chip and package. - RunDocTest(ExampleArgs), + #[clap(alias = "run-doc-test")] + RunDocTests(ExampleArgs), /// Run the given example for the specified chip. RunExample(ExampleArgs), /// Run all applicable tests or the specified test for a specified chip. @@ -177,7 +180,7 @@ fn main() -> Result<()> { Cli::FmtPackages(args) => fmt_packages(&workspace, args), Cli::GenerateEfuseFields(args) => generate_efuse_src(&workspace, args), Cli::LintPackages(args) => lint_packages(&workspace, args), - Cli::RunDocTest(args) => run_doctests(&workspace, args), + Cli::RunDocTests(args) => run_doc_tests(&workspace, args), Cli::RunElfs(args) => run_elfs(args), Cli::RunExample(args) => examples(&workspace, args, CargoAction::Run), Cli::RunTests(args) => tests(&workspace, args, CargoAction::Run), @@ -436,12 +439,9 @@ fn build_documentation_for_package( // Ensure that the package/chip combination provided are valid: validate_package_chip(&package, chip)?; - // Determine the appropriate build target for the given package and chip: - let target = target_triple(package, chip)?; - // Build the documentation for the specified package, targeting the // specified chip: - let docs_path = xtask::build_documentation(workspace, package, *chip, target)?; + let docs_path = xtask::build_documentation(workspace, package, *chip)?; ensure!( docs_path.exists(), @@ -458,6 +458,7 @@ fn build_documentation_for_package( // Create the output directory, and copy the built documentation into it: fs::create_dir_all(&output_path) .with_context(|| format!("Failed to create {}", output_path.display()))?; + copy_dir_all(&docs_path, &output_path).with_context(|| { format!( "Failed to copy {} to {}", @@ -812,16 +813,23 @@ fn run_elfs(args: RunElfArgs) -> Result<()> { Ok(()) } -fn run_doctests(workspace: &Path, args: ExampleArgs) -> Result<()> { +fn run_doc_tests(workspace: &Path, args: ExampleArgs) -> Result<()> { + let chip = args.chip; + let package_name = args.package.to_string(); let package_path = xtask::windows_safe_path(&workspace.join(&package_name)); - // Determine the appropriate build target for the given package and chip: - let target = target_triple(args.package, &args.chip)?; - let features = vec![args.chip.to_string()]; + // Determine the appropriate build target, and cargo features for the given + // package and chip: + let target = target_triple(args.package, &chip)?; + let features = vec![chip.to_string()]; + + // We need `nightly` for building the doc tests, unfortunately: + let toolchain = if chip.is_xtensa() { "esp" } else { "nightly" }; // Build up an array of command-line arguments to pass to `cargo`: let builder = CargoArgsBuilder::default() + .toolchain(toolchain) .subcommand("test") .arg("--doc") .arg("-Zdoctest-xcompile") @@ -842,14 +850,6 @@ fn run_doctests(workspace: &Path, args: ExampleArgs) -> Result<()> { // ---------------------------------------------------------------------------- // Helper Functions -fn target_triple(package: Package, chip: &Chip) -> Result<&str> { - if package == Package::EspLpHal { - chip.lp_target() - } else { - Ok(chip.target()) - } -} - fn validate_package_chip(package: &Package, chip: &Chip) -> Result<()> { ensure!( *package != Package::EspLpHal || chip.has_lp_core(),