Bun の開発環境の構成は、インターネット接続とコンピューターの速度に応じて 10〜30 分かかる場合があります。リポジトリとビルドアーティファクトには約 10GB の空きディスク容量が必要です。

Windows を使用している場合は、このガイド を参照してください。

Nix の使用（代替）

手動での依存関係のインストールの代替として、Nix flake が提供されています：

nix develop
# または明示的に pure シェルを使用
# nix develop .#pure
export CMAKE_SYSTEM_PROCESSOR=$(uname -m)
bun bd

これは、sudo を必要とせずに、分離された再現可能な環境ですべての依存関係を提供します。

依存関係のインストール（手動）

システムのパッケージマネージャーを使用して、Bun の依存関係をインストールします：

$ brew install automake cmake coreutils gnu-sed go icu4c libiconv libtool ninja pkg-config rust ruby sccache

$ sudo apt install curl wget lsb-release software-properties-common cargo cmake git golang libtool ninja-build pkg-config rustc ruby-full xz-utils

$ sudo pacman -S base-devel cmake git go libiconv libtool make ninja pkg-config python rust sed unzip ruby

$ sudo dnf install cargo clang19 llvm19 lld19 cmake git golang libtool ninja-build pkg-config rustc ruby libatomic-static libstdc++-static sed unzip which libicu-devel 'perl(Math::BigInt)'

$ sudo zypper install go cmake ninja automake git icu rustup && rustup toolchain install stable

注: Zig コンパイラーはビルドスクリプトによって自動的にインストールおよび更新されます。手動インストールは必要ありません。

開始する前に、すでに Bun のリリースビルドがインストールされている必要があります。コードのトランスパイルとミニファイ、およびコード生成スクリプトにバンデラーを使用するためです。

$ curl -fsSL https://bun.com/install | bash

$ npm install -g bun

$ brew tap oven-sh/bun
$ brew install bun

オプション：sccache のインストール

sccache はコンパイル成果物をキャッシュし、ビルドを大幅に高速化するために使用されます。S3 サポート付きでインストールする必要があります：

# macOS の場合
$ brew install sccache

# Linux の場合。パッケージマネージャーのバージョンには S3 サポートがない場合があります。
$ cargo install sccache --features=s3

これにより、S3 サポート付きで sccache がインストールされます。ビルドスクリプトは、共有 S3 キャッシュを使用して sccache を自動的に検出および使用します。注: すべてのバージョンの sccache が S3 サポート付きでコンパイルされているわけではないため、cargo でのインストールを推奨します。

sccache の AWS 認証情報の登録（コア開発者のみ）

コア開発者は、共有 S3 キャッシュへの書き込みアクセス権を持っています。書き込みアクセスを有効にするには、AWS 認証情報でログインする必要があります。これを行う最も簡単な方法は、aws CLI をインストールし、aws configure を呼び出して AWS 認証情報を提供すること です。

cmake スクリプトは、環境または ~/.aws/credentials ファイルから AWS 認証情報を自動的に検出します。

`aws` CLI へのログイン

1. [公式ガイド](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) に従って AWS CLI をインストールします。
2. AWS アカウントコンソールにログインします。チームメンバーが認証情報を提供します。
3. 右上の名前をクリック > セキュリティ認証情報。
4. 「アクセスキー」までスクロールし、新しいアクセスキーを作成します。
5. ターミナルで `aws configure` を実行し、プロンプトに従ってアクセスキー ID とシークレットアクセスキーを入力します。

よくある問題

- キャッシュが使用されていることを確認するには、ビルド直後に `sccache --show-stats` コマンドを使用できます。これにより、キャッシュヒット/ミスなど、非常に有用な統計情報が表示されます。
- 複数の AWS プロファイルが構成されている場合は、`AWS_PROFILE` 環境変数で正しいプロファイルが設定されていることを確認してください。
- `sccache` はサーバークライアントモデルに従います。AWS 認証情報が構成されているにもかかわらず、`sccache` が S3 を使用しない奇妙な問題が発生した場合は、`sccache --stop-server` で実行中の `sccache` サーバーを停止し、ビルドを再実行してみてください。

LLVM のインストール

Bun には LLVM 19 が必要です（clang は LLVM の一部です）。このバージョン要件は、WebKit（事前コンパイル済み）に一致するためです。バージョンが一致しないと、ランタイムでメモリアロケーションの失敗が発生します。ほとんどの場合、システムパッケージマネージャーを通じて LLVM をインストールできます：

$ brew install llvm@19

$ # LLVM には、すべてのバージョンの Ubuntu と互換性のある自動インストールスクリプトがあります
$ wget https://apt.llvm.org/llvm.sh -O - | sudo bash -s -- 19 all

$ sudo pacman -S llvm clang lld

$ sudo dnf install llvm clang lld-devel

$ sudo zypper install clang19 lld19 llvm19

上記の解決策のいずれも適用できない場合は、手動 でインストールする必要があります。

Clang/LLVM 19 がパスにあることを確認します：

$ which clang-19

そうでない場合は、これを手動で追加します：

# fish を使用している場合は fish_add_path を使用
# zsh を使用している場合は path+="$(brew --prefix llvm@19)/bin" を使用
$ export PATH="$(brew --prefix llvm@19)/bin:$PATH"

# fish を使用している場合は fish_add_path を使用
$ export PATH="$PATH:/usr/lib/llvm19/bin"

Bun のビルド

リポジトリをクローンした後、次のコマンドを実行してビルドします。サブモジュールをクローンし、依存関係をビルドするため、これには時間がかかる場合があります。

bun run build

バイナリは ./build/debug/bun-debug に配置されます。これを $PATH に追加することを推奨します。ビルドが成功したことを確認するために、Bun の開発ビルドでバージョン番号を表示してみましょう。

$ build/debug/bun-debug --version
x.y.z_debug

VSCode

VSCode は、設定されているため、Bun の作業に推奨される IDE です。開いたら、Extensions: Show Recommended Extensions を実行して、Zig および C++ 用の推奨拡張機能をインストールできます。ZLS は自動的に構成されます。

別のエディターを使用する場合は、ZLS に自動的にインストールされた Zig コンパイラーを使用するように指示してください。これは ./vendor/zig/zig.exe にあります。ファイル名は Windows で期待通りに動作するように zig.exe ですが、macOS/Linux でも機能します（驚くべきファイル拡張子があるだけです）。

ターミナルで bun-debug を実行できるように、./build/debug を $PATH に追加することを推奨します：

bun-debug

デバッグビルドの実行

bd package.json スクリプトは、Bun のデバッグビルドをコンパイルおよび実行し、失敗した場合にのみビルドプロセスの出力を表示します。

bun bd <args>
bun bd test foo.test.ts
bun bd ./foo.ts

Bun は、Zig の変更がある場合、デバッグビルドのコンパイルに約 2.5 分かかります。開発ワークフローが「1 行変更、保存、再ビルド」である場合、ビルドの完了を待つのに多くの時間を費やすことになります。代わりに：

• 変更をまとめて行う
• ZLS が LSP エラーの増分ウォッチングを実行していることを確認する（VSCode を使用して Zig をインストールし、bun run build を 1 回実行して Zig をダウンロードすると、これは動作するはずです）
• デバッガー（VSCode の「CodeLLDB」）を使用してコードをステップスルーすることを優先する
• デバッグログを使用する。BUN_DEBUG_<scope>=1 は、対応する Output.scoped(.<scope>, .hidden) ログのデバッグログを有効にします。また、BUN_DEBUG_QUIET_LOGS=1 を設定して、明示的に有効にされていないすべてのデバッグログを無効にすることもできます。デバッグログをファイルにダンプするには、BUN_DEBUG=<path-to-file>.log を使用します。デバッグログはリリースビルドで積極的に削除されます。
• src/js/**/*.ts の変更は、再ビルドが非常に高速です。C++ の変更は少し遅いですが、Zig コード（Zig は 1 つのコンパイルユニット、C++ は多数）よりもはるかに高速です。

コード生成スクリプト

Bun のビルドプロセス中に、いくつかのコード生成スクリプトが使用されます。これらは、特定のファイルに変更が行われたときに自動的に実行されます。

特に、以下があります：

• ./src/codegen/generate-jssink.ts -- ReadableStream とインターフェースするためのさまざまなクラスを実装する build/debug/codegen/JSSink.cpp、build/debug/codegen/JSSink.h を生成します。これは内部的に FileSink、ArrayBufferSink、"type": "direct" ストリーム、およびストリームに関連する他のコードが機能する方法です。
• ./src/codegen/generate-classes.ts -- build/debug/codegen/ZigGeneratedClasses* を生成します。これは、Zig で実装された JavaScriptCore クラスの Zig および C++ バインディングを生成します。**/*.classes.ts ファイルでは、さまざまなクラス、メソッド、プロトタイプ、ゲッター/セッターなどのインターフェースを定義し、コードジェネレーターがこれを読み取って、JavaScript オブジェクトを C++ で実装し、Zig に接続するためのボイラープレートコードを生成します。
• ./src/codegen/cppbind.ts -- [[ZIG_EXPORT]] 属性でマークされた C++ 関数の自動 Zig バインディングを生成します。
• ./src/codegen/bundle-modules.ts -- node:fs、bun:ffi などの組み込みモジュールを、最終バイナリに含めることができるファイルにバンドルします。開発中は、Zig を再ビルドせずにこれらをリロードできます（bun run build を実行する必要がありますが、その後ディスクからトランスパイルされたファイルを再読み込みします）。リリースビルドでは、これらはバイナリに埋め込まれます。
• ./src/codegen/bundle-functions.ts -- ReadableStream、WritableStream、およびその他のいくつかの、JavaScript/TypeScript で実装されたグローバルアクセス可能関数をバンドルします。これらは組み込みモジュールと同様に使用されますが、出力は WebKit/Safari が Safari の組み込み関数に対して行うものに密接に一致し、実装を WebKit からコピーペーストして出発点として使用できるようにします。

ESM モジュールの変更

node:fs、node:stream、bun:sqlite、ws などの特定のモジュールは JavaScript で実装されています。これらは src/js/{node,bun,thirdparty} ファイルにあり、Bun を使用して事前バンドルされています。

リリースビルド

Bun のリリースビルドをコンパイルするには、次を実行します：

bun run build:release

バイナリは ./build/release/bun および ./build/release/bun-profile に配置されます。

プルリクエストからリリースビルドをダウンロード

ローカルでリリースビルドを構築する時間を節約するために、プルリクエストからリリースビルドを実行する方法を提供しています。これは、マージ前にリリースビルドで変更を手動でテストする場合に役立ちます。

プルリクエストからリリースビルドを実行するには、bun-pr npm パッケージを使用できます：

bunx bun-pr <pr-number>
bunx bun-pr <branch-name>
bunx bun-pr "https://github.com/oven-sh/bun/pull/1234566"
bunx bun-pr --asan <pr-number> # Linux x64 のみ

これにより、プルリクエストからリリースビルドをダウンロードし、$PATH に bun-${pr-number} として追加します。その後、bun-${pr-number} でビルドを実行できます。

bun-1234566 --version

これは、リンクされたプルリクエストの GitHub Actions アーティファクトからリリースビルドをダウンロードすることで機能します。GitHub での認証に gh CLI が必要になる場合があります。

AddressSanitizer

AddressSanitizer は、メモリ問題を見つけるのに役立ち、Linux および macOS の Bun のデバッグビルドでデフォルトで有効になっています。これには Zig コードとすべての依存関係が含まれます。Zig コードのビルドに約 2 倍の時間がかかるため、生産性の妨げになる場合は、cmake/targets/BuildBun.cmake ファイルで -Denable_asan=$<IF:$<BOOL:${ENABLE_ASAN}>,true,false> を -Denable_asan=false に設定して無効にできますが、一般的にはビルド間に変更をまとめることを推奨します。

Address Sanitizer でリリースビルドをビルドするには、次を実行します：

bun run build:release:asan

CI では、Address Sanitizer でビルドされた少なくとも 1 つのターゲットでテストスイートを実行します。

WebKit のローカルビルド + JSC のデバッグモード

WebKit はデフォルトではクローンされません（時間とディスク容量を節約するため）。WebKit をローカルでクローンおよびビルドするには、次を実行します：

# WebKit を ./vendor/WebKit にクローン
$ git clone https://github.com/oven-sh/WebKit vendor/WebKit

# cmake/tools/SetupWebKit.cmake の `set(WEBKIT_VERSION <commit_hash>)` で指定されたコミットハッシュをチェックアウト
$ git -C vendor/WebKit checkout <commit_hash>

# JSC のデバッグビルドを作成。これにより、ビルド成果物が ./vendor/WebKit/WebKitBuild/Debug に出力されます
# オプションで、リリースビルドには `bun run jsc:build` を使用できます
bun run jsc:build:debug && rm vendor/WebKit/WebKitBuild/Debug/JavaScriptCore/DerivedSources/inspector/InspectorProtocolObjects.h

# `make jsc-debug` の初回実行後、JSC を再ビルドするには：
$ cmake --build vendor/WebKit/WebKitBuild/Debug --target jsc && rm vendor/WebKit/WebKitBuild/Debug/JavaScriptCore/DerivedSources/inspector/InspectorProtocolObjects.h

# ローカル JSC ビルドで bun をビルド
bun run build:local

bun run build:local を使用すると、Bun は ./build/debug ディレクトリ（./build/debug の代わりに）にビルドされます。これを使用するには、いくつかの場所を変更する必要があります：

• src/js/builtins.d.ts の最初の行
• .clangd 設定の CompilationDatabase 行は CompilationDatabase: build/debug-local である必要があります
• build.zig では、codegen_path オプションは build/debug-local/codegen である必要があります（build/debug/codegen の代わりに）
• .vscode/launch.json では、多くの設定で ./build/debug/ が使用されているため、必要に応じて変更してください

WebKit フォルダーは、ビルド成果物を含めて 8GB 以上です。

JSC デバッグビルドを使用していて、VSCode を使用している場合は、C/C++: Select a Configuration コマンドを実行して、インテリセンスがデバッグヘッダーを見つけるように構成してください。

WebKit フォーク に変更を加える場合は、SetupWebKit.cmake を変更してコミットハッシュを指すようにする必要があることにも注意してください。

トラブルシューティング

Ubuntu での 'span' ファイルが見つからない

Clang コンパイラーは通常、デフォルトで libstdc++ C++ 標準ライブラリを使用します。libstdc++ は、GNU Compiler Collection（GCC）によって提供されるデフォルトの C++ 標準ライブラリ実装です。Clang は libc++ ライブラリにリンクする場合がありますが、これには Clang を実行する際に -stdlib フラグを明示的に指定する必要があります。

Bun は std::span のような C++20 機能に依存しており、これらは GCC 11 未満では利用できません。GCC 10 には C++20 機能がすべて実装されていません。その結果、make setup の実行が以下のエラーで失敗する場合があります：

fatal error: 'span' file not found
#include <span>
         ^~~~~~

この問題は、最初に bun setup を実行する際に、Clang が単純なプログラムをコンパイルできないとして現れる場合があります：

The C++ compiler

  "/usr/bin/clang++-19"

is not able to compile a simple test program.

エラーを修正するには、GCC バージョンを 11 に更新する必要があります。これを行うには、最新のバージョンがディストリビューションの公式リポジトリで利用可能かどうかを確認するか、GCC 11 パッケージを提供するサードパーティのリポジトリを使用する必要があります。以下は一般的な手順です：

$ sudo apt update
$ sudo apt install gcc-11 g++-11
# 上記のコマンドが `Unable to locate package gcc-11` で失敗する場合は、APT リポジトリを追加する必要があります
$ sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
# 次に `apt install` を再度実行します
$ sudo apt install gcc-11 g++-11

次に、GCC 11 をデフォルトのコンパイラーとして設定する必要があります：

$ sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-11 100
$ sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-11 100

libarchive

macOS で libarchive のコンパイル時にエラーが表示された場合は、次を実行します：

$ brew install pkg-config

macOS の library not found for -lSystem

コンパイル時にこのエラーが表示された場合は、次を実行します：

$ xcode-select --install

libatomic.a が見つからない

Bun は、すべてのシステムがそれを持っているわけではないため、libatomic の静的リンクをデフォルトにしています。静的 libatomic を提供していないディストロでビルドしている場合は、動的リンクを有効にするために次のコマンドを実行できます：

bun run build -DUSE_STATIC_LIBATOMIC=OFF

このようにコンパイルされたバージョンの Bun は、他のシステムで機能しない場合があります。

bun-debug の使用

• ロギングを無効にする：BUN_DEBUG_QUIET_LOGS=1 bun-debug ...（すべてのデバッグログを無効にする）
• 特定の zig スコープのロギングを有効にする：BUN_DEBUG_EventLoop=1 bun-debug ...（std.log.scoped(.EventLoop) を許可）
• Bun は実行するすべてのファイルをトランスパイルします。デバッグビルドで実際に実行されたソースを表示するには、/tmp/bun-debug-src/...path/to/file で見つけます。例えば、/home/bun/index.ts のトランスパイルされたバージョンは /tmp/bun-debug-src/home/bun/index.ts にあります。