feat: add variants.yaml for troubleshooting (#439)

* misc: always log variants.yaml

* feat: store recipe under separate variant hash

* misc: update docs

* misc: rename dirs

* misc: change section

Author: nichmor

crates/pixi-build-backend/src/intermediate_backend.rs

@@ -336,6 +336,9 @@ where
         let mut outputs = Vec::new();
 
         let num_of_outputs = discovered_outputs.len();
+
+        let mut variants_saved = false;
+
         for discovered_output in discovered_outputs {
             let variant = discovered_output.used_vars;
             let hash = HashInfo::from_variant(&variant, &discovered_output.noarch_type);
@@ -377,17 +380,52 @@ where
                 &named_source.path,
             );
 
-            // Save intermediate recipe in the debug dir
-            let debug_path = directories.work_dir.join("recipe.yaml");
-            tokio_fs::create_dir_all(&directories.work_dir)
+            // Save intermediate recipe and the used variant
+            // in the work dir by hash of the variant
+            // and entire variants.yaml at the root of work_dir
+            let work_dir = &directories.work_dir;
+
+            let recipe_path = work_dir.join("recipe.yaml");
+            let variants_path = work_dir.join("variants.yaml");
+
+            let package_work_dir = work_dir.join("recipe").join(&hash.hash);
+            let package_recipe_path = package_work_dir.join("recipe.yaml");
+            let package_variant_path = package_work_dir.join("variants.yaml");
+
+            tokio_fs::create_dir_all(&package_work_dir)
+                .await
+                .into_diagnostic()?;
+
+            let recipe_yaml = generated_recipe.recipe.to_yaml_pretty().into_diagnostic()?;
+
+            tokio_fs::write(&package_recipe_path, &recipe_yaml)
                 .await
                 .into_diagnostic()?;
-            tokio_fs::write(
-                &debug_path,
-                generated_recipe.recipe.to_yaml_pretty().into_diagnostic()?,
-            )
-            .await
-            .into_diagnostic()?;
+
+            let variant_yaml = serde_yaml::to_string(&variant)
+                .into_diagnostic()
+                .context("failed to serialize variant to YAML")?;
+
+            tokio_fs::write(&package_variant_path, variant_yaml)
+                .await
+                .into_diagnostic()?;
+
+            // write the entire variants.yaml at the root of work_dir
+            if !variants_saved {
+                let variants = serde_yaml::to_string(&variant_config)
+                    .into_diagnostic()
+                    .context("failed to serialize variant config to YAML")?;
+
+                tokio_fs::write(&variants_path, variants)
+                    .await
+                    .into_diagnostic()?;
+
+                tokio_fs::write(&recipe_path, recipe_yaml)
+                    .await
+                    .into_diagnostic()?;
+
+                variants_saved = true;
+            }
 
             subpackages.insert(
                 recipe.package().name().clone(),
@@ -569,6 +607,7 @@ where
             recipe_path: Some(self.source_dir.join(&self.manifest_rel_path)),
         };
         let outputs = find_outputs_from_src(named_source.clone())?;
+
         let variant_config = VariantConfig {
             variants,
             pin_run_as_build: None,
@@ -591,17 +630,56 @@ where
             recipe_path,
         );
 
-        // Save intermediate recipe in the debug dir
-        let debug_path = directories.work_dir.join("recipe.yaml");
-        tokio_fs::create_dir_all(&directories.work_dir)
+        // Save intermediate recipe and the used variant
+        // in the work dir by hash of the variant
+        let variant = discovered_output.used_vars;
+
+        // Save intermediate recipe and the used variant
+        // in the work dir by hash of the variant
+        // and entire variants.yaml at the root of work_dir
+        let work_dir = &directories.work_dir;
+
+        let recipe_path = work_dir.join("recipe.yaml");
+        let variants_path = work_dir.join("variants.yaml");
+
+        let package_dir = directories
+            .work_dir
+            .join("recipe")
+            .join(&discovered_output.hash.hash);
+
+        let package_recipe_path = package_dir.join("recipe.yaml");
+        let package_variant_path = package_dir.join("variants.yaml");
+
+        tokio_fs::create_dir_all(&package_dir)
+            .await
+            .into_diagnostic()?;
+
+        let recipe_yaml = recipe.recipe.to_yaml_pretty().into_diagnostic()?;
+
+        tokio_fs::write(&package_recipe_path, &recipe_yaml)
+            .await
+            .into_diagnostic()?;
+
+        let variant_yaml = serde_yaml::to_string(&variant)
+            .into_diagnostic()
+            .context("failed to serialize variant to YAML")?;
+
+        tokio_fs::write(&package_variant_path, variant_yaml)
+            .await
+            .into_diagnostic()?;
+
+        // write the entire variants.yaml at the root of work_dir
+        let variants = serde_yaml::to_string(&variant_config)
+            .into_diagnostic()
+            .context("failed to serialize variant config to YAML")?;
+
+        tokio_fs::write(&variants_path, variants)
+            .await
+            .into_diagnostic()?;
+
+        tokio_fs::write(&recipe_path, recipe_yaml)
             .await
             .into_diagnostic()?;
-        tokio_fs::write(
-            &debug_path,
-            recipe.recipe.to_yaml_pretty().into_diagnostic()?,
-        )
-        .await
-        .into_diagnostic()?;
 
         let tool_config = Configuration::builder()
             .with_opt_cache_dir(self.cache_dir.clone())
@@ -627,7 +705,7 @@ where
                     virtual_packages: vec![],
                 },
                 hash: discovered_output.hash,
-                variant: discovered_output.used_vars.clone(),
+                variant,
                 directories,
                 channels: vec![],
                 channel_priority: Default::default(),

docs/index.md

@@ -47,6 +47,71 @@ Check out our [tutorial series](https://pixi.sh/latest/build/getting_started/) t
 
     Learn how pixi-build integrates with conda-forge's compiler infrastructure to provide cross-platform, ABI-compatible builds. Covers compiler configuration, platform-specific behavior, and available compiler options for supported backends.
 
+## 🔧 Troubleshooting
+
+### Rebuilding Generated Recipes
+
+When you build a package using `pixi build`, the build backends generate a complete rattler-build recipe that is stored in your project's build directory. This can be useful for debugging build issues or understanding exactly how your package is being built.
+
+### Recipe Locations
+
+The build backends generate recipes in two locations:
+
+#### 1. General Recipe (all outputs)
+
+```
+<your_project>/.pixi/build/work/<package-name>--<hash>/work/
+```
+
+This directory contains:
+
+- `recipe.yaml` - A general recipe that can build all package outputs
+- `variants.yaml` - All variant configurations for the package
+
+#### 2. Variant-Specific Recipe (single output)
+
+```
+<your_project>/.pixi/build/work/<package-name>--<hash>/work/recipe/<variant_hash>/
+```
+
+This directory contains:
+
+- `recipe.yaml` - The complete rattler-build recipe generated by the build backend
+- `variants.yaml` - The variant configuration used for this specific build
+
+### Rebuilding a Package
+
+To debug or rebuild a package using the same configuration, you have two options:
+
+### Option 1: Navigate to the recipe directory
+
+1. Navigate to the recipe directory:
+   ```bash
+   cd .pixi/build/work/<package-name>--<hash>/work/recipe/<variant_hash>/
+   ```
+
+2. Use `rattler-build` to rebuild the package:
+   ```bash
+   rattler-build build
+   ```
+
+### Option 2: Point to the recipe directory
+
+Use the `--recipe` flag to build without changing directories:
+
+```bash
+rattler-build build --recipe .pixi/build/work/<package-name>--<hash>/work/recipe/<variant_hash>/
+```
+
+This allows you to:
+
+* Inspect the exact recipe that was generated
+* Debug build failures with direct access to `rattler-build`
+* Understand how the build backend translated your project model (`pixi.toml`)
+
+!!! tip
+    The `<variant_hash>` ensures that each unique combination of build variants gets its own recipe directory, making it easy to compare different build configurations.
+
 ## 🔗 Useful Links
 
 - [GitHub](https://github.com/prefix-dev/pixi): Pixi source code, feel free to leave a star!