install: honour npm's libc field for optional native packages, add --libc

docs/pm/cli/install.mdx

@@ -420,14 +420,14 @@ jobs:
 
 ## Platform-specific dependencies?
 
-Bun stores normalized `cpu` and `os` values from npm in the lockfile, along with the resolved packages. It skips downloading, extracting, and installing packages disabled for the current target at runtime. This means the lockfile doesn't change between platforms/architectures even if the packages ultimately installed do change.
+Bun stores normalized `cpu`, `os` and `libc` values from npm in the lockfile, along with the resolved packages. It skips downloading, extracting, and installing packages disabled for the current target at runtime. This means the lockfile doesn't change between platforms/architectures even if the packages ultimately installed do change. `libc` (`glibc` or `musl`) is only consulted on Linux, so that only the matching variant of a native package's prebuilt binaries is downloaded.
 
-### `--cpu` and `--os` flags
+### `--cpu`, `--os` and `--libc` flags
 
 You can override the target platform for package selection:
 
 ```bash
-bun install --cpu=x64 --os=linux
+bun install --cpu=x64 --os=linux --libc=musl
 ```
 
 These flags install packages for the specified platform instead of the current system. Use them for cross-platform builds or when preparing deployments for different environments.
@@ -436,6 +436,8 @@ These flags install packages for the specified platform instead of the current s
 
 **Accepted values for `--os`**: `aix`, `darwin`, `freebsd`, `linux`, `openbsd`, `sunos`, `win32`, `android`
 
+**Accepted values for `--libc`**: `glibc`, `musl` (`*` for both)
+
 ## Peer dependencies?
 
 Bun handles peer dependencies like Yarn: `bun install` installs them automatically. If the dependency is marked optional in `peerDependenciesMeta`, Bun uses an existing dependency if possible.

src/install/PackageManager.rs

@@ -730,6 +730,20 @@ impl PackageManager {
         unsafe { &*get() }
     }
 
+    /// `get()` for code that may also run before the manager exists (unit paths,
+    /// `bun pm` helpers that build a `Meta` without an install).
+    #[inline]
+    pub fn try_get() -> Option<&'static PackageManager> {
+        let p = get();
+        if p.is_null() {
+            None
+        } else {
+            // SAFETY: same as `get()` — non-null means `allocate_package_manager()`
+            // ran and the singleton lives for the process.
+            Some(unsafe { &*p })
+        }
+    }
+
     /// Associated-fn spelling that forwards to the free [`init`] so callers
     /// can write `PackageManager::init(ctx, cli, subcommand)`.
     #[inline]

src/install/PackageManager/CommandLineArguments.rs

@@ -125,6 +125,9 @@ const SHARED_TAIL_PARAMS: &[ParamType] = &[
     clap::param!(
         "--os <STR>...                         Override operating system for optional dependencies (e.g., linux, darwin, * for all)"
     ),
+    clap::param!(
+        "--libc <STR>...                       Override libc for optional dependencies (glibc, musl, * for all)"
+    ),
     clap::param!("-h, --help                            Print this help menu"),
 ];
 
@@ -593,6 +596,7 @@ pub struct CommandLineArguments {
 
     // CPU and OS overrides for optional dependencies
     pub(crate) cpu: Npm::Architecture,
+    pub(crate) libc: Npm::Libc,
     pub(crate) os: Npm::OperatingSystem,
 }
 
@@ -687,6 +691,7 @@ impl Default for CommandLineArguments {
             audit_ignore_list: &[],
 
             cpu: Npm::Architecture::CURRENT,
+            libc: Npm::Libc::CURRENT,
             os: Npm::OperatingSystem::CURRENT,
         }
     }
@@ -1570,6 +1575,28 @@ Full documentation is available at <magenta>https://bun.com/docs/pm/cli/prune<r>
             cli.os = os_negatable.combine();
         }
 
+        let libc_values = args.options(b"--libc");
+        if !libc_values.is_empty() {
+            let mut libc_negatable = Npm::Libc::NONE.negatable();
+            for libc_str in libc_values {
+                libc_negatable.apply(libc_str);
+                if *libc_str == *b"*" {
+                    libc_negatable.had_wildcard = true;
+                    libc_negatable.had_unrecognized_values = false;
+                } else if libc_negatable.had_unrecognized_values
+                    && *libc_str != *b"any"
+                    && *libc_str != *b"none"
+                {
+                    Output::err_generic(
+                        "Invalid libc: '{}'. Valid values are: *, any, glibc, musl. Use !name to negate.",
+                        (bstr::BStr::new(libc_str),),
+                    );
+                    Global::crash();
+                }
+            }
+            cli.libc = libc_negatable.combine();
+        }
+
         if matches!(subcommand, Subcommand::Add | Subcommand::Install) {
             cli.dependency_group = if args.flag(b"--development") || args.flag(b"--dev") {
                 Options::DependencyGroup::DEV

src/install/PackageManager/PackageManagerOptions.rs

@@ -92,6 +92,9 @@ pub struct Options {
 
     /// Override CPU architecture for optional dependencies filtering
     pub cpu: Npm::Architecture,
+    /// Host libc family used to filter optional native packages that declare npm's
+    /// `libc` field (glibc vs musl). `--libc` overrides; NONE = don't filter.
+    pub libc: Npm::Libc,
     /// Override OS for optional dependencies filtering
     pub os: Npm::OperatingSystem,
 
@@ -160,6 +163,7 @@ impl Default for Options {
             minimum_release_age_ms: None,
             minimum_release_age_excludes: None,
             cpu: Npm::Architecture::CURRENT,
+            libc: Npm::Libc::CURRENT,
             os: Npm::OperatingSystem::CURRENT,
             config_version: None,
         }
@@ -820,6 +824,7 @@ impl Options {
             // CPU and OS are now parsed as enums in CommandLineArguments, just copy them
             self.cpu = cli.cpu;
             self.os = cli.os;
+            self.libc = cli.libc;
 
             self.do_.set(Do::UPDATE_TO_LATEST, cli.latest);
             self.do_.set(Do::RECURSIVE, cli.recursive);

src/install/lockfile.rs

@@ -1507,6 +1507,9 @@
                         if pkg_meta.arch == Npm::Architecture::ALL {
                             pkg_meta.arch = pkg.package.cpu;
                         }
+                        if pkg_meta.libc == Npm::Libc::NONE {
+                            pkg_meta.libc = pkg.package.libc;
+                        }
                     }
                 }
                 _ => {}

src/install/lockfile/Package.rs

@@ -852,6 +852,7 @@ impl Package<u64> {
             );
 
             package.meta.arch = package_version.cpu;
+            package.meta.libc = package_version.libc;
             package.meta.os = package_version.os;
             package.meta.integrity = package_version.integrity;
             package

src/install/lockfile/Package/Meta.rs

@@ -1,5 +1,5 @@
 use bun_install::integrity::Integrity;
-use bun_install::npm::{Architecture, OperatingSystem};
+use bun_install::npm::{Architecture, Libc, OperatingSystem};
 use bun_install::{INVALID_PACKAGE_ID, Origin, PackageID};
 use bun_semver::String;
 
@@ -14,7 +14,9 @@ use crate::lockfile_real::StringBuilder as LockfileStringBuilder;
 #[derive(Clone, Copy)]
 pub struct Meta {
     pub(crate) origin: Origin,
-    pub(crate) _padding_origin: u8,
+    /// npm `libc` field (glibc/musl). Occupies what used to be a padding byte, so
+    /// binary lockfiles written before it read back as `Libc::NONE` (unspecified).
+    pub(crate) libc: Libc,
 
     pub(crate) arch: Architecture,
     pub(crate) os: OperatingSystem,
@@ -49,7 +51,7 @@ impl Default for Meta {
     fn default() -> Self {
         Self {
             origin: Origin::Npm,
-            _padding_origin: 0,
+            libc: Libc::NONE,
             arch: Architecture::ALL,
             os: OperatingSystem::ALL,
             _padding_os: 0,
@@ -63,10 +65,23 @@ impl Default for Meta {
 }
 
 impl Meta {
-    /// Does the `cpu` arch and `os` match the requirements listed in the package?
+    /// Do the `cpu` arch, `os` and (on Linux) `libc` match the requirements listed in the package?
     /// This is completely unrelated to "devDependencies", "peerDependencies", "optionalDependencies" etc
     pub fn is_disabled(&self, cpu: Architecture, os: OperatingSystem) -> bool {
-        !self.arch.is_match(cpu) || !self.os.is_match(os)
+        !self.arch.is_match(cpu) || !self.os.is_match(os) || !self.libc_matches_host()
+    }
+
+    /// npm's `libc` constraint: only consulted for packages that target Linux, against
+    /// the host libc (or the `--libc` override).
+    #[inline]
+    fn libc_matches_host(&self) -> bool {
+        if self.libc == Libc::NONE {
+            return true;
+        }
+        let target = crate::package_manager_real::PackageManager::try_get()
+            .map(|pm| pm.options.libc)
+            .unwrap_or(Libc::CURRENT);
+        self.libc.is_match(target)
     }
 
     pub(crate) fn has_install_script(&self) -> bool {
@@ -110,6 +125,7 @@ impl Meta {
             integrity: self.integrity,
             arch: self.arch,
             os: self.os,
+            libc: self.libc,
             origin: self.origin,
             has_install_script: self.has_install_script,
             ..Meta::default()

src/install/lockfile/bun.lock.rs

@@ -786,7 +786,7 @@ impl Stringifier {
                         });
                     }
 
-                    // INFO = { prod/dev/optional/peer dependencies, os, cpu, libc (TODO), bin, binDir }
+                    // INFO = { prod/dev/optional/peer dependencies, os, cpu, libc, bin, binDir }
 
                     // first index is resolution for each type of package
                     // npm         -> [ "name@version", registry (TODO: remove if default), INFO, integrity]
@@ -1063,7 +1063,7 @@ impl Stringifier {
         Ok(())
     }
 
-    /// Writes a single line object. Contains dependencies, os, cpu, libc (soon), and bin
+    /// Writes a single line object. Contains dependencies, os, cpu, libc, and bin
     /// { "devDependencies": { "one": "1.1.1", "two": "2.2.2" }, "os": "none" }
     fn write_package_info_object(
         writer: &mut Writer,
@@ -1178,14 +1178,15 @@ impl Stringifier {
             writer.write_all(b" \"bundled\": true")?;
         }
 
-        // TODO(dylan-conway)
-        // if (meta.libc != .all) {
-        //     try writer.writeAll(
-        //         \\"libc": [
-        //     );
-        //     try Negatable(Npm.Libc).toJson(meta.libc, writer);
-        //     try writer.writeAll("], ");
-        // }
+        if meta.libc != Npm::Libc::NONE && meta.libc != Npm::Libc::ALL {
+            if any {
+                writer.write_byte(b',')?;
+            } else {
+                any = true;
+            }
+            writer.write_all(b" \"libc\": ")?;
+            Negatable::<Npm::Libc>::to_json(meta.libc, &mut AsFmt::new(writer))?;
+        }
 
         if meta.os != Npm::OperatingSystem::ALL {
             if any {
@@ -2844,10 +2845,9 @@ pub(crate) fn parse_into_binary_lockfile(
                                 pkg.meta.arch =
                                     Npm::negatable_from_json_value::<Npm::Architecture>(arch);
                             }
-                            // TODO(dylan-conway)
-                            // if (os_cpu_libc_obj.get("libc")) |libc| {
-                            //     pkg.meta.libc = Negatable(Npm.Libc).fromJson(allocator, libc);
-                            // }
+                            if let Some(libc) = deps_os_cpu_libc_bin_bundle_obj.get(b"libc") {
+                                pkg.meta.libc = Npm::negatable_from_json_value::<Npm::Libc>(libc);
+                            }
                         }
                     }
                     ResolutionTag::Root => {

src/install_types/resolver_hooks.rs

@@ -863,20 +863,47 @@ negatable_names! { OperatingSystem: u16, OPERATING_SYSTEM_NAMES => [
 pub struct Libc(pub u8);
 
 impl Libc {
+    /// "unspecified" — the package did not declare a `libc` field (or the lockfile
+    /// predates the field). Matches every host.
     pub const NONE: Self = Self(0);
-    pub(crate) const ALL: Self = Self(Self::ALL_VALUE);
+    pub const ALL: Self = Self(Self::ALL_VALUE);
 
-    pub(crate) const GLIBC: u8 = 1 << 1;
-    pub(crate) const MUSL: u8 = 1 << 2;
+    pub const GLIBC: u8 = 1 << 1;
+    pub const MUSL: u8 = 1 << 2;
 
-    pub(crate) const ALL_VALUE: u8 = Self::GLIBC | Self::MUSL;
+    pub const ALL_VALUE: u8 = Self::GLIBC | Self::MUSL;
 
-    // TODO: runtime libc detection
+    /// The host's libc family. Only meaningful on Linux (npm's `libc` field is
+    /// ignored elsewhere); a musl-targeted bun build is a musl host.
+    #[cfg(all(target_os = "linux", target_env = "musl"))]
+    pub const CURRENT: Self = Self(Self::MUSL);
+    #[cfg(all(target_os = "linux", not(target_env = "musl")))]
+    pub const CURRENT: Self = Self(Self::GLIBC);
+    #[cfg(not(target_os = "linux"))]
+    pub const CURRENT: Self = Self::NONE;
 
     #[inline]
-    pub(crate) fn has(self, other: u8) -> bool {
+    pub const fn none() -> Self {
+        Self::NONE
+    }
+    #[inline]
+    pub const fn all() -> Self {
+        Self::ALL
+    }
+    #[inline]
+    pub fn has(self, other: u8) -> bool {
         (self.0 & other) != 0
     }
+    /// Does a package declaring `self` install on a host whose libc is `target`?
+    /// Unspecified on either side matches (non-Linux hosts pass `NONE`).
+    #[inline]
+    pub fn is_match(self, target: Self) -> bool {
+        self.0 == 0 || target.0 == 0 || (self.0 & target.0) != 0
+    }
+    #[inline]
+    pub fn negatable(self) -> Negatable<Self> {
+        NegatableExt::negatable(self)
+    }
 }
 
 negatable_names! { Libc: u8, LIBC_NAMES => [ b"musl" => MUSL, b"glibc" => GLIBC ] }