feat: Allow for build_string_prefix passed into packages (#2384)

Author: hunger

crates/rattler_build_recipe/src/variant_render.rs

@@ -106,6 +106,12 @@ pub struct RenderConfig {
     /// like `MACOSX_DEPLOYMENT_TARGET` on macOS that have default values but can be
     /// customized via variant config.
     pub os_env_var_keys: HashSet<String>,
+    /// An optional prefix to prepend to the auto-generated build string.
+    /// When set, the build string becomes `{prefix}_{default_build_string}`.
+    pub build_string_prefix: Option<String>,
+    /// An optional build number override.
+    /// When set, this replaces the build number from the recipe.
+    pub build_number_override: Option<u64>,
 }
 
 impl Default for RenderConfig {
@@ -118,6 +124,8 @@ impl Default for RenderConfig {
             build_platform: rattler_conda_types::Platform::current(),
             host_platform: rattler_conda_types::Platform::current(),
             os_env_var_keys: HashSet::new(),
+            build_string_prefix: None,
+            build_number_override: None,
         }
     }
 }
@@ -175,6 +183,18 @@ impl RenderConfig {
         self.os_env_var_keys = keys;
         self
     }
+
+    /// Set a prefix to prepend to the auto-generated build string.
+    pub fn with_build_string_prefix(mut self, prefix: impl Into<String>) -> Self {
+        self.build_string_prefix = Some(prefix.into());
+        self
+    }
+
+    /// Override the build number from the recipe.
+    pub fn with_build_number_override(mut self, build_number: u64) -> Self {
+        self.build_number_override = Some(build_number);
+        self
+    }
 }
 
 /// Result of rendering a recipe with a specific variant combination
@@ -978,7 +998,7 @@ fn render_with_empty_combinations(
         results[i].pin_subpackages = pin_subpackages;
 
         // Finalize build string with complete pin information
-        finalize_build_string_single(&mut results[i])?;
+        finalize_build_string_single(&mut results[i], config)?;
     }
 
     Ok(results)
@@ -988,11 +1008,25 @@ fn render_with_empty_combinations(
 ///
 /// This computes the hash from the variant (which includes pin information)
 /// and resolves the build string for one variant.
-fn finalize_build_string_single(result: &mut RenderedVariant) -> Result<(), RenderError> {
+fn finalize_build_string_single(
+    result: &mut RenderedVariant,
+    config: &RenderConfig,
+) -> Result<(), RenderError> {
+    let build_string_prefix = config.build_string_prefix.as_deref();
     let noarch = result.recipe.build.noarch.unwrap_or(NoArchType::none());
 
     // Compute hash from the variant (which now includes pin_subpackage information)
-    let hash_info = HashInfo::from_variant(&result.variant, &noarch);
+    let mut hash_info = HashInfo::from_variant(&result.variant, &noarch);
+
+    // Prepend the user-provided build string prefix to the hash prefix so it
+    // becomes part of the default build string format: {prefix}h{hash}_{number}.
+    if let Some(prefix) = build_string_prefix {
+        if hash_info.prefix.is_empty() {
+            hash_info.prefix = format!("{prefix}_");
+        } else {
+            hash_info.prefix = format!("{prefix}_{}", hash_info.prefix);
+        }
+    }
 
     // If build string is not set (Default), or if it needs resolving
     if matches!(
@@ -1018,6 +1052,11 @@ fn finalize_build_string_single(result: &mut RenderedVariant) -> Result<(), Rend
 
         let eval_ctx = EvaluationContext::from_variables(variables);
 
+        // Apply the build number override if provided.
+        if let Some(bn) = config.build_number_override {
+            result.recipe.build.number = Some(bn);
+        }
+
         // Resolve the build string template with the hash
         result.recipe.build.string.resolve(
             &hash_info,
@@ -1395,7 +1434,7 @@ fn render_with_variants(
         results[i].pin_subpackages = pin_subpackages;
 
         // Finalize build string with complete pin information
-        finalize_build_string_single(&mut results[i])?;
+        finalize_build_string_single(&mut results[i], &config)?;
     }
 
     Ok(results)
@@ -3035,4 +3074,201 @@ postgresql:
         // postgresql 16 should be skipped (<=16), 17 should build
         assert_eq!(skip_flags, vec![("16".into(), true), ("17".into(), false)]);
     }
+
+    #[test]
+    fn test_build_string_prefix_simple() {
+        let recipe_yaml = r#"
+package:
+  name: test-pkg
+  version: "1.0.0"
+"#;
+        let stage0_recipe = stage0::parse_recipe_or_multi_from_source(recipe_yaml).unwrap();
+        let variant_config = VariantConfig::default();
+
+        let config = RenderConfig::new().with_build_string_prefix("foobar");
+        let rendered =
+            render_recipe_with_variant_config(&stage0_recipe, &variant_config, config).unwrap();
+
+        assert_eq!(rendered.len(), 1);
+        let build_string = rendered[0]
+            .recipe
+            .build
+            .string
+            .as_resolved()
+            .unwrap()
+            .to_string();
+        assert!(
+            build_string.starts_with("foobar_h"),
+            "build string should start with 'foobar_h', got '{build_string}'"
+        );
+    }
+
+    #[test]
+    fn test_build_string_prefix_with_variants() {
+        let recipe_yaml = r#"
+package:
+  name: test-pkg
+  version: "1.0.0"
+
+requirements:
+  host:
+    - python ${{ python }}
+  run:
+    - python
+"#;
+        let variant_yaml = r#"
+python:
+  - "3.9.*"
+  - "3.10.*"
+"#;
+        let stage0_recipe = stage0::parse_recipe_or_multi_from_source(recipe_yaml).unwrap();
+        let variant_config = VariantConfig::from_yaml_str(variant_yaml).unwrap();
+
+        let config = RenderConfig::new().with_build_string_prefix("myprefix");
+        let rendered =
+            render_recipe_with_variant_config(&stage0_recipe, &variant_config, config).unwrap();
+
+        assert_eq!(rendered.len(), 2);
+        for variant in &rendered {
+            let build_string = variant
+                .recipe
+                .build
+                .string
+                .as_resolved()
+                .unwrap()
+                .to_string();
+            assert!(
+                build_string.starts_with("myprefix_"),
+                "build string should start with 'myprefix_', got '{build_string}'"
+            );
+        }
+
+        // The two variants should produce different build strings
+        let bs0 = rendered[0].recipe.build.string.as_resolved().unwrap();
+        let bs1 = rendered[1].recipe.build.string.as_resolved().unwrap();
+        assert_ne!(
+            bs0, bs1,
+            "different variants should produce different build strings"
+        );
+    }
+
+    #[test]
+    fn test_build_string_prefix_absent_gives_default() {
+        let recipe_yaml = r#"
+package:
+  name: test-pkg
+  version: "1.0.0"
+"#;
+        let stage0_recipe = stage0::parse_recipe_or_multi_from_source(recipe_yaml).unwrap();
+        let variant_config = VariantConfig::default();
+
+        let with_prefix = render_recipe_with_variant_config(
+            &stage0_recipe,
+            &variant_config,
+            RenderConfig::new().with_build_string_prefix("pfx"),
+        )
+        .unwrap();
+        let without_prefix =
+            render_recipe_with_variant_config(&stage0_recipe, &variant_config, RenderConfig::new())
+                .unwrap();
+
+        let bs_with = with_prefix[0].recipe.build.string.as_resolved().unwrap();
+        let bs_without = without_prefix[0].recipe.build.string.as_resolved().unwrap();
+
+        // The prefixed version should contain the unprefixed version
+        assert!(
+            bs_with.starts_with("pfx_"),
+            "prefixed build string should start with 'pfx_', got '{bs_with}'"
+        );
+        assert!(
+            bs_with.ends_with(bs_without),
+            "prefixed '{bs_with}' should end with default '{bs_without}'"
+        );
+    }
+
+    #[test]
+    fn test_build_number_override() {
+        let recipe_yaml = r#"
+package:
+  name: test-pkg
+  version: "1.0.0"
+
+build:
+  number: 5
+"#;
+        let stage0_recipe = stage0::parse_recipe_or_multi_from_source(recipe_yaml).unwrap();
+        let variant_config = VariantConfig::default();
+
+        // Without override — should use the recipe's build number (5)
+        let rendered_default =
+            render_recipe_with_variant_config(&stage0_recipe, &variant_config, RenderConfig::new())
+                .unwrap();
+        assert_eq!(rendered_default[0].recipe.build.number, Some(5));
+
+        // With override — should use 42
+        let rendered_override = render_recipe_with_variant_config(
+            &stage0_recipe,
+            &variant_config,
+            RenderConfig::new().with_build_number_override(42),
+        )
+        .unwrap();
+        assert_eq!(rendered_override[0].recipe.build.number, Some(42));
+
+        // Build string should contain the overridden build number
+        let bs = rendered_override[0]
+            .recipe
+            .build
+            .string
+            .as_resolved()
+            .unwrap();
+        assert!(
+            bs.ends_with("_42"),
+            "build string should end with '_42', got '{bs}'"
+        );
+    }
+
+    #[test]
+    fn test_build_number_override_default_recipe() {
+        let recipe_yaml = r#"
+package:
+  name: test-pkg
+  version: "1.0.0"
+"#;
+        let stage0_recipe = stage0::parse_recipe_or_multi_from_source(recipe_yaml).unwrap();
+        let variant_config = VariantConfig::default();
+
+        // Recipe has no build number (defaults to 0)
+        let rendered_default =
+            render_recipe_with_variant_config(&stage0_recipe, &variant_config, RenderConfig::new())
+                .unwrap();
+        let bs_default = rendered_default[0]
+            .recipe
+            .build
+            .string
+            .as_resolved()
+            .unwrap();
+        assert!(
+            bs_default.ends_with("_0"),
+            "default build string should end with '_0', got '{bs_default}'"
+        );
+
+        // Override to 7
+        let rendered_override = render_recipe_with_variant_config(
+            &stage0_recipe,
+            &variant_config,
+            RenderConfig::new().with_build_number_override(7),
+        )
+        .unwrap();
+        assert_eq!(rendered_override[0].recipe.build.number, Some(7));
+        let bs_override = rendered_override[0]
+            .recipe
+            .build
+            .string
+            .as_resolved()
+            .unwrap();
+        assert!(
+            bs_override.ends_with("_7"),
+            "overridden build string should end with '_7', got '{bs_override}'"
+        );
+    }
 }

docs/reference/cli/rattler-build/build.md

@@ -65,6 +65,10 @@ rattler-build build [OPTIONS]
 :  Continue building even if (one) of the packages fails to build. This is useful when building many packages with `--recipe-dir`.`
 
 ## Modifying result
+- <a id="arg---build-num" href="#arg---build-num">`--build-num <BUILD_NUM>`</a>
+:  Override the build number for all outputs (defaults to the build number in the recipe)
+- <a id="arg---build-string-prefix" href="#arg---build-string-prefix">`--build-string-prefix <BUILD_STRING_PREFIX>`</a>
+:  Prefix to prepend to the auto-generated build string (e.g. `--build-string-prefix my_prefix` produces `my_prefix_h1234_0`)
 - <a id="arg---package-format" href="#arg---package-format">`--package-format <PACKAGE_FORMAT>`</a>
 :  The package format to use for the build. Can be one of `tar-bz2` or
 `conda`. You can also add a compression level to the package format,
@@ -94,8 +98,6 @@ e.g. `tar-bz2:<number>` (from 1 to 9) or `conda:<number>` (from -7 to
 :  Allow symlinks in packages on Windows (defaults to false - symlinks are forbidden on Windows)
 - <a id="arg---exclude-newer" href="#arg---exclude-newer">`--exclude-newer <EXCLUDE_NEWER>`</a>
 :  Exclude packages newer than this date from the solver, in RFC3339 format (e.g. 2024-03-15T12:00:00Z)
-- <a id="arg---build-num" href="#arg---build-num">`--build-num <BUILD_NUM>`</a>
-:  Override the build number for all outputs (defaults to the build number in the recipe)
 
 ## Sandbox arguments
 - <a id="arg---sandbox" href="#arg---sandbox">`--sandbox`</a>

docs/reference/cli/rattler-build/publish.md

@@ -100,15 +100,15 @@ e.g. `tar-bz2:<number>` (from 1 to 9) or `conda:<number>` (from -7 to
 :  Allow symlinks in packages on Windows (defaults to false - symlinks are forbidden on Windows)
 - <a id="arg---exclude-newer" href="#arg---exclude-newer">`--exclude-newer <EXCLUDE_NEWER>`</a>
 :  Exclude packages newer than this date from the solver, in RFC3339 format (e.g. 2024-03-15T12:00:00Z)
-- <a id="arg---build-num" href="#arg---build-num">`--build-num <BUILD_NUM>`</a>
-:  Override the build number for all outputs (defaults to the build number in the recipe)
 
 ## Publishing
 - <a id="arg---to" href="#arg---to">`--to <TO>`</a>
 :  The channel or URL to publish the package to
 <br>**required**: `true`
 - <a id="arg---build-number" href="#arg---build-number">`--build-number <BUILD_NUMBER>`</a>
 :  Override the build number for all outputs. Use an absolute value (e.g., `--build-number=12`) or a relative bump (e.g., `--build-number=+1`). When using a relative bump, the highest build number from the target channel is used as the base
+- <a id="arg---build-string-prefix" href="#arg---build-string-prefix">`--build-string-prefix <BUILD_STRING_PREFIX>`</a>
+:  Prefix to prepend to the auto-generated build string (e.g. `--build-string-prefix my_prefix` produces `my_prefix_h1234_0`)
 - <a id="arg---force" href="#arg---force">`--force`</a>
 :  Force upload even if the package already exists (not recommended - may break lockfiles). Only works with S3, filesystem, Anaconda.org, and prefix.dev channels
 - <a id="arg---generate-attestation" href="#arg---generate-attestation">`--generate-attestation`</a>

py-rattler-build/rust/src/cli_api.rs

@@ -19,7 +19,7 @@ use crate::error::RattlerBuildError;
 use crate::run_async_task;
 
 #[pyfunction]
-#[pyo3(signature = (recipes, up_to, build_platform, target_platform, host_platform, channel, variant_config, variant_overrides=None, ignore_recipe_variants=false, render_only=false, with_solve=false, keep_build=false, no_build_id=false, package_format=None, compression_threads=None, io_concurrency_limit=None, no_include_recipe=false, test=None, output_dir=None, auth_file=None, channel_priority=None, skip_existing=None, noarch_build_platform=None, allow_insecure_host=None, continue_on_failure=false, error_prefix_in_binary=false, allow_symlinks_on_windows=false, allow_absolute_license_paths=false, exclude_newer=None, build_num=None, use_bz2=true, use_zstd=true, use_sharded=true))]
+#[pyo3(signature = (recipes, up_to, build_platform, target_platform, host_platform, channel, variant_config, variant_overrides=None, ignore_recipe_variants=false, render_only=false, with_solve=false, keep_build=false, no_build_id=false, package_format=None, compression_threads=None, io_concurrency_limit=None, no_include_recipe=false, test=None, output_dir=None, auth_file=None, channel_priority=None, skip_existing=None, noarch_build_platform=None, allow_insecure_host=None, continue_on_failure=false, error_prefix_in_binary=false, allow_symlinks_on_windows=false, allow_absolute_license_paths=false, exclude_newer=None, build_num=None, build_string_prefix=None, use_bz2=true, use_zstd=true, use_sharded=true))]
 #[allow(clippy::too_many_arguments)]
 pub fn build_recipes_py(
     recipes: Vec<PathBuf>,
@@ -52,6 +52,7 @@ pub fn build_recipes_py(
     allow_absolute_license_paths: bool,
     exclude_newer: Option<chrono::DateTime<chrono::Utc>>,
     build_num: Option<u64>,
+    build_string_prefix: Option<String>,
     use_bz2: bool,
     use_zstd: bool,
     use_sharded: bool,
@@ -137,6 +138,7 @@ pub fn build_recipes_py(
         allow_absolute_license_paths,
         exclude_newer,
         build_num,
+        build_string_prefix,
         None, // markdown_summary
     );
 

py-rattler-build/rust/src/render.rs

@@ -25,15 +25,18 @@ pub struct PyRenderConfig {
 #[pymethods]
 impl PyRenderConfig {
     /// Create a new render configuration with default settings
+    #[allow(clippy::too_many_arguments)]
     #[new]
-    #[pyo3(signature = (target_platform=None, build_platform=None, host_platform=None, experimental=false, recipe_path=None, extra_context=None))]
+    #[pyo3(signature = (target_platform=None, build_platform=None, host_platform=None, experimental=false, recipe_path=None, extra_context=None, build_string_prefix=None, build_number_override=None))]
     fn new(
         target_platform: Option<String>,
         build_platform: Option<String>,
         host_platform: Option<String>,
         experimental: bool,
         recipe_path: Option<PathBuf>,
         extra_context: Option<Bound<'_, PyDict>>,
+        build_string_prefix: Option<String>,
+        build_number_override: Option<u64>,
     ) -> PyResult<Self> {
         let target_platform = target_platform
             .map(|p| p.parse::<Platform>())
@@ -83,6 +86,8 @@ impl PyRenderConfig {
                 build_platform,
                 host_platform,
                 os_env_var_keys,
+                build_string_prefix,
+                build_number_override,
             },
         })
     }