Das Konfigurieren einer Entwicklungsumgebung für Bun kann 10-30 Minuten dauern, abhängig von Ihrer Internetverbindung und Computergeschwindigkeit. Sie benötigen etwa 10 GB freien Festplattenspeicher für das Repository und Build-Artefakte.

Wenn Sie Windows verwenden, lesen Sie bitte diese Anleitung

Nix verwenden (Alternative)

Ein Nix-Flake wird als Alternative zur manuellen Installation von Abhängigkeiten bereitgestellt:

nix develop
# oder verwenden Sie explizit die reine Shell
# nix develop .#pure
export CMAKE_SYSTEM_PROCESSOR=$(uname -m)
bun bd

Dies bietet alle Abhängigkeiten in einer isolierten, reproduzierbaren Umgebung ohne sudo.

Abhängigkeiten installieren (manuell)

Installieren Sie Buns Abhängigkeiten mit dem Paketmanager Ihres Systems:

$ 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

Hinweis: Der Zig-Compiler wird automatisch von den Build-Skripten installiert und aktualisiert. Eine manuelle Installation ist nicht erforderlich.

Bevor Sie beginnen, müssen Sie bereits eine Release-Build von Bun installiert haben, da wir unseren Bundler verwenden, um unseren Code zu transpilieren und zu minifizieren, sowie für Code-Generierungsskripte.

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

$ npm install -g bun

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

Optional: sccache installieren

sccache wird verwendet, um Kompilierungsartefakte zu cachen und Builds erheblich zu beschleunigen. Es muss mit S3-Unterstützung installiert werden:

# Für macOS
$ brew install sccache

# Für Linux. Beachten Sie, dass die Version in Ihrem Paketmanager möglicherweise keine S3-Unterstützung hat.
$ cargo install sccache --features=s3

Dies installiert sccache mit S3-Unterstützung. Unsere Build-Skripte erkennen und verwenden sccache automatisch mit unserem gemeinsamen S3-Cache. Hinweis: Nicht alle Versionen von sccache sind mit S3-Unterstützung kompiliert, daher empfehlen wir die Installation über cargo.

AWS-Anmeldedaten für sccache registrieren (nur für Core-Entwickler)

Core-Entwickler haben Schreibzugriff auf den gemeinsamen S3-Cache. Um Schreibzugriff zu aktivieren, müssen Sie sich mit AWS-Anmeldedaten anmelden. Der einfachste Weg dies zu tun, ist die aws CLI zu verwenden und aws configure aufzurufen, um Ihre AWS-Sicherheitsinformationen bereitzustellen.

Die cmake-Skripte sollten Ihre AWS-Anmeldedaten automatisch aus der Umgebung oder der ~/.aws/credentials-Datei erkennen.

Anmeldung bei der `aws` CLI

1. Installieren Sie die AWS CLI, indem Sie der [offiziellen Anleitung](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) folgen.
2. Melden Sie sich bei Ihrer AWS-Kontokonsole an. Ein Teammitglied sollte Ihnen Ihre Anmeldedaten zur Verfügung stellen.
3. Klicken Sie oben rechts auf Ihren Namen > Sicherheitsanmeldedaten.
4. Scrollen Sie zu "Zugriffsschlüssel" und erstellen Sie einen neuen Zugriffsschlüssel.
5. Führen Sie `aws configure` in Ihrem Terminal aus und geben Sie die Zugriffsschlüssel-ID und den geheimen Zugriffsschlüssel ein, wenn Sie dazu aufgefordert werden.

Häufige Probleme, auf die Sie stoßen können

- Um zu bestätigen, dass der Cache verwendet wird, können Sie den Befehl `sccache --show-stats` direkt nach einem Build verwenden. Dies zeigt sehr nützliche Statistiken, einschließlich Cache-Hits/Misses.
- Wenn Sie mehrere AWS-Profile konfiguriert haben, stellen Sie sicher, dass das richtige Profil in der `AWS_PROFILE`-Umgebungsvariablen festgelegt ist.
- `sccache` folgt einem Server-Client-Modell. Wenn Sie auf seltsame Probleme stoßen, bei denen `sccache` sich weigert, S3 zu verwenden, obwohl Sie AWS-Anmeldedaten konfiguriert haben, versuchen Sie, alle laufenden `sccache`-Server mit `sccache --stop-server` zu beenden und den Build erneut auszuführen.

LLVM installieren

Bun benötigt LLVM 19 (clang ist Teil von LLVM). Diese Versionsanforderung dient der Übereinstimmung mit WebKit (vorkompiliert), da nicht übereinstimmende Versionen zu Speicherzuweisungsfehlern zur Laufzeit führen. In den meisten Fällen können Sie LLVM über Ihren Systempaketmanager installieren:

$ brew install llvm@19

$ # LLVM hat ein automatisches Installationsskript, das mit allen Ubuntu-Versionen kompatibel ist
$ 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

Wenn keine der oben genannten Lösungen zutrifft, müssen Sie es manuell installieren.

Stellen Sie sicher, dass Clang/LLVM 19 in Ihrem Pfad ist:

$ which clang-19

Wenn nicht, führen Sie dies aus, um es manuell hinzuzufügen:

# verwenden Sie fish_add_path, wenn Sie fish verwenden
# verwenden Sie path+="$(brew --prefix llvm@19)/bin", wenn Sie zsh verwenden
$ export PATH="$(brew --prefix llvm@19)/bin:$PATH"

# verwenden Sie fish_add_path, wenn Sie fish verwenden
$ export PATH="$PATH:/usr/lib/llvm19/bin"

Bun erstellen

Nachdem Sie das Repository geklont haben, führen Sie den folgenden Befehl aus, um zu bauen. Dies kann eine Weile dauern, da Submodule geklont und Abhängigkeiten gebaut werden.

bun run build

Die Binärdatei befindet sich unter ./build/debug/bun-debug. Es wird empfohlen, dies zu Ihrem $PATH hinzuzufügen. Um zu überprüfen, ob der Build funktioniert hat, drucken wir die Versionsnummer des Entwicklungs-Builds von Bun.

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

VSCode

VSCode ist die empfohlene IDE für die Arbeit an Bun, da sie konfiguriert wurde. Nach dem Öffnen können Sie Extensions: Show Recommended Extensions ausführen, um die empfohlenen Erweiterungen für Zig und C++ zu installieren. ZLS wird automatisch konfiguriert.

Wenn Sie einen anderen Editor verwenden, stellen Sie sicher, dass Sie ZLS anweisen, den automatisch installierten Zig-Compiler zu verwenden, der sich unter ./vendor/zig/zig.exe befindet. Der Dateiname ist zig.exe, damit er unter Windows wie erwartet funktioniert, aber er funktioniert auch unter macOS/Linux (er hat nur eine überraschende Dateierweiterung).

Wir empfehlen, ./build/debug zu Ihrem $PATH hinzuzufügen, damit Sie bun-debug in Ihrem Terminal ausführen können:

bun-debug

Debug-Builds ausführen

Das bd package.json-Skript kompiliert und führt einen Debug-Build von Bun aus und gibt nur die Ausgabe des Build-Prozesses aus, wenn er fehlschlägt.

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

Bun benötigt etwa 2,5 Minuten, um einen Debug-Build zu kompilieren, wenn Zig-Änderungen vorgenommen werden. Wenn Ihr Entwicklungs-Workflow "eine Zeile ändern, speichern, neu bauen" lautet, verbringen Sie zu viel Zeit mit dem Warten auf den Build. Stattdessen:

• Bündeln Sie Ihre Änderungen
• Stellen Sie sicher, dass zls mit inkrementellem Watching für LSP-Fehler läuft (wenn Sie VSCode verwenden und Zig installieren und bun run build einmal ausführen, um Zig herunterzuladen, sollte dies einfach funktionieren)
• Verwenden Sie vorzugsweise den Debugger ("CodeLLDB" in VSCode), um den Code Schritt für Schritt zu durchlaufen.
• Verwenden Sie Debug-Logs. BUN_DEBUG_<scope>=1 aktiviert Debug-Logging für den entsprechenden Output.scoped(.<scope>, .hidden)-Logs. Sie können auch BUN_DEBUG_QUIET_LOGS=1 setzen, um alle Debug-Logs zu deaktivieren, die nicht explizit aktiviert sind. Um Debug-Logs in eine Datei zu dumpen, BUN_DEBUG=<path-to-file>.log. Debug-Logs werden in Release-Builds aggressiv entfernt.
• src/js/**.ts-Änderungen sind ziemlich sofort neu zu bauen. C++-Änderungen sind etwas langsamer, aber immer noch viel schneller als der Zig-Code (Zig ist eine Kompilierungseinheit, C++ ist viele).

Code-Generierungsskripte

Mehrere Code-Generierungsskripte werden während Buns Build-Prozess verwendet. Diese werden automatisch ausgeführt, wenn Änderungen an bestimmten Dateien vorgenommen werden.

Insbesondere sind dies:

• ./src/codegen/generate-jssink.ts -- Generiert build/debug/codegen/JSSink.cpp, build/debug/codegen/JSSink.h, die verschiedene Klassen für die Schnittstelle mit ReadableStream implementieren. So funktionieren intern FileSink, ArrayBufferSink, "type": "direct"-Streams und anderer Code im Zusammenhang mit Streams.
• ./src/codegen/generate-classes.ts -- Generiert build/debug/codegen/ZigGeneratedClasses*, was Zig & C++-Bindings für JavaScriptCore-Klassen generiert, die in Zig implementiert sind. In **/*.classes.ts-Dateien definieren wir die Schnittstellen für verschiedene Klassen, Methoden, Prototypen, Getter/Setter usw., die der Code-Generator liest, um Boilerplate-Code zu generieren, der die JavaScript-Objekte in C++ implementiert und sie mit Zig verbindet.
• ./src/codegen/cppbind.ts -- Generiert automatische Zig-Bindings für C++-Funktionen, die mit [[ZIG_EXPORT]]-Attributen markiert sind.
• ./src/codegen/bundle-modules.ts -- Bündelt eingebaute Module wie node:fs, bun:ffi in Dateien, die wir in die endgültige Binärdatei einfügen können. In der Entwicklung können diese neu geladen werden, ohne Zig neu zu bauen (Sie müssen immer noch bun run build ausführen, aber es liest danach die transpilierten Dateien von der Festplatte neu). In Release-Builds sind diese in die Binärdatei eingebettet.
• ./src/codegen/bundle-functions.ts -- Bündelt global zugängliche Funktionen, die in JavaScript/TypeScript implementiert sind, wie ReadableStream, WritableStream und einige weitere. Diese werden ähnlich wie die eingebauten Module verwendet, aber die Ausgabe entspricht mehr dem, was WebKit/Safari für Safaris eingebaute Funktionen tut, damit wir die Implementierungen von WebKit als Ausgangspunkt kopieren können.

ESM-Module modifizieren

Bestimmte Module wie node:fs, node:stream, bun:sqlite und ws sind in JavaScript implementiert. Diese befinden sich in src/js/{node,bun,thirdparty}-Dateien und werden mit Bun vorab gebündelt.

Release-Build

Um einen Release-Build von Bun zu kompilieren, führen Sie aus:

bun run build:release

Die Binärdatei befindet sich unter ./build/release/bun und ./build/release/bun-profile.

Release-Build von Pull-Requests herunterladen

Um Ihnen Zeit zu sparen, die Sie mit dem lokalen Erstellen eines Release-Builds verbringen, bieten wir eine Möglichkeit, Release-Builds von Pull-Requests auszuführen. Dies ist nützlich, um Änderungen manuell in einem Release-Build zu testen, bevor sie zusammengeführt werden.

Um einen Release-Build von einem Pull-Request auszuführen, können Sie das bun-pr npm-Paket verwenden:

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> # Nur Linux x64

Dies lädt den Release-Build vom Pull-Request herunter und fügt ihn als bun-${pr-number} zu $PATH hinzu. Sie können den Build dann mit bun-${pr-number} ausführen.

bun-1234566 --version

Dies funktioniert, indem der Release-Build von den GitHub Actions-Artefakten im verknüpften Pull-Request heruntergeladen wird. Möglicherweise benötigen Sie die gh CLI installiert, um sich bei GitHub zu authentifizieren.

AddressSanitizer

AddressSanitizer hilft beim Finden von Speicherproblemen und ist standardmäßig in Debug-Builds von Bun unter Linux und macOS aktiviert. Dies umfasst den Zig-Code und alle Abhängigkeiten. Es bewirkt, dass der Zig-Code etwa 2x länger zum Bauen benötigt. Wenn Sie dadurch nicht produktiv sein können, können Sie es deaktivieren, indem Sie -Denable_asan=$<IF:$<BOOL:${ENABLE_ASAN}>,true,false> auf -Denable_asan=false in der cmake/targets/BuildBun.cmake-Datei setzen, aber im Allgemeinen empfehlen wir, Ihre Änderungen zwischen den Builds zu bündeln.

Um einen Release-Build mit Address Sanitizer zu erstellen, führen Sie aus:

bun run build:release:asan

In CI führen wir unsere Test-Suite mit mindestens einem Ziel aus, das mit Address Sanitizer gebaut wurde.

WebKit lokal erstellen + Debug-Modus von JSC

WebKit wird standardmäßig nicht geklont (um Zeit und Festplattenspeicher zu sparen). Um WebKit lokal zu klonen und zu bauen, führen Sie aus:

# WebKit nach ./vendor/WebKit klonen
$ git clone https://github.com/oven-sh/WebKit vendor/WebKit

# Den Commit-Hash auschecken, der in `set(WEBKIT_VERSION <commit_hash>)` in cmake/tools/SetupWebKit.cmake angegeben ist
$ git -C vendor/WebKit checkout <commit_hash>

# Einen Debug-Build von JSC erstellen. Dies gibt Build-Artefakte in ./vendor/WebKit/WebKitBuild/Debug aus
# Optional können Sie `bun run jsc:build` für einen Release-Build verwenden
bun run jsc:build:debug && rm vendor/WebKit/WebKitBuild/Debug/JavaScriptCore/DerivedSources/inspector/InspectorProtocolObjects.h

# Nach einem ersten Lauf von `make jsc-debug` können Sie JSC neu bauen mit:
$ cmake --build vendor/WebKit/WebKitBuild/Debug --target jsc && rm vendor/WebKit/WebKitBuild/Debug/JavaScriptCore/DerivedSources/inspector/InspectorProtocolObjects.h

# Bun mit dem lokalen JSC-Build erstellen
bun run build:local

Die Verwendung von bun run build:local baut Bun im ./build/debug-local-Verzeichnis (anstelle von ./build/debug). Sie müssen einige Stellen ändern, um dieses neue Verzeichnis zu verwenden:

• Die erste Zeile in src/js/builtins.d.ts
• Die CompilationDatabase-Zeile in der .clangd-Konfiguration sollte CompilationDatabase: build/debug-local sein
• In build.zig sollte die codegen_path-Option build/debug-local/codegen sein (anstelle von build/debug/codegen)
• In .vscode/launch.json verwenden viele Konfigurationen ./build/debug/, ändern Sie diese nach Bedarf

Beachten Sie, dass der WebKit-Ordner einschließlich Build-Artefakten 8 GB+ groß ist.

Wenn Sie einen JSC-Debug-Build verwenden und VSCode nutzen, stellen Sie sicher, dass Sie den Befehl C/C++: Select a Configuration ausführen, um Intellisense so zu konfigurieren, dass es die Debug-Header findet.

Beachten Sie, dass wenn Sie Änderungen an unserem WebKit-Fork vornehmen, Sie auch SetupWebKit.cmake ändern müssen, um auf den Commit-Hash zu verweisen.

Fehlerbehebung

'span'-Datei nicht gefunden auf Ubuntu

Der Clang-Compiler verwendet standardmäßig typischerweise die libstdc++ C++-Standardbibliothek. libstdc++ ist die Standard-C++-Standardbibliothek, die vom GNU Compiler Collection (GCC) bereitgestellt wird. Während Clang möglicherweise gegen die libc++-Bibliothek linkt, erfordert dies das explizite Angeben des -stdlib-Flags beim Ausführen von Clang.

Bun verwendet C++20-Funktionen wie std::span, die in GCC-Versionen unter 11 nicht verfügbar sind. GCC 10 hat nicht alle C++20-Funktionen implementiert. Als Ergebnis kann make setup mit dem folgenden Fehler fehlschlagen:

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

Das Problem kann sich beim ersten Ausführen von bun setup als Clang zeigen, das nicht in der Lage ist, ein einfaches Testprogramm zu kompilieren:

The C++ compiler

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

is not able to compile a simple test program.

Um den Fehler zu beheben, müssen wir die GCC-Version auf 11 aktualisieren. Dazu müssen wir prüfen, ob die neueste Version in den offiziellen Repositories der Distribution verfügbar ist, oder ein Drittanbieter-Repository verwenden, das GCC 11-Pakete bereitstellt. Hier sind allgemeine Schritte:

$ sudo apt update
$ sudo apt install gcc-11 g++-11
# Wenn der obige Befehl mit `Unable to locate package gcc-11` fehlschlägt, müssen wir das APT-Repository hinzufügen
$ sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
# Führen Sie nun `apt install` erneut aus
$ sudo apt install gcc-11 g++-11

Jetzt müssen wir GCC 11 als Standardcompiler festlegen:

$ 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

Wenn Sie auf macOS einen Fehler beim Kompilieren von libarchive sehen, führen Sie aus:

$ brew install pkg-config

macOS library not found for -lSystem

Wenn Sie diesen Fehler beim Kompilieren sehen, führen Sie aus:

$ xcode-select --install

Kann libatomic.a nicht finden

Bun linkt standardmäßig libatomic statisch, da nicht alle Systeme es haben. Wenn Sie auf einer Distribution bauen, die keine statische libatomic verfügbar hat, können Sie den folgenden Befehl ausführen, um dynamisches Linken zu aktivieren:

bun run build -DUSE_STATIC_LIBATOMIC=OFF

Die gebaute Version von Bun funktioniert möglicherweise nicht auf anderen Systemen, wenn sie auf diese Weise kompiliert wurde.

bun-debug verwenden

• Logging deaktivieren: BUN_DEBUG_QUIET_LOGS=1 bun-debug ... (um alle Debug-Logs zu deaktivieren)
• Logging für einen bestimmten Zig-Scope aktivieren: BUN_DEBUG_EventLoop=1 bun-debug ... (um std.log.scoped(.EventLoop) zuzulassen)
• Bun transpiliert jede Datei, die es ausführt. Um die tatsächlich ausgeführte Quelle in einem Debug-Build zu sehen, finden Sie sie unter /tmp/bun-debug-src/...path/to/file, zum Beispiel wäre die transpilierte Version von /home/bun/index.ts in /tmp/bun-debug-src/home/bun/index.ts