fix: resolve overlinking false positives for staging outputs

When a package output inherits from a staging cache, the staging
cache's host dependencies aren't installed in the prefix during
overlinking checks. This means libraries like libz.so.1 can't be
attributed to zlib, even though zlib is a run dependency via inherited
run_exports.

Fix: at staging build time, capture a LibraryNameMap (filename to
package mapping) from PrefixInfo while conda-meta still exists. Store
it in the staging cache metadata, thread it to BuildOutput, and use it
as a fallback in perform_linking_checks when resolve_libraries can't
find the library on disk.

Fixes #2186

Supersedes #2210


test: add e2e test for staging overlinking check

Author: Hofer-Julian

crates/rattler_build_core/src/build.rs

@@ -136,10 +136,12 @@ pub async fn run_build(
     // This will build or restore staging caches and return their dependencies/sources if inherited
     let staging_result = output.process_staging_caches(tool_configuration).await?;
 
-    // If we inherit from a staging cache, store its dependencies and sources
-    if let Some((deps, sources)) = staging_result {
+    // If we inherit from a staging cache, store its dependencies, sources, and
+    // library name map for overlinking checks
+    if let Some((deps, sources, library_name_map)) = staging_result {
         output.finalized_cache_dependencies = Some(deps);
         output.finalized_cache_sources = Some(sources);
+        output.staging_library_name_map = Some(library_name_map);
     }
 
     // Fetch sources for this output

crates/rattler_build_core/src/post_process/checks.rs

@@ -528,6 +528,7 @@ pub fn perform_linking_checks(
     let system_libs = find_system_libs(output)?;
 
     let prefix_info = PrefixInfo::from_prefix(output.prefix())?;
+    let staging_lib_map = output.staging_library_name_map.as_ref();
 
     let host_dso_packages = host_run_export_dso_packages(output, &prefix_info.package_to_nature);
     tracing::trace!("Host run_export DSO packages: {host_dso_packages:#?}",);
@@ -644,6 +645,26 @@ pub fn perform_linking_checks(
                 );
             }
 
+            // Fallback: if the library couldn't be resolved on disk (e.g. from
+            // a staging cache whose host deps are not installed), try to match
+            // it by filename against the cached library name map.
+            if let Some(lib_map) = staging_lib_map
+                && let Some(providing_package) = lib_map.find_package(lib)
+                && run_dependency_names.contains(&providing_package)
+            {
+                tracing::debug!(
+                    "Library {lib:?} matched to '{}' via staging library name map",
+                    providing_package.as_normalized()
+                );
+                link_info.linked_packages.push(LinkedPackage {
+                    name: lib.to_path_buf(),
+                    link_origin: LinkOrigin::ForeignPackage(
+                        providing_package.as_normalized().to_string(),
+                    ),
+                });
+                continue;
+            }
+
             // Check if the library is one of the system libraries (i.e. comes from sysroot).
             if system_libs.allow.is_match(lib) && !system_libs.deny.is_match(lib) {
                 link_info.linked_packages.push(LinkedPackage {

crates/rattler_build_core/src/post_process/package_nature.rs

@@ -215,6 +215,72 @@ impl PrefixInfo {
     }
 }
 
+/// A mapping from shared library filenames to the package that provides them.
+///
+/// This is used as a fallback during overlinking checks when the staging
+/// cache's host dependencies are not physically installed in the prefix.
+/// Instead of requiring files on disk, this allows name-based attribution
+/// of libraries to packages.
+#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]
+pub struct LibraryNameMap {
+    /// Maps library filenames (e.g. "libz.so.1", "libz.1.dylib") to the
+    /// package name that provides them.
+    pub library_to_package: HashMap<String, PackageName>,
+}
+
+impl LibraryNameMap {
+    /// Build a `LibraryNameMap` from a `PrefixInfo` by extracting the
+    /// filenames of all files that look like shared objects.
+    pub(crate) fn from_prefix_info(prefix_info: &PrefixInfo) -> Self {
+        let mut library_to_package = HashMap::new();
+
+        for (path, package_name) in &prefix_info.path_to_package {
+            if is_dso(&path.path)
+                && let Some(file_name) = path.path.file_name()
+            {
+                library_to_package.insert(
+                    file_name.to_string_lossy().to_string(),
+                    package_name.clone(),
+                );
+            }
+        }
+
+        Self { library_to_package }
+    }
+
+    /// Look up a library path by extracting its filename and checking the map.
+    /// Returns the package name if found.
+    ///
+    /// Handles various library path forms:
+    /// - Plain filenames: `libz.so.1`
+    /// - macOS @rpath references: `@rpath/libz.1.dylib`
+    /// - Full or relative paths: `lib/libz.so.1`
+    pub fn find_package(&self, library: &Path) -> Option<PackageName> {
+        let path_str = library.to_string_lossy();
+
+        // Strip @rpath/ or @loader_path/ prefixes (macOS)
+        let stripped = path_str
+            .strip_prefix("@rpath/")
+            .or_else(|| path_str.strip_prefix("@loader_path/"))
+            .unwrap_or(&path_str);
+
+        // Try the stripped path directly (handles plain filenames)
+        if let Some(pkg) = self.library_to_package.get(stripped) {
+            return Some(pkg.clone());
+        }
+
+        // Try just the filename component
+        let file_name = Path::new(stripped).file_name()?.to_string_lossy();
+
+        self.library_to_package.get(file_name.as_ref()).cloned()
+    }
+
+    /// Returns true if the map is empty.
+    pub fn is_empty(&self) -> bool {
+        self.library_to_package.is_empty()
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

crates/rattler_build_core/src/staging.rs

@@ -22,6 +22,7 @@ use crate::{
     env_vars,
     metadata::{Output, build_reindexed_channels},
     packaging::Files,
+    post_process::package_nature::{LibraryNameMap, PrefixInfo},
     render::resolved_dependencies::{
         FinalizedDependencies, RunExportsDownload, install_environments, resolve_dependencies,
     },
@@ -71,6 +72,13 @@ pub struct StagingCacheMetadata {
 
     /// The variant configuration that was used
     pub variant: BTreeMap<NormalizedKey, Variable>,
+
+    /// Mapping from shared library filenames to the package that provides them.
+    /// Captured at staging build time while conda-meta is still present, used
+    /// during overlinking checks as a fallback when these packages are not
+    /// physically installed in the host prefix.
+    #[serde(default)]
+    pub library_name_map: LibraryNameMap,
 }
 
 impl Output {
@@ -140,7 +148,8 @@ impl Output {
     /// 2. If yes, restore the cached files to the prefix
     /// 3. If no, build the staging cache and save it
     ///
-    /// Returns the finalized dependencies and sources from the staging cache
+    /// Returns the finalized dependencies, sources, and library name map from
+    /// the staging cache.
     pub async fn build_or_restore_staging_cache(
         &self,
         staging: &StagingCache,
@@ -149,6 +158,7 @@ impl Output {
         (
             FinalizedDependencies,
             Vec<rattler_build_recipe::stage1::Source>,
+            LibraryNameMap,
         ),
         miette::Error,
     > {
@@ -215,6 +225,7 @@ impl Output {
         (
             FinalizedDependencies,
             Vec<rattler_build_recipe::stage1::Source>,
+            LibraryNameMap,
         ),
         miette::Error,
     > {
@@ -252,6 +263,13 @@ impl Output {
             .await
             .into_diagnostic()?;
 
+        // Capture the library name map while conda-meta still exists in the
+        // prefix. This maps shared library filenames to their providing
+        // packages so overlinking checks can attribute libraries even after
+        // the staging cache's host deps are no longer installed.
+        let prefix_info = PrefixInfo::from_prefix(self.prefix()).into_diagnostic()?;
+        let library_name_map = LibraryNameMap::from_prefix_info(&prefix_info);
+
         // Run the build script
         let target_platform = self.build_configuration.target_platform;
         let mut env_vars = env_vars::vars(self, "BUILD");
@@ -374,6 +392,7 @@ impl Output {
             work_dir_files: copied_work_dir.copied_paths().to_vec(),
             prefix: self.prefix().to_path_buf(),
             variant: staging.used_variant.clone(),
+            library_name_map: library_name_map.clone(),
         };
 
         let metadata_json = serde_json::to_string_pretty(&metadata).into_diagnostic()?;
@@ -385,7 +404,7 @@ impl Output {
             metadata.work_dir_files.len()
         );
 
-        Ok((finalized_dependencies, finalized_sources))
+        Ok((finalized_dependencies, finalized_sources, library_name_map))
     }
 
     /// Restore a staging cache from disk
@@ -397,6 +416,7 @@ impl Output {
         (
             FinalizedDependencies,
             Vec<rattler_build_recipe::stage1::Source>,
+            LibraryNameMap,
         ),
         miette::Error,
     > {
@@ -436,7 +456,11 @@ impl Output {
             metadata.name
         );
 
-        Ok((metadata.finalized_dependencies, metadata.finalized_sources))
+        Ok((
+            metadata.finalized_dependencies,
+            metadata.finalized_sources,
+            metadata.library_name_map,
+        ))
     }
 
     /// Process all staging caches for this output
@@ -451,6 +475,7 @@ impl Output {
         Option<(
             FinalizedDependencies,
             Vec<rattler_build_recipe::stage1::Source>,
+            LibraryNameMap,
         )>,
         miette::Error,
     > {
@@ -467,7 +492,7 @@ impl Output {
                 "Building or restoring staging cache: {}",
                 staging_cache.name
             );
-            let (_deps, _sources) = self
+            let (_deps, _sources, _lib_map) = self
                 .build_or_restore_staging_cache(staging_cache, tool_configuration)
                 .await?;
         }
@@ -488,11 +513,11 @@ impl Output {
                 })?;
 
             // Get or build the cache
-            let (deps, sources) = self
+            let (deps, sources, lib_map) = self
                 .build_or_restore_staging_cache(staging, tool_configuration)
                 .await?;
 
-            Ok(Some((deps, sources)))
+            Ok(Some((deps, sources, lib_map)))
         } else {
             Ok(None)
         }

crates/rattler_build_core/src/types/build_output.rs

@@ -20,6 +20,7 @@ use std::{
 
 use crate::{
     console_utils::github_integration_enabled,
+    post_process::package_nature::LibraryNameMap,
     render::resolved_dependencies::FinalizedDependencies,
     system_tools::SystemTools,
     types::{BuildConfiguration, BuildSummary, PlatformWithVirtualPackages},
@@ -60,6 +61,12 @@ pub struct BuildOutput {
     /// that created this artifact
     #[serde(skip_serializing_if = "Option::is_none")]
     pub extra_meta: Option<BTreeMap<String, Value>>,
+
+    /// Library name map from the staging cache, used as a fallback during
+    /// overlinking checks when the staging cache's host dependencies are not
+    /// physically installed in the host prefix.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub staging_library_name_map: Option<LibraryNameMap>,
 }
 
 impl BuildOutput {

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

@@ -196,6 +196,7 @@ pub(crate) fn output_from_rendered_variant(
         finalized_sources: None,
         finalized_cache_dependencies: None,
         finalized_cache_sources: None,
+        staging_library_name_map: None,
         build_summary: Arc::new(Mutex::new(BuildSummary::default())),
         system_tools: SystemTools::new("rattler-build", env!("CARGO_PKG_VERSION")),
         extra_meta: None,

src/lib.rs

@@ -553,6 +553,7 @@ pub async fn get_build_output(
             finalized_sources: None,
             finalized_cache_dependencies: None,
             finalized_cache_sources: None,
+            staging_library_name_map: None,
             system_tools: SystemTools::new("rattler-build", env!("CARGO_PKG_VERSION")),
             build_summary: Arc::new(Mutex::new(BuildSummary::default())),
             extra_meta: Some(

test-data/recipes/staging/staging-overlinking/recipe.yaml

@@ -0,0 +1,54 @@
+# Test case: Overlinking check with staging outputs
+#
+# When a package inherits from a staging cache, the staging cache's host
+# dependencies (like zlib) are not installed in the prefix during the
+# overlinking check. The staging library name map must be used as a fallback
+# to resolve libraries to their providing packages.
+
+schema_version: 1
+
+recipe:
+  name: staging-overlinking-test
+  version: "1.0.0"
+
+build:
+  number: 0
+  dynamic_linking:
+    overlinking_behavior: error
+    missing_dso_allowlist:
+      - "libc*"
+
+outputs:
+  - staging:
+      name: compile-stage
+    requirements:
+      build:
+        - ${{ compiler('c') }}
+      host:
+        - zlib
+    build:
+      script:
+        - if: unix
+          then: |
+            cat > test_zlib.c << 'EOF'
+            #include <zlib.h>
+            #include <stdio.h>
+            int main() {
+                printf("zlib version: %s\n", zlibVersion());
+                return 0;
+            }
+            EOF
+            mkdir -p $PREFIX/bin
+            $CC $CFLAGS $LDFLAGS test_zlib.c -lz -o $PREFIX/bin/test_zlib
+        - if: win
+          then: |
+            echo int main() { return 0; } > test_zlib.c
+            mkdir %PREFIX%\bin
+            cl test_zlib.c /Fe%PREFIX%\bin\test_zlib.exe
+
+  - package:
+      name: staging-overlinking-test
+    inherit: compile-stage
+    build:
+      files:
+        - bin/**

test/end-to-end/test_staging.py

@@ -614,6 +614,34 @@ def test_staging_run_exports_ignore_by_name(
     )
 
 
+def test_staging_overlinking(
+    rattler_build: RattlerBuild, recipes: Path, tmp_path: Path
+):
+    """Test that overlinking checks pass for staging outputs via library name map.
+
+    When a package inherits from a staging cache, the staging cache's host
+    dependencies (e.g. zlib) are not installed in the host prefix during the
+    overlinking check of the inheriting package. The fix captures a library name
+    map at staging build time and uses it as a fallback in the overlinking check.
+
+    This test compiles a small C program that links against libz, packages it
+    via a staging output with overlinking_behavior: error, and verifies the
+    build succeeds (i.e. libz.so.1 is correctly attributed to zlib via the
+    staging library name map).
+    """
+    rattler_build.build(
+        recipes / "staging/staging-overlinking",
+        tmp_path,
+        extra_args=["--experimental"],
+    )
+
+    pkg = get_extracted_package(tmp_path, "staging-overlinking-test")
+    if platform.system() == "Windows":
+        assert (pkg / "bin/test_zlib.exe").exists()
+    else:
+        assert (pkg / "bin/test_zlib").exists()
+
+
 if __name__ == "__main__":
     # Allow running individual tests
     pytest.main([__file__, "-v"])