Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion cmake/targets/BuildBun.cmake
Original file line number Diff line number Diff line change
Expand Up @@ -1091,9 +1091,10 @@ if(WIN32)
endif()
endif()

option(BUN_USE_LD_NEW "Use ld_new linker on macOS (disable for Nix builds)" ON)
if(APPLE)
target_link_options(${bun} PUBLIC
-Wl,-ld_new
$<$<BOOL:${BUN_USE_LD_NEW}>:-Wl,-ld_new>
-Wl,-no_compact_unwind
-Wl,-stack_size,0x1200000
-fno-keep-static-consts
Comment on lines 1095 to 1100

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick | 🔵 Trivial

Gate -Wl,-ld_new removal to avoid changing default macOS linker behavior unintentionally.

If this is only required for Nix builds, consider an option/conditional so non‑Nix macOS builds retain the prior linker.

🔧 Possible gating option
+option(BUN_USE_LD_NEW "Use ld_new linker on macOS" ON)
 if(APPLE)
   target_link_options(${bun} PUBLIC
-    # -Wl,-ld_new  # Disabled for Nix compatibility - uses default linker
+    $<$<BOOL:${BUN_USE_LD_NEW}>:-Wl,-ld_new>
     -Wl,-no_compact_unwind
     -Wl,-stack_size,0x1200000
     -fno-keep-static-consts
   )
 endif()
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
if(APPLE)
target_link_options(${bun} PUBLIC
-Wl,-ld_new
# -Wl,-ld_new # Disabled for Nix compatibility - uses default linker
-Wl,-no_compact_unwind
-Wl,-stack_size,0x1200000
-fno-keep-static-consts
option(BUN_USE_LD_NEW "Use ld_new linker on macOS" ON)
if(APPLE)
target_link_options(${bun} PUBLIC
$<$<BOOL:${BUN_USE_LD_NEW}>:-Wl,-ld_new>
-Wl,-no_compact_unwind
-Wl,-stack_size,0x1200000
-fno-keep-static-consts
🤖 Prompt for AI Agents
In `@cmake/targets/BuildBun.cmake` around lines 1066 - 1071, The current removal
of -Wl,-ld_new from the Apple target_link_options for target ${bun} should be
gated so non‑Nix macOS builds keep the previous linker behavior; add a CMake
option (e.g., OPTION_USE_NIX_LINKER or BUILD_FOR_NIX) or detect a Nix build
environment and wrap the -Wl,-ld_new flag in a conditional so that
target_link_options(${bun} PUBLIC -Wl,-ld_new) is only applied when that
option/flag is true (leave the existing -Wl,-no_compact_unwind,
-Wl,-stack_size,... lines unchanged for all Apple builds).

Comment on lines +1094 to 1100

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

rg -n "BUN_USE_LD_NEW" -C 2

Repository: oven-sh/bun

Length of output: 563


🏁 Script executed:

# Search for files that might configure or pass CMAKE options
find . -type f \( -name "CMakeLists.txt" -o -name "*.nix" -o -name "*.github*" -o -name "Makefile" \) | head -20

Repository: oven-sh/bun

Length of output: 214


🏁 Script executed:

# Also search for patterns that pass CMAKE options
rg -n "BUN_USE_LD_NEW|add_subdirectory|target_link_options" --type cmake | grep -i "bun_use\|ld_new\|subdirectory" | head -30

Repository: oven-sh/bun

Length of output: 247


🏁 Script executed:

# Check Nix build files for BUN_USE_LD_NEW or macOS-specific options
fd -e nix | head -20

Repository: oven-sh/bun

Length of output: 74


🏁 Script executed:

# Check if CMakeLists.txt passes this option when including BuildBun.cmake
rg -n "BUN_USE_LD_NEW|BuildBun" CMakeLists.txt -C 3

Repository: oven-sh/bun

Length of output: 134


🏁 Script executed:

# Check Nix files for BUN_USE_LD_NEW or CMAKE option passing
rg -n "BUN_USE_LD_NEW|cmake.*-D|build.*flags" flake.nix shell.nix -C 2

Repository: oven-sh/bun

Length of output: 37


🏁 Script executed:

# Search for any cmake invocation that might set this option
rg -n "\-DBUN_USE_LD_NEW" --type cmake

Repository: oven-sh/bun

Length of output: 37


🏁 Script executed:

# Check how nix files configure cmake
cat flake.nix | head -100

Repository: oven-sh/bun

Length of output: 2792


🏁 Script executed:

# Check shell.nix as well
cat shell.nix | head -50

Repository: oven-sh/bun

Length of output: 1007


The option's help text contradicts the actual configuration: it says "disable for Nix builds" but Nix builds do not disable it.

The BUN_USE_LD_NEW option is defined and used correctly in BuildBun.cmake with a proper generator expression. However, it only appears in that file—neither flake.nix nor shell.nix pass -DBUN_USE_LD_NEW=OFF or any override. The option defaults to ON, meaning Nix builds will use the ld_new linker despite the help text suggesting otherwise.

Either wire the option into the Nix build by passing -DBUN_USE_LD_NEW=OFF, or remove the "disable for Nix builds" clause from the help text to reflect actual behavior.

🤖 Prompt for AI Agents
In `@cmake/targets/BuildBun.cmake` around lines 1094 - 1100, The option
BUN_USE_LD_NEW in BuildBun.cmake is declared with help text saying "disable for
Nix builds" but defaults to ON and Nix files (flake.nix/shell.nix) do not
override it; either wire the CMake option into the Nix build or change the help
text: update flake.nix and/or shell.nix to pass -DBUN_USE_LD_NEW=OFF when
invoking CMake to actually disable ld_new for Nix, or edit the option(...) call
in BuildBun.cmake to remove the "disable for Nix builds" clause so the comment
reflects current behavior (references: symbol BUN_USE_LD_NEW and file
BuildBun.cmake).

Expand Down Expand Up @@ -1305,6 +1306,8 @@ list(TRANSFORM BUN_DEPENDENCIES TOLOWER OUTPUT_VARIABLE BUN_TARGETS)
add_custom_target(dependencies DEPENDS ${BUN_TARGETS})

if(APPLE)
# macOS uses system icucore library for ICU functionality
# The prebuilt WebKit is compiled against icucore and expects its non-versioned symbols
target_link_libraries(${bun} PRIVATE icucore resolv)
target_compile_definitions(${bun} PRIVATE U_DISABLE_RENAMING=1)
endif()
Expand Down
271 changes: 268 additions & 3 deletions docs/pm/cli/install.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -200,6 +200,266 @@ bun install --dry-run

---

## Offline mode

Bun provides two offline modes for controlling network behavior during installation:

| Flag | Behavior |
|------|----------|
| `--offline` | Strict offline - fails if package not in cache |
| `--prefer-offline` | Prefers cache, falls back to network if needed |

### Strict offline mode (`--offline`)

To install packages without making any network requests, use the `--offline` flag:

```bash terminal icon="terminal"
bun install --offline
```

When offline mode is enabled, Bun will only use packages that are already in the local cache. If a required package is not cached, the installation will fail with an error message indicating that the package is not available in offline mode.

### Prefer offline mode (`--prefer-offline`)

To prefer cached packages but fall back to network when necessary:

```bash terminal icon="terminal"
bun install --prefer-offline
```

This mode uses cached packages whenever available, skipping network requests for packages that are already cached. If a package is not in the cache, Bun will fetch it from the registry normally. This provides faster installs when you have good cache coverage without the risk of failures when new dependencies are added.

### When to use offline mode

Offline mode is useful in several scenarios:

- **Air-gapped environments**: Servers or build systems that have no internet access
- **CI/CD optimization**: After an initial install populates the cache, subsequent installs can run offline for faster, more reliable builds
- **Reproducible builds**: Ensure builds only use cached, known-good packages
- **Network reliability**: Avoid failures caused by temporary network issues or registry outages

### Cache requirements

For offline mode to work, you need:

1. **Caching enabled**: The default cache location is `~/.bun/install/cache`. If you've disabled caching with `cache = false` in `bunfig.toml`, offline mode won't work.
2. **Packages already cached**: Run a normal install first to populate the cache.

If you're using a custom cache directory, make sure it's configured in both the initial install and the offline install:

```toml bunfig.toml icon="settings"
[install]
cache = "/path/to/custom/cache"
```

You can also enable these modes using environment variables:

```bash terminal icon="terminal"
BUN_CONFIG_OFFLINE=1 bun install # Strict offline
BUN_CONFIG_PREFER_OFFLINE=1 bun install # Prefer offline
```

Or configure them in `bunfig.toml`:

```toml bunfig.toml icon="settings"
[install]
offline = true # Strict offline mode
# or
preferOffline = true # Prefer offline mode
# Note: These options are mutually exclusive. Using both will result in an error.
```
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

### Air-gapped environment workflow

For environments with no internet access, you need to prepare the cache on a connected machine and transfer it to the air-gapped system.

#### Step 1: Prepare the cache on a connected machine

On a machine with internet access, install all dependencies to populate the cache:

```bash terminal icon="terminal"
# Clone or copy your project
git clone https://github.com/your-org/your-project.git
cd your-project

# Install dependencies (this populates ~/.bun/install/cache)
bun install

# Verify the cache was populated
ls ~/.bun/install/cache
```

#### Step 2: Package the cache for transfer

Create a portable archive of the cache directory:

```bash terminal icon="terminal"
# Create a tarball of the cache
tar -czvf bun-cache.tar.gz -C ~/.bun/install cache

# Also include your lockfile for reproducibility
cp bun.lock /path/to/transfer/
```

<Note>

The cache directory contains both package tarballs and extracted package contents. The entire `cache` directory must be transferred to ensure offline installs work correctly.

</Note>

#### Step 3: Transfer to the air-gapped system

Transfer the following files to your air-gapped environment:

- `bun-cache.tar.gz` - The package cache
- `bun.lock` - Your lockfile for reproducible installs
- Your project source code

Use your organization's approved method for transferring files (USB drive, secure file transfer, etc.).

#### Step 4: Set up on the air-gapped system

On the air-gapped machine:

```bash terminal icon="terminal"
# Extract the cache to Bun's cache directory
mkdir -p ~/.bun/install
tar -xzvf bun-cache.tar.gz -C ~/.bun/install

# Copy your project and lockfile
cp -r your-project /path/to/workspace/
cd /path/to/workspace/your-project

# Install using only the cache (no network requests)
bun install --offline --frozen-lockfile
```

#### Using a custom cache location

For more control, you can use a project-local cache:

```bash terminal icon="terminal"
# On the connected machine: use a local cache directory
BUN_INSTALL_CACHE_DIR=./vendor/cache bun install

# Transfer the entire project including vendor/cache

# On the air-gapped machine: use the same cache location
BUN_INSTALL_CACHE_DIR=./vendor/cache bun install --offline
```

Or configure it in `bunfig.toml`:

```toml bunfig.toml icon="settings"
[install]
cache = "./vendor/cache"
offline = true
```

### Docker workflow for air-gapped builds

For containerized air-gapped environments, you can bake the cache into your Docker image:

```dockerfile Dockerfile icon="docker"
# Stage 1: Build with network access (on connected system)
FROM oven/bun:1 AS deps
WORKDIR /app
COPY package.json bun.lock ./
RUN bun install

# Stage 2: Production image (can run air-gapped)
FROM oven/bun:1
WORKDIR /app

# Copy the populated cache from the build stage
COPY --from=deps /root/.bun/install/cache /root/.bun/install/cache

# Copy application files
COPY package.json bun.lock ./
COPY src ./src

# Install from cache only - no network needed
RUN bun install --offline --frozen-lockfile

CMD ["bun", "run", "start"]
```

Alternatively, pre-build a cache image that can be used across multiple projects:

```dockerfile Dockerfile.cache icon="docker"
# Cache image - build this on a connected system
FROM oven/bun:1
WORKDIR /cache

# Copy all your organization's package.json files
COPY projects/*/package.json projects/*/bun.lock ./

# Install everything to populate the cache
RUN for dir in */; do (cd "$dir" && bun install); done

# The cache is now at /root/.bun/install/cache
```

### CI/CD with cached dependencies

For CI/CD pipelines, cache the Bun install cache between runs:

```yaml .github/workflows/build.yml icon="file-code"
name: Build
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: oven-sh/setup-bun@v2

- name: Cache Bun dependencies
uses: actions/cache@v4
with:
path: ~/.bun/install/cache
key: bun-${{ runner.os }}-${{ hashFiles('**/bun.lock') }}
restore-keys: |
bun-${{ runner.os }}-

- name: Install dependencies
run: bun install --frozen-lockfile
# After cache is warm, add --offline for faster, network-free installs
```

### Troubleshooting offline installs

**Error: Package not found in cache**

If you see an error like `error: PackageName is not available in offline mode`, the package isn't in your cache. Solutions:

1. On a connected machine, run `bun install` without `--offline` to fetch the missing package
2. Transfer the updated cache to your air-gapped system
3. Ensure your `bun.lock` matches what's in the cache

**Error: Cache directory not found**

Ensure the cache directory exists and is readable:

```bash terminal icon="terminal"
ls -la ~/.bun/install/cache
# Or your custom cache location
ls -la $BUN_INSTALL_CACHE_DIR
```

**Lockfile mismatch**

When using `--frozen-lockfile` with `--offline`, ensure the `bun.lock` file was created from the same cache:

```bash terminal icon="terminal"
# On connected machine: regenerate lockfile
rm bun.lock
bun install

# Transfer both the cache AND the new bun.lock
```

---

## Non-npm dependencies

Bun supports installing dependencies from Git, GitHub, and local or remotely-hosted tarballs. For complete documentation refer to [Package manager > Git, GitHub, and tarball dependencies](/pm/cli/add).
Expand Down Expand Up @@ -324,6 +584,9 @@ frozenLockfile = false
# equivalent to `--dry-run` flag
dryRun = false

# equivalent to `--offline` flag
offline = false

# equivalent to `--concurrent-scripts` flag
concurrentScripts = 16 # (cpu count or GOMAXPROCS) x2

Expand All @@ -347,11 +610,13 @@ Environment variables have a higher priority than `bunfig.toml`.
| ---------------------------------- | ------------------------------------------------------------- |
| `BUN_CONFIG_REGISTRY` | Set an npm registry (default: https://registry.npmjs.org) |
| `BUN_CONFIG_TOKEN` | Set an auth token (currently does nothing) |
| `BUN_CONFIG_OFFLINE` | Install packages from cache only, without making network requests |
| `BUN_CONFIG_PREFER_OFFLINE` | Prefer cached packages, fall back to network if not available |
| `BUN_CONFIG_YARN_LOCKFILE` | Save a Yarn v1-style yarn.lock |
| `BUN_CONFIG_LINK_NATIVE_BINS` | Point `bin` in package.json to a platform-specific dependency |
| `BUN_CONFIG_SKIP_SAVE_LOCKFILE` | Don’t save a lockfile |
| `BUN_CONFIG_SKIP_LOAD_LOCKFILE` | Don’t load a lockfile |
| `BUN_CONFIG_SKIP_INSTALL_PACKAGES` | Don’t install any packages |
| `BUN_CONFIG_SKIP_SAVE_LOCKFILE` | Don't save a lockfile |
| `BUN_CONFIG_SKIP_LOAD_LOCKFILE` | Don't load a lockfile |
| `BUN_CONFIG_SKIP_INSTALL_PACKAGES` | Don't install any packages |

Bun always tries to use the fastest available installation method for the target platform. On macOS, that’s `clonefile` and on Linux, that’s `hardlink`. You can change which installation method is used with the `--backend` flag. When unavailable or on error, `clonefile` and `hardlink` fallsback to a platform-specific implementation of copying files.

Expand Down
26 changes: 22 additions & 4 deletions flake.nix
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,8 @@
pkgs.zlib
pkgs.libxml2
pkgs.libiconv
pkgs.icu
pkgs.sqlite

# Development tools
pkgs.git
Expand Down Expand Up @@ -119,10 +121,10 @@
pkgs.xorg.libxshmfence
pkgs.gdk-pixbuf
] ++ pkgs.lib.optionals pkgs.stdenv.isDarwin [
# macOS specific dependencies
pkgs.darwin.apple_sdk.frameworks.CoreFoundation
pkgs.darwin.apple_sdk.frameworks.CoreServices
pkgs.darwin.apple_sdk.frameworks.Security
# macOS: stdenv provides apple-sdk automatically since nixpkgs 25.11
# No explicit framework references needed - they're part of the SDK
pkgs.darwin.libiconv
pkgs.darwin.ICU # Provides libicucore compatibility layer for WebKit
];

in
Expand All @@ -145,6 +147,22 @@
export CMAKE_RANLIB="$RANLIB"
export CMAKE_SYSTEM_PROCESSOR="$(uname -m)"
export TMPDIR="''${TMPDIR:-/tmp}"

# Use system Xcode SDK for macOS builds (requires macOS 13.0+ SDK)
if [ -d "/Applications/Xcode.app/Contents/Developer" ]; then
export DEVELOPER_DIR="/Applications/Xcode.app/Contents/Developer"
export SDKROOT="$(xcrun --sdk macosx --show-sdk-path)"
export CMAKE_OSX_SYSROOT="$SDKROOT"
fi

# ICU and sqlite include paths for WebKit headers and sqlite bindings
export CXXFLAGS="''${CXXFLAGS:+$CXXFLAGS }-I${pkgs.icu.dev}/include -I${pkgs.sqlite.dev}/include"
export CFLAGS="''${CFLAGS:+$CFLAGS }-I${pkgs.icu.dev}/include -I${pkgs.sqlite.dev}/include"
export CMAKE_CXX_FLAGS="''${CMAKE_CXX_FLAGS:+$CMAKE_CXX_FLAGS }-I${pkgs.icu.dev}/include -I${pkgs.sqlite.dev}/include"
export CMAKE_C_FLAGS="''${CMAKE_C_FLAGS:+$CMAKE_C_FLAGS }-I${pkgs.icu.dev}/include -I${pkgs.sqlite.dev}/include"
'' + pkgs.lib.optionalString pkgs.stdenv.isDarwin ''
# Add darwin.ICU library path for libicucore (required by WebKit)
export LIBRARY_PATH="${pkgs.darwin.ICU}/lib''${LIBRARY_PATH:+:$LIBRARY_PATH}"
'' + pkgs.lib.optionalString pkgs.stdenv.isLinux ''
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
export LD="${pkgs.lib.getExe' lld "ld.lld"}"
export NIX_CFLAGS_LINK="''${NIX_CFLAGS_LINK:+$NIX_CFLAGS_LINK }-fuse-ld=lld"
Expand Down
6 changes: 6 additions & 0 deletions src/api/schema.zig
Original file line number Diff line number Diff line change
Expand Up @@ -3045,6 +3045,12 @@ pub const api = struct {
/// frozen_lockfile
frozen_lockfile: ?bool = null,

/// offline
offline: ?bool = null,

/// prefer_offline
prefer_offline: ?bool = null,

/// exact
exact: ?bool = null,

Expand Down
12 changes: 12 additions & 0 deletions src/bunfig.zig
Original file line number Diff line number Diff line change
Expand Up @@ -588,6 +588,18 @@ pub const Bunfig = struct {
}
}

if (install_obj.get("offline")) |offline| {
if (offline.asBool()) |value| {
install.offline = value;
}
}

if (install_obj.get("preferOffline")) |prefer_offline| {
if (prefer_offline.asBool()) |value| {
install.prefer_offline = value;
}
}

if (install_obj.get("saveTextLockfile")) |save_text_lockfile| {
if (save_text_lockfile.asBool()) |value| {
install.save_text_lockfile = value;
Expand Down
Loading