La configurazione di un ambiente di sviluppo per Bun può richiedere 10-30 minuti a seconda della tua connessione internet e della velocità del computer. Avrai bisogno di ~10GB di spazio libero su disco per il repository e gli artifact di compilazione.

Se stai usando Windows, consulta questa guida

Usare Nix (Alternativa)

Un flake Nix è fornito come alternativa all'installazione manuale delle dipendenze:

nix develop
# oppure usa esplicitamente la shell pura
# nix develop .#pure
export CMAKE_SYSTEM_PROCESSOR=$(uname -m)
bun bd

Questo fornisce tutte le dipendenze in un ambiente isolato e riproducibile senza richiedere sudo.

Installare le Dipendenze (Manuale)

Usando il package manager del tuo sistema, installa le dipendenze di 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

Nota: Il compilatore Zig viene installato e aggiornato automaticamente dagli script di compilazione. Non è richiesta l'installazione manuale.

Prima di iniziare, dovrai già avere una build release di Bun installata, poiché usiamo il nostro bundler per traspile e minificare il nostro codice, così come per gli script di generazione del codice.

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

$ npm install -g bun

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

Opzionale: Installare sccache

sccache è usato per cacheare gli artifact di compilazione, accelerando significativamente le build. Deve essere installato con supporto S3:

# Per macOS
$ brew install sccache

# Per Linux. Nota che la versione nel tuo package manager potrebbe non avere supporto S3.
$ cargo install sccache --features=s3

Questo installerà sccache con supporto S3. I nostri script di compilazione rileveranno e useranno automaticamente sccache con la nostra cache S3 condivisa. Nota: Non tutte le versioni di sccache sono compilate con supporto S3, quindi raccomandiamo di installarlo tramite cargo.

Registrare le Credenziali AWS per sccache (Solo per Sviluppatori Core)

Gli sviluppatori core hanno accesso in scrittura alla cache S3 condivisa. Per abilitare l'accesso in scrittura, devi accedere con le credenziali AWS. Il modo più semplice per farlo è usare la aws CLI e invocare aws configure per fornire le tue informazioni di sicurezza AWS.

Gli script cmake dovrebbero rilevare automaticamente le tue credenziali AWS dall'ambiente o dal file ~/.aws/credentials.

Accedere alla CLI `aws`

1. Installa la AWS CLI seguendo [la guida ufficiale](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
2. Accedi alla console del tuo account AWS. Un membro del team dovrebbe fornirti le tue credenziali.
3. Clicca sul tuo nome in alto a destra > Security credentials.
4. Scorri fino a "Access keys" e crea una nuova chiave di accesso.
5. Esegui `aws configure` nel tuo terminale e fornisci l'ID della chiave di accesso e la chiave di accesso segreta quando richiesto.

Problemi Comuni che Potresti Incontrare

- Per confermare che la cache è in uso, puoi usare il comando `sccache --show-stats` subito dopo una build. Questo esporrà statistiche molto utili, inclusi cache hit/miss.
- Se hai più profili AWS configurati, assicurati che il profilo corretto sia impostato nella variabile d'ambiente `AWS_PROFILE`.
- `sccache` segue un modello server-client. Se incontri strani problemi in cui `sccache` si rifiuta di usare S3, anche se hai configurato le credenziali AWS, prova a terminare qualsiasi server `sccache` in esecuzione con `sccache --stop-server` e poi riavvia la build.

Installare LLVM

Bun richiede LLVM 19 (clang fa parte di LLVM). Questo requisito di versione è per corrispondere a WebKit (precompilato), poiché versioni non corrispondenti causeranno errori di allocazione di memoria a runtime. Nella maggior parte dei casi, puoi installare LLVM attraverso il package manager di sistema:

$ brew install llvm@19

$ # LLVM ha uno script di installazione automatico compatibile con tutte le versioni di 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

Se nessuna delle soluzioni sopra si applica, dovrai installarlo manualmente.

Assicurati che Clang/LLVM 19 sia nel tuo percorso:

$ which clang-19

Altrimenti, esegui questo per aggiungerlo manualmente:

# usa fish_add_path se stai usando fish
# usa path+="$(brew --prefix llvm@19)/bin" se stai usando zsh
$ export PATH="$(brew --prefix llvm@19)/bin:$PATH"

# usa fish_add_path se stai usando fish
$ export PATH="$PATH:/usr/lib/llvm19/bin"

Compilare Bun

Dopo aver clonato il repository, esegui il seguente comando per compilare. Questo potrebbe richiedere del tempo poiché clonerà i sottomoduli e compilerà le dipendenze.

bun run build

Il binario si troverà in ./build/debug/bun-debug. È raccomandato aggiungere questo al tuo $PATH. Per verificare che la compilazione abbia funzionato, stampiamo il numero di versione sulla build di sviluppo di Bun.

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

VSCode

VSCode è l'IDE raccomandato per lavorare su Bun, poiché è stato configurato. Una volta aperto, puoi eseguire Extensions: Show Recommended Extensions per installare le estensioni raccomandate per Zig e C++. ZLS è configurato automaticamente.

Se usi un editor diverso, assicurati di dire a ZLS di usare il compilatore Zig installato automaticamente, che si trova in ./vendor/zig/zig.exe. Il nome del file è zig.exe in modo che funzioni come previsto su Windows, ma funziona ancora su macOS/Linux (ha solo un'estensione di file sorprendente).

Raccomandiamo di aggiungere ./build/debug al tuo $PATH in modo da poter eseguire bun-debug nel tuo terminale:

bun-debug

Eseguire build di debug

Lo script package.json bd compila ed esegue una build di debug di Bun, stampando l'output del processo di build solo se fallisce.

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

Bun impiega circa 2,5 minuti per compilare una build di debug quando ci sono modifiche Zig. Se il tuo flusso di lavoro di sviluppo è "cambia una riga, salva, ricompila", passerai troppo tempo ad aspettare la fine della compilazione. Invece:

• Raggruppa le tue modifiche
• Assicurati che zls sia in esecuzione con il watching incrementale per gli errori LSP (se usi VSCode e installi Zig ed esegui bun run build una volta per scaricare Zig, questo dovrebbe funzionare)
• Preferisci usare il debugger ("CodeLLDB" in VSCode) per scorrere il codice.
• Usa i log di debug. BUN_DEBUG_<scope>=1 abiliterà il logging di debug per i log Output.scoped(.<scope>, .hidden) corrispondenti. Puoi anche impostare BUN_DEBUG_QUIET_LOGS=1 per disabilitare tutti i log di debug che non sono esplicitamente abilitati. Per scaricare i log di debug in un file, BUN_DEBUG=<percorso-al-file>.log. I log di debug sono aggressivamente rimossi nelle build release.
• Le modifiche src/js/**.ts sono praticamente istantanee da ricompilare. Le modifiche C++ sono un po' più lente, ma comunque molto più veloci del codice Zig (Zig è un'unità di compilazione, C++ sono molte).

Script di generazione del codice

Diversi script di generazione del codice sono usati durante il processo di build di Bun. Questi vengono eseguiti automaticamente quando vengono apportate modifiche a determinati file.

In particolare, questi sono:

• ./src/codegen/generate-jssink.ts -- Genera build/debug/codegen/JSSink.cpp, build/debug/codegen/JSSink.h che implementano varie classi per interfacciarsi con ReadableStream. Questo è internamente come funzionano FileSink, ArrayBufferSink, stream "type": "direct" e altro codice relativo agli stream.
• ./src/codegen/generate-classes.ts -- Genera build/debug/codegen/ZigGeneratedClasses*, che genera binding Zig e C++ per le classi JavaScriptCore implementate in Zig. Nei file **/*.classes.ts, definiamo le interfacce per varie classi, metodi, prototipi, getter/setter ecc che il generatore di codice legge per generare codice boilerplate che implementa gli oggetti JavaScript in C++ e li collega a Zig
• ./src/codegen/cppbind.ts -- Genera automaticamente binding Zig per funzioni C++ contrassegnate con attributi [[ZIG_EXPORT]].
• ./src/codegen/bundle-modules.ts -- Bundle di moduli built-in come node:fs, bun:ffi in file che possiamo includere nel binario finale. In sviluppo, questi possono essere ricaricati senza ricompilare Zig (devi ancora eseguire bun run build, ma rilegge i file transpilati dal disco successivamente). Nelle build release, questi sono incorporati nel binario.
• ./src/codegen/bundle-functions.ts -- Bundle di funzioni accessibili a livello globale implementate in JavaScript/TypeScript come ReadableStream, WritableStream e alcune altre. Queste sono usate in modo simile ai moduli built-in, ma l'output si allinea più strettamente a ciò che WebKit/Safari fa per le funzioni built-in di Safari in modo da poter copiare e incollare le implementazioni da WebKit come punto di partenza.

Modificare i moduli ESM

Alcuni moduli come node:fs, node:stream, bun:sqlite e ws sono implementati in JavaScript. Questi si trovano nei file src/js/{node,bun,thirdparty} e sono pre-bundled usando Bun.

Build release

Per compilare una build release di Bun, esegui:

bun run build:release

Il binario si troverà in ./build/release/bun e ./build/release/bun-profile.

Scaricare la build release dalle pull request

Per risparmiarti tempo impiegato a compilare una build release localmente, forniamo un modo per eseguire build release dalle pull request. Questo è utile per testare manualmente le modifiche in una build release prima che vengano unite.

Per eseguire una build release da una pull request, puoi usare il pacchetto npm bun-pr:

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

Questo scaricherà la build release dalla pull request e la aggiungerà a $PATH come bun-${pr-number}. Puoi quindi eseguire la build con bun-${pr-number}.

bun-1234566 --version

Questo funziona scaricando la build release dagli artifact di GitHub Actions sulla pull request collegata. Potresti aver bisogno della CLI gh installata per autenticarti con GitHub.

AddressSanitizer

AddressSanitizer aiuta a trovare problemi di memoria ed è abilitato per impostazione predefinita nelle build di debug di Bun su Linux e macOS. Questo include il codice Zig e tutte le dipendenze. Fa sì che il codice Zig impieghi circa il doppio del tempo per compilare, se questo ti impedisce di essere produttivo puoi disabilitarlo impostando -Denable_asan=$<IF:$<BOOL:${ENABLE_ASAN}>,true,false> a -Denable_asan=false nel file cmake/targets/BuildBun.cmake, ma in genere raccomandiamo di raggruppare le modifiche tra le build.

Per compilare una build release con Address Sanitizer, esegui:

bun run build:release:asan

In CI, eseguiamo la nostra suite di test con almeno un target che è compilato con Address Sanitizer.

Compilare WebKit localmente + Modalità Debug di JSC

WebKit non è clonato per impostazione predefinita (per risparmiare tempo e spazio su disco). Per clonare e compilare WebKit localmente, esegui:

# Clona WebKit in ./vendor/WebKit
$ git clone https://github.com/oven-sh/WebKit vendor/WebKit

# Esegui il checkout dell'hash del commit specificato in `set(WEBKIT_VERSION <commit_hash>)` in cmake/tools/SetupWebKit.cmake
$ git -C vendor/WebKit checkout <commit_hash>

# Crea una build debug di JSC. Questo produrrà artifact di build in ./vendor/WebKit/WebKitBuild/Debug
# Opzionalmente, puoi usare `bun run jsc:build` per una build release
bun run jsc:build:debug && rm vendor/WebKit/WebKitBuild/Debug/JavaScriptCore/DerivedSources/inspector/InspectorProtocolObjects.h

# Dopo un'esecuzione iniziale di `make jsc-debug`, puoi ricompilare JSC con:
$ cmake --build vendor/WebKit/WebKitBuild/Debug --target jsc && rm vendor/WebKit/WebKitBuild/Debug/JavaScriptCore/DerivedSources/inspector/InspectorProtocolObjects.h

# Compila bun con la build JSC locale
bun run build:local

Usare bun run build:local compilerà Bun nella directory ./build/debug-local (invece di ./build/debug), dovrai cambiare un paio di posti per usare questa nuova directory:

• La prima riga in src/js/builtins.d.ts
• La riga CompilationDatabase nella configurazione .clangd dovrebbe essere CompilationDatabase: build/debug-local
• In build.zig, l'opzione codegen_path dovrebbe essere build/debug-local/codegen (invece di build/debug/codegen)
• In .vscode/launch.json, molte configurazioni usano ./build/debug/, cambiale come ritieni opportuno

Nota che la cartella WebKit, inclusi gli artifact di build, è di dimensioni superiori a 8GB.

Se stai usando una build debug di JSC e usi VScode, assicurati di eseguire il comando C/C++: Select a Configuration per configurare intellisense per trovare gli header di debug.

Nota che se apporti modifiche al nostro fork di WebKit, dovrai anche modificare SetupWebKit.cmake per puntare all'hash del commit.

Risoluzione dei problemi

File 'span' non trovato su Ubuntu

Il compilatore Clang usa tipicamente la libreria standard C++ libstdc++ per impostazione predefinita. libstdc++ è l'implementazione predefinita della libreria standard C++ fornita da GNU Compiler Collection (GCC). Mentre Clang può collegarsi alla libreria libc++, questo richiede di fornire esplicitamente il flag -stdlib quando si esegue Clang.

Bun si affida a funzionalità C++20 come std::span, che non sono disponibili nelle versioni di GCC inferiori a 11. GCC 10 non ha tutte le funzionalità C++20 implementate. Di conseguenza, l'esecuzione di make setup potrebbe fallire con il seguente errore:

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

Il problema può manifestarsi durante l'esecuzione iniziale di bun setup come Clang incapace di compilare un semplice programma:

The C++ compiler

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

is not able to compile a simple test program.

Per correggere l'errore, dobbiamo aggiornare la versione di GCC a 11. Per fare questo, dovremo verificare se l'ultima versione è disponibile nei repository ufficiali della distribuzione o usare un repository di terze parti che fornisce pacchetti GCC 11. Ecco i passaggi generali:

$ sudo apt update
$ sudo apt install gcc-11 g++-11
# Se il comando sopra fallisce con `Unable to locate package gcc-11` dobbiamo
# aggiungere il repository APT
$ sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
# Ora esegui di nuovo `apt install`
$ sudo apt install gcc-11 g++-11

Ora dobbiamo impostare GCC 11 come compilatore predefinito:

$ 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

Se vedi un errore su macOS durante la compilazione di libarchive, esegui:

$ brew install pkg-config

macOS library not found for -lSystem

Se vedi questo errore durante la compilazione, esegui:

$ xcode-select --install

Impossibile trovare libatomic.a

Bun usa per impostazione predefinita il collegamento statico di libatomic, poiché non tutti i sistemi ce l'hanno. Se stai compilando su una distribuzione che non ha libatomic statico disponibile, puoi eseguire il seguente comando per abilitare il collegamento dinamico:

bun run build -DUSE_STATIC_LIBATOMIC=OFF

La versione compilata di Bun potrebbe non funzionare su altri sistemi se compilata in questo modo.

Usare bun-debug

• Disabilita il logging: BUN_DEBUG_QUIET_LOGS=1 bun-debug ... (per disabilitare tutti i log di debug)
• Abilita il logging per uno scope zig specifico: BUN_DEBUG_EventLoop=1 bun-debug ... (per consentire std.log.scoped(.EventLoop))
• Bun transpila ogni file che esegue, per vedere la sorgente effettivamente eseguita in una build di debug trovala in /tmp/bun-debug-src/...percorso/al/file, ad esempio la versione transpilata di /home/bun/index.ts si troverà in /tmp/bun-debug-src/home/bun/index.ts