diff --git a/README.md b/README.md index 3344866c99bb..c507cc5dec62 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/docs/bundler/executables.mdx b/docs/bundler/executables.mdx index 77cb6a6ba3c4..1f228827dcfc 100644 --- a/docs/bundler/executables.mdx +++ b/docs/bundler/executables.mdx @@ -51,19 +51,11 @@ To build for Linux x64 (most servers): ```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 ``` ```ts build.ts icon="/icons/typescript.svg" - // Standard Linux x64 await Bun.build({ entrypoints: ["./index.ts"], compile: { @@ -71,24 +63,6 @@ To build for Linux x64 (most servers): 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", - }, - }); ``` @@ -123,19 +97,12 @@ 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 ``` ```ts build.ts icon="/icons/typescript.svg" - // Standard Windows x64 await Bun.build({ entrypoints: ["./path/to/my/app.ts"], compile: { @@ -143,15 +110,6 @@ To build for 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", - }, - }); ``` @@ -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 | - - 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. - + + 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. + --- @@ -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 diff --git a/docs/installation.mdx b/docs/installation.mdx index be6531858e93..da4c07e43a2f 100644 --- a/docs/installation.mdx +++ b/docs/installation.mdx @@ -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 - For older CPUs without AVX2 + ARM64 Linux systems - Standard Windows binary - - - For older CPUs without AVX2 + Nehalem or newer Intel Macs - - ARM64 Linux systems - ### Musl Binaries @@ -295,7 +281,6 @@ To download Bun binaries directly, visit the [releases page on GitHub](https://g 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) @@ -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. - - - **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 | - - - - **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 | - - - Baseline builds are slower than regular builds. Use them only if you encounter an "Illegal - Instruction" error. - - - - +| Platform | Intel Requirement | AMD Requirement | +| -------- | ------------------------------- | ------------------ | +| x64 | Nehalem (1st gen Core) or newer | Bulldozer or newer | - 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. --- diff --git a/packages/bun-release/npm/@oven/bun-darwin-x64-baseline/README.md b/packages/bun-release/npm/@oven/bun-darwin-x64-baseline/README.md index 8196cdc74006..a454d23c3c7b 100644 --- a/packages/bun-release/npm/@oven/bun-darwin-x64-baseline/README.md +++ b/packages/bun-release/npm/@oven/bun-darwin-x64-baseline/README.md @@ -2,4 +2,4 @@ This is the macOS x64 binary for Bun, a fast all-in-one JavaScript runtime. https://bun.com -_Note: "Baseline" builds are for machines that do not support [AVX2](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions) instructions._ +_Note: This package is an alias of [`@oven/bun-darwin-x64`](https://www.npmjs.com/package/@oven/bun-darwin-x64). Bun ships a single x64 binary that targets Nehalem (SSE4.2) and dispatches AVX2/AVX-512 at runtime._ diff --git a/packages/bun-release/npm/@oven/bun-linux-x64-baseline/README.md b/packages/bun-release/npm/@oven/bun-linux-x64-baseline/README.md index 2e8bb84c0cb0..612a2cca8428 100644 --- a/packages/bun-release/npm/@oven/bun-linux-x64-baseline/README.md +++ b/packages/bun-release/npm/@oven/bun-linux-x64-baseline/README.md @@ -2,4 +2,4 @@ This is the Linux x64 binary for Bun, a fast all-in-one JavaScript runtime. https://bun.com -_Note: "Baseline" builds are for machines that do not support [AVX2](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions) instructions._ +_Note: This package is an alias of [`@oven/bun-linux-x64`](https://www.npmjs.com/package/@oven/bun-linux-x64). Bun ships a single x64 binary that targets Nehalem (SSE4.2) and dispatches AVX2/AVX-512 at runtime._ diff --git a/packages/bun-release/npm/@oven/bun-windows-x64-baseline/README.md b/packages/bun-release/npm/@oven/bun-windows-x64-baseline/README.md index fbb371458f2e..ae284dcd1361 100644 --- a/packages/bun-release/npm/@oven/bun-windows-x64-baseline/README.md +++ b/packages/bun-release/npm/@oven/bun-windows-x64-baseline/README.md @@ -2,4 +2,4 @@ This is the Windows x64 binary for Bun, a fast all-in-one JavaScript runtime. https://bun.com -_Note: "Baseline" builds are for machines that do not support [AVX2](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions) instructions._ +_Note: This package is an alias of [`@oven/bun-windows-x64`](https://www.npmjs.com/package/@oven/bun-windows-x64). Bun ships a single x64 binary that targets Nehalem (SSE4.2) and dispatches AVX2/AVX-512 at runtime._ diff --git a/packages/bun-release/npm/bun/README.md b/packages/bun-release/npm/bun/README.md index c8c0ec20af24..b8fdf4a833ac 100644 --- a/packages/bun-release/npm/bun/README.md +++ b/packages/bun-release/npm/bun/README.md @@ -18,13 +18,12 @@ bun upgrade - [macOS, arm64 (Apple Silicon)](https://www.npmjs.com/package/@oven/bun-darwin-aarch64) - [macOS, x64](https://www.npmjs.com/package/@oven/bun-darwin-x64) -- [macOS, x64 (without AVX2 instructions)](https://www.npmjs.com/package/@oven/bun-darwin-x64-baseline) - [Linux, arm64](https://www.npmjs.com/package/@oven/bun-linux-aarch64) - [Linux, x64](https://www.npmjs.com/package/@oven/bun-linux-x64) -- [Linux, x64 (without AVX2 instructions)](https://www.npmjs.com/package/@oven/bun-linux-x64-baseline) - [Windows, x64](https://www.npmjs.com/package/@oven/bun-windows-x64) -- [Windows, x64 (without AVX2 instructions)](https://www.npmjs.com/package/@oven/bun-windows-x64-baseline) -- [Windows ARM64](https://www.npmjs.com/package/@oven/bun-windows-aarch64) +- [Windows, arm64](https://www.npmjs.com/package/@oven/bun-windows-aarch64) + +The x64 binary targets Nehalem (SSE4.2) and dispatches AVX2/AVX-512 at runtime. The `@oven/bun-*-x64-baseline` packages are published as aliases of the same binary for backward compatibility. ### Future Platforms diff --git a/test/internal/release-asset-coherence.test.ts b/test/internal/release-asset-coherence.test.ts new file mode 100644 index 000000000000..f4803a3a01eb --- /dev/null +++ b/test/internal/release-asset-coherence.test.ts @@ -0,0 +1,109 @@ +// 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"; +import { platforms } from "../../packages/bun-release/src/platform"; + +const repo = join(import.meta.dir, "..", ".."); + +/** Set of `.zip` files the release step uploads to the GitHub release. */ +function releaseAssetSet(): Set { + 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(); + 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; +} + +/** + * Every `target` value install.sh can reach. Base values are parsed from the + * literal `target=` assignments so a new platform case in install.sh + * without a matching release asset fails here; the `-musl` / `-baseline` / + * `-profile` suffix transforms are stable cross-cutting logic applied on top. + */ +function installShTargets(): Set { + const sh = readFileSync(join(repo, "src/runtime/cli/install.sh"), "utf8"); + const bases = new Set([...sh.matchAll(/^\s*target=([a-z][a-z0-9-]+)\s*$/gm)].map(m => m[1])); + expect(bases.size).toBeGreaterThanOrEqual(5); + expect(bases).toContain("linux-x64"); + + const out = new Set(); + for (const base of bases) { + out.add(base); + if (base.startsWith("linux-")) out.add(`${base}-musl`); + } + for (const t of [...out]) { + // The AVX2 probe appends -baseline to *-x64* only. + if (t.includes("-x64") && !t.startsWith("windows-")) out.add(`${t}-baseline`); + } + for (const t of [...out]) out.add(`${t}-profile`); + return out; +} + +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", () => { + const targets = installShTargets(); + expect(targets.has("linux-x64-musl-baseline-profile")).toBe(true); + const missing = [...targets].map(t => `bun-${t}.zip`).filter(n => !assets.has(n)); + 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 bins = platforms.map(p => p.bin); + expect(bins.length).toBeGreaterThanOrEqual(14); + const missing = bins.map(b => `${b}.zip`).filter(name => !assets.has(name)); + expect(missing).toEqual([]); + }); + + test("docs and npm READMEs do not describe baseline as a separate x64 build", () => { + // The single x64 binary targets Nehalem (SSE4.2); AVX2 is runtime-dispatched. + // Keeps installation/--compile docs and the npmjs.com-visible READMEs from + // re-introducing the old "pick baseline if your CPU lacks AVX2" guidance. + const files = [ + "docs/installation.mdx", + "docs/bundler/executables.mdx", + "packages/bun-release/npm/bun/README.md", + "packages/bun-release/npm/@oven/bun-darwin-x64-baseline/README.md", + "packages/bun-release/npm/@oven/bun-linux-x64-baseline/README.md", + "packages/bun-release/npm/@oven/bun-windows-x64-baseline/README.md", + ]; + const stale = + /target the Haswell|require.{0,20}AVX2|without AVX2|do not support.{0,20}AVX2|modern is faster|baseline.{0,20}slower/i; + const offenders: string[] = []; + for (const file of files) { + const doc = readFileSync(join(repo, file), "utf8"); + const m = doc.match(stale); + if (m) offenders.push(`${file}: "${m[0]}"`); + } + expect(offenders).toEqual([]); + }); +});