Skip to content
Open
Show file tree
Hide file tree
Changes from 1 commit
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
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ Bun supports Linux (x64 & arm64), macOS (x64 & Apple Silicon), and Windows (x64

> **Linux users** — Kernel version 5.6 or higher is strongly recommended, but the minimum is 5.1.

> **x64 users** — if you see "illegal instruction" or similar errors, check our [CPU requirements](https://bun.com/docs/installation#cpu-requirements-and-baseline-builds)
> **x64 users** — if you see "illegal instruction" or similar errors, check our [CPU requirements](https://bun.com/docs/installation#cpu-requirements)

```sh
# with install script (recommended)
Expand Down
80 changes: 17 additions & 63 deletions docs/bundler/executables.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -51,44 +51,18 @@ To build for Linux x64 (most servers):
<Tab title="CLI">
```bash icon="terminal" terminal
bun build --compile --target=bun-linux-x64 ./index.ts --outfile myapp

# To support CPUs from before 2013, use the baseline version (nehalem)
bun build --compile --target=bun-linux-x64-baseline ./index.ts --outfile myapp

# To explicitly only support CPUs from 2013 and later, use the modern version (haswell)
# modern is faster, but baseline is more compatible.
bun build --compile --target=bun-linux-x64-modern ./index.ts --outfile myapp
```

</Tab>
<Tab title="JavaScript">
```ts build.ts icon="/icons/typescript.svg"
// Standard Linux x64
await Bun.build({
entrypoints: ["./index.ts"],
compile: {
target: "bun-linux-x64",
outfile: "./myapp",
},
});

// Baseline (pre-2013 CPUs)
await Bun.build({
entrypoints: ["./index.ts"],
compile: {
target: "bun-linux-x64-baseline",
outfile: "./myapp",
},
});

// Modern (2013+ CPUs, faster)
await Bun.build({
entrypoints: ["./index.ts"],
compile: {
target: "bun-linux-x64-modern",
outfile: "./myapp",
},
});
```

</Tab>
Expand Down Expand Up @@ -123,35 +97,19 @@ To build for Windows x64:
```bash icon="terminal" terminal
bun build --compile --target=bun-windows-x64 ./path/to/my/app.ts --outfile myapp

# To support CPUs from before 2013, use the baseline version (nehalem)
bun build --compile --target=bun-windows-x64-baseline ./path/to/my/app.ts --outfile myapp

# To explicitly only support CPUs from 2013 and later, use the modern version (haswell)
bun build --compile --target=bun-windows-x64-modern ./path/to/my/app.ts --outfile myapp

# note: if no .exe extension is provided, Bun adds it automatically for Windows executables
```

</Tab>
<Tab title="JavaScript">
```ts build.ts icon="/icons/typescript.svg"
// Standard Windows x64
await Bun.build({
entrypoints: ["./path/to/my/app.ts"],
compile: {
target: "bun-windows-x64",
outfile: "./myapp", // .exe added automatically
},
});

// Baseline or modern variants
await Bun.build({
entrypoints: ["./path/to/my/app.ts"],
compile: {
target: "bun-windows-x64-baseline",
outfile: "./myapp",
},
});
```

</Tab>
Expand Down Expand Up @@ -228,23 +186,22 @@ To build for macOS x64:

The segments of the `--target` value can appear in any order, as long as they're delimited by `-`.

| --target | Operating System | Architecture | Modern | Baseline | Libc |
| -------------------- | ---------------- | ------------ | ------ | -------- | ----- |
| bun-linux-x64 | Linux | x64 | ✅ | ✅ | glibc |
| bun-linux-arm64 | Linux | arm64 | ✅ | N/A | glibc |
| bun-windows-x64 | Windows | x64 | ✅ | ✅ | - |
| bun-windows-arm64 | Windows | arm64 | ✅ | N/A | - |
| bun-darwin-x64 | macOS | x64 | ✅ | ✅ | - |
| bun-darwin-arm64 | macOS | arm64 | ✅ | N/A | - |
| bun-linux-x64-musl | Linux | x64 | ✅ | ✅ | musl |
| bun-linux-arm64-musl | Linux | arm64 | ✅ | N/A | musl |
| --target | Operating System | Architecture | Libc |
| -------------------- | ---------------- | ------------ | ----- |
| bun-linux-x64 | Linux | x64 | glibc |
| bun-linux-arm64 | Linux | arm64 | glibc |
| bun-windows-x64 | Windows | x64 | - |
| bun-windows-arm64 | Windows | arm64 | - |
| bun-darwin-x64 | macOS | x64 | - |
| bun-darwin-arm64 | macOS | arm64 | - |
| bun-linux-x64-musl | Linux | x64 | musl |
| bun-linux-arm64-musl | Linux | arm64 | musl |

<Warning>
On x64 platforms, Bun uses SIMD optimizations that require a CPU with AVX2 instructions. The `-baseline` build of Bun
is for older CPUs without them. The Bun installer detects which version to use, but when cross-compiling you might not
know the target CPU. This mostly matters on Windows x64 and Linux x64, rarely on Darwin x64. If you or your users see
`"Illegal instruction"` errors, you might need to use the baseline version.
</Warning>
<Note>
On x64, Bun ships a single binary that targets Nehalem (SSE4.2) and selects AVX2/AVX-512 code paths at runtime. The
`-baseline` and `-modern` target suffixes are still accepted for backward compatibility and resolve to the same
binary; you do not need to pick one based on the destination CPU.
</Note>

---

Expand Down Expand Up @@ -1276,18 +1233,15 @@ compile: {
```ts title="Bun.Build.CompileTarget" icon="/icons/typescript.svg"
type CompileTarget =
| "bun-darwin-x64"
| "bun-darwin-x64-baseline"
| "bun-darwin-arm64"
| "bun-linux-x64"
| "bun-linux-x64-baseline"
| "bun-linux-x64-modern"
| "bun-linux-arm64"
| "bun-linux-x64-musl"
| "bun-linux-arm64-musl"
| "bun-windows-x64"
| "bun-windows-x64-baseline"
| "bun-windows-x64-modern"
| "bun-windows-arm64";
// The "-baseline" and "-modern" suffixes are accepted for backward
// compatibility and resolve to the same x64 binary.
```

### Complete example
Expand Down
57 changes: 13 additions & 44 deletions docs/installation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -237,28 +237,21 @@ To download Bun binaries directly, visit the [releases page on GitHub](https://g
title="Linux x64"
href="https://github.com/oven-sh/bun/releases/latest/download/bun-linux-x64.zip"
>
Standard Linux x64 binary
glibc, Nehalem or newer
</Card>
<Card
icon="/icons/linux.svg"
title="Linux x64 Baseline"
href="https://github.com/oven-sh/bun/releases/latest/download/bun-linux-x64-baseline.zip"
title="Linux ARM64"
href="https://github.com/oven-sh/bun/releases/latest/download/bun-linux-aarch64.zip"
>
For older CPUs without AVX2
ARM64 Linux systems
</Card>
<Card
icon="/icons/windows.svg"
title="Windows x64"
href="https://github.com/oven-sh/bun/releases/latest/download/bun-windows-x64.zip"
>
Standard Windows binary
</Card>
<Card
icon="/icons/windows.svg"
title="Windows x64 Baseline"
href="https://github.com/oven-sh/bun/releases/latest/download/bun-windows-x64-baseline.zip"
>
For older CPUs without AVX2
Nehalem or newer
</Card>
<Card
icon="/icons/windows.svg"
Expand All @@ -281,21 +274,13 @@ To download Bun binaries directly, visit the [releases page on GitHub](https://g
>
Intel Macs
</Card>
<Card
icon="/icons/linux.svg"
title="Linux ARM64"
href="https://github.com/oven-sh/bun/releases/latest/download/bun-linux-aarch64.zip"
>
ARM64 Linux systems
</Card>
</CardGroup>

### Musl Binaries

For distributions without `glibc` (Alpine Linux, Void Linux):

- [Linux x64 musl](https://github.com/oven-sh/bun/releases/latest/download/bun-linux-x64-musl.zip)
- [Linux x64 musl baseline](https://github.com/oven-sh/bun/releases/latest/download/bun-linux-x64-musl-baseline.zip)
- [Linux ARM64 musl](https://github.com/oven-sh/bun/releases/latest/download/bun-linux-aarch64-musl.zip)

<Note>
Expand All @@ -308,33 +293,17 @@ For distributions without `glibc` (Alpine Linux, Void Linux):

## CPU Requirements

CPU requirements depend on which binary you're using:
Bun ships a single x64 binary per platform. It targets the Nehalem microarchitecture (SSE4.2) and selects AVX2/AVX-512
code paths at runtime when the CPU supports them, so there is no separate "baseline" download to choose.

<Tabs>
<Tab title="Standard Builds">
**x64 binaries** target the Haswell CPU architecture (AVX and AVX2 instructions required)
| Platform | Intel Requirement | AMD Requirement |
|----------|-------------------|-----------------|
| x64 | Haswell (4th gen Core) or newer | Excavator or newer |
</Tab>

<Tab title="Baseline Builds">
**x64-baseline binaries** target the Nehalem architecture for older CPUs
| Platform | Intel Requirement | AMD Requirement |
|----------|-------------------|-----------------|
| x64-baseline | Nehalem (1st gen Core) or newer | Bulldozer or newer |

<Warning>
Baseline builds are slower than regular builds. Use them only if you encounter an "Illegal
Instruction" error.
</Warning>
</Tab>

</Tabs>
| Platform | Intel Requirement | AMD Requirement |
| -------- | ------------------------------- | ------------------ |
| x64 | Nehalem (1st gen Core) or newer | Bulldozer or newer |

<Note>
Bun does not support CPUs older than the baseline target, which requires the SSE4.2 extension. Bun requires macOS 13.0
or later.
Bun does not support x64 CPUs without the SSE4.2 extension. Bun requires macOS 13.0 or later. The `-baseline` release
assets and `@oven/bun-*-x64-baseline` npm packages are kept as aliases of the single x64 binary for backward
compatibility with older install scripts.
</Note>

---
Expand Down
94 changes: 94 additions & 0 deletions test/internal/release-asset-coherence.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
// Guards the invariant that every zip name a download path can request
// (install.sh, install.ps1, the @oven/* npm packages, `bun upgrade`) is
// actually produced by the release pipeline. #34782 collapsed x64 to a single
// Nehalem binary with `-baseline` assets as rezipped aliases; a drift in any
// one of these files would 404 installs on release day.
import { describe, expect, test } from "bun:test";
import { readFileSync } from "node:fs";
import { join } from "node:path";

const repo = join(import.meta.dir, "..", "..");

/** Set of `<name>.zip` files the release step uploads to the GitHub release. */
function releaseAssetSet(): Set<string> {
const sh = readFileSync(join(repo, ".buildkite/scripts/upload-release.sh"), "utf8");

// `local artifacts=( ... )` holds the primary zip names CI produces.
const listMatch = sh.match(/local artifacts=\(([\s\S]*?)\)/);
if (!listMatch) throw new Error("upload-release.sh: artifacts=() block not found");
const assets = new Set<string>();
for (const m of listMatch[1].matchAll(/(bun-[A-Za-z0-9_-]+\.zip)/g)) assets.add(m[1]);

// `alias_baseline_artifact` rezips each primary x64 zip under a `-baseline`
// name with the inner directory renamed to match; include those.
const aliasBody = sh.match(/function alias_baseline_artifact\b[\s\S]*?\n {2}\}/);
if (!aliasBody) throw new Error("upload-release.sh: alias_baseline_artifact() not found");
for (const m of aliasBody[0].matchAll(/echo "(bun-[A-Za-z0-9_-]+\.zip)"/g)) assets.add(m[1]);

return assets;
}

describe("release asset coherence", () => {
const assets = releaseAssetSet();

test("upload-release.sh artifact list parsed", () => {
expect(assets.size).toBeGreaterThanOrEqual(24);
expect(assets.has("bun-linux-x64.zip")).toBe(true);
expect(assets.has("bun-linux-x64-baseline.zip")).toBe(true);
});

test("install.sh targets all resolve to a release asset", () => {
// Every `target=...` assignment the script can reach, expanded over the
// platform cases plus the avx2-miss `-baseline` and `debug-info` `-profile`
// suffix paths. Keep this list literal so adding a case to install.sh
// without a matching release asset fails here.
const want = [
"darwin-x64",
"darwin-x64-baseline",
"darwin-aarch64",
"linux-x64",
"linux-x64-baseline",
"linux-x64-musl",
"linux-x64-musl-baseline",
"linux-aarch64",
"linux-aarch64-musl",
"windows-x64",
"windows-aarch64",
];
const missing: string[] = [];
for (const t of want) {
for (const suffix of ["", "-profile"]) {
const name = `bun-${t}${suffix}.zip`;
if (!assets.has(name)) missing.push(name);
}
}
expect(missing).toEqual([]);
});

test("install.ps1 targets all resolve to a release asset", () => {
const want = ["bun-windows-x64.zip", "bun-windows-x64-baseline.zip", "bun-windows-aarch64.zip"];
expect(want.filter(n => !assets.has(n))).toEqual([]);
});

test("packages/bun-release platform bins all resolve to a release asset", () => {
// upload-npm.ts fetches `${bin}.zip` for every entry in `platforms`,
// including `alias: true` entries, and extracts `${bin}/...` from it.
const src = readFileSync(join(repo, "packages/bun-release/src/platform.ts"), "utf8");
const bins = [...src.matchAll(/bin:\s*"(bun-[A-Za-z0-9_-]+)"/g)].map(m => m[1]);
expect(bins.length).toBeGreaterThanOrEqual(14);
const missing = bins.map(b => `${b}.zip`).filter(name => !assets.has(name));
expect(missing).toEqual([]);
});

test("docs do not claim x64 requires AVX2/Haswell", () => {
// The single x64 binary targets Nehalem (SSE4.2); AVX2 is runtime-dispatched.
// Keeps installation and --compile docs from re-introducing the old
// "pick baseline if your CPU lacks AVX2" guidance.
for (const file of ["docs/installation.mdx", "docs/bundler/executables.mdx"]) {
const doc = readFileSync(join(repo, file), "utf8");
expect(doc).not.toMatch(/target the Haswell/i);
expect(doc).not.toMatch(/require.{0,20}AVX2/i);
expect(doc).not.toMatch(/modern is faster/i);
}
});

Check warning on line 93 in test/internal/release-asset-coherence.test.ts

View check run for this annotation

Claude / Claude Code Review

npm package READMEs still describe -baseline as "without AVX2 instructions"

The npm package READMEs still carry the same stale "without AVX2" / "do not support AVX2" claims this PR removes from `docs/`: `packages/bun-release/npm/bun/README.md` (L21/24/26) and each `packages/bun-release/npm/@oven/bun-{darwin,linux,windows}-x64-baseline/README.md` (L5). Since the new `installation.mdx` `<Note>` explicitly names the `@oven/bun-*-x64-baseline` packages as aliases, these are same-class sibling sites — worth updating here so npmjs.com doesn't keep telling users baseline is a
Comment thread
robobun marked this conversation as resolved.
Outdated
});
Loading