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

@@ -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<PathBuf> {
+pub fn build_documentation(workspace: &Path, package: Package, chip: Chip) -> Result<PathBuf> {
     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<semver::Ver
 pub fn windows_safe_path(path: &Path) -> 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())
+    }
+}

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(),