Configurer un environnement de développement pour Bun peut prendre 10 à 30 minutes selon votre connexion Internet et la vitesse de votre ordinateur. Vous aurez besoin d'environ 10 Go d'espace disque libre pour le dépôt et les artefacts de construction.

Si vous utilisez Windows, veuillez consulter ce guide

Utiliser Nix (Alternative)

Un Nix flake est fourni comme alternative à l'installation manuelle des dépendances :

nix develop
# ou utiliser explicitement le shell pur
# nix develop .#pure
export CMAKE_SYSTEM_PROCESSOR=$(uname -m)
bun bd

Cela fournit toutes les dépendances dans un environnement isolé et reproductible sans nécessiter sudo.

Installer les dépendances (Manuel)

En utilisant le gestionnaire de packages de votre système, installez les dépendances de 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

Note : Le compilateur Zig est automatiquement installé et mis à jour par les scripts de construction. L'installation manuelle n'est pas requise.

Avant de commencer, vous devrez déjà avoir une version release de Bun installée, car nous utilisons notre bundler pour transpiler et minifier notre code, ainsi que pour les scripts de génération de code.

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

$ npm install -g bun

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

Optionnel : Installer sccache

sccache est utilisé pour mettre en cache les artefacts de compilation, accélérant considérablement les constructions. Il doit être installé avec le support S3 :

# Pour macOS
$ brew install sccache

# Pour Linux. Notez que la version dans votre gestionnaire de packages peut ne pas avoir le support S3.
$ cargo install sccache --features=s3

Cela installera sccache avec le support S3. Nos scripts de construction détecteront et utiliseront automatiquement sccache avec notre cache S3 partagé. Note : Toutes les versions de sccache ne sont pas compilées avec le support S3, c'est pourquoi nous recommandons de l'installer via cargo.

Enregistrer les identifiants AWS pour sccache (Développeurs principaux uniquement)

Les développeurs principaux ont un accès en écriture au cache S3 partagé. Pour activer l'accès en écriture, vous devez vous connecter avec des identifiants AWS. La manière la plus simple de le faire est d'utiliser le CLI aws et d'invoquer aws configure pour fournir vos informations de sécurité AWS.

Les scripts cmake devraient automatiquement détecter vos identifiants AWS depuis l'environnement ou le fichier ~/.aws/credentials.

Se connecter au CLI `aws`

1. Installez le CLI AWS en suivant [le guide officiel](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
2. Connectez-vous à votre console de compte AWS. Un membre de l'équipe devrait vous fournir vos identifiants.
3. Cliquez sur votre nom en haut à droite > Security credentials.
4. Faites défiler jusqu'à "Access keys" et créez une nouvelle clé d'accès.
5. Exécutez `aws configure` dans votre terminal et fournissez l'ID de clé d'accès et la clé d'accès secrète lorsque demandé.

Problèmes courants que vous pouvez rencontrer

- Pour confirmer que le cache est utilisé, vous pouvez utiliser la commande `sccache --show-stats` juste après une construction. Cela affichera des statistiques très utiles, y compris les hits/misses du cache.
- Si vous avez plusieurs profils AWS configurés, assurez-vous que le bon profil est défini dans la variable d'environnement `AWS_PROFILE`.
- `sccache` suit un modèle serveur-client. Si vous rencontrez des problèmes étranges où `sccache` refuse d'utiliser S3, même si vous avez des identifiants AWS configurés, essayez de tuer tous les serveurs `sccache` en cours d'exécution avec `sccache --stop-server` puis de relancer la construction.

Installer LLVM

Bun nécessite LLVM 19 (clang fait partie de LLVM). Cette exigence de version correspond à WebKit (précompilé), car des versions incompatibles provoqueront des échecs d'allocation de mémoire à l'exécution. Dans la plupart des cas, vous pouvez installer LLVM via le gestionnaire de packages de votre système :

$ brew install llvm@19

$ # LLVM dispose d'un script d'installation automatique compatible avec toutes les versions d'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

Si aucune des solutions ci-dessus ne s'applique, vous devrez l'installer manuellement.

Assurez-vous que Clang/LLVM 19 est dans votre chemin :

$ which clang-19

Sinon, exécutez ceci pour l'ajouter manuellement :

# utilisez fish_add_path si vous utilisez fish
# utilisez path+="$(brew --prefix llvm@19)/bin" si vous utilisez zsh
$ export PATH="$(brew --prefix llvm@19)/bin:$PATH"

# utilisez fish_add_path si vous utilisez fish
$ export PATH="$PATH:/usr/lib/llvm19/bin"

Construire Bun

Après avoir cloné le dépôt, exécutez la commande suivante pour construire. Cela peut prendre un certain temps car cela clonera les sous-modules et construira les dépendances.

bun run build

Le binaire sera situé à ./build/debug/bun-debug. Il est recommandé de l'ajouter à votre $PATH. Pour vérifier que la construction a fonctionné, imprimons le numéro de version sur la version de développement de Bun.

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

VSCode

VSCode est l'IDE recommandé pour travailler sur Bun, car il a été configuré. Une fois ouvert, vous pouvez exécuter Extensions: Show Recommended Extensions pour installer les extensions recommandées pour Zig et C++. ZLS est automatiquement configuré.

Si vous utilisez un éditeur différent, assurez-vous de dire à ZLS d'utiliser le compilateur Zig automatiquement installé, qui se trouve à ./vendor/zig/zig.exe. Le nom de fichier est zig.exe pour que cela fonctionne comme prévu sur Windows, mais cela fonctionne toujours sur macOS/Linux (cela a juste une extension de fichier surprenante).

Nous recommandons d'ajouter ./build/debug à votre $PATH pour pouvoir exécuter bun-debug dans votre terminal :

bun-debug

Exécuter des versions de débogage

Le script package.json bd compile et exécute une version de débogage de Bun, n'affichant la sortie du processus de construction que si elle échoue.

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

Bun prend généralement environ 2,5 minutes pour compiler une version de débogage lorsqu'il y a des modifications Zig. Si votre flux de travail de développement est "changer une ligne, enregistrer, reconstruire", vous passerez trop de temps à attendre la fin de la construction. À la place :

• Regroupez vos modifications
• Assurez-vous que zls fonctionne avec une surveillance incrémentale pour les erreurs LSP (si vous utilisez VSCode et installez Zig et exécutez bun run build une fois pour télécharger Zig, cela devrait fonctionner)
• Préférez utiliser le débogueur ("CodeLLDB" dans VSCode) pour parcourir le code.
• Utilisez les journaux de débogage. BUN_DEBUG_<scope>=1 activera la journalisation de débogage pour les journaux Output.scoped(.<scope>, .hidden) correspondants. Vous pouvez également définir BUN_DEBUG_QUIET_LOGS=1 pour désactiver toute la journalisation de débogage qui n'est pas explicitement activée. Pour vider les journaux de débogage dans un fichier, BUN_DEBUG=<chemin-vers-fichier>.log. Les journaux de débogage sont agressivement supprimés dans les versions release.
• Les modifications src/js/**.ts sont pratiquement instantanées à reconstruire. Les modifications C++ sont un peu plus lentes, mais toujours beaucoup plus rapides que le code Zig (Zig est une unité de compilation, C++ en est plusieurs).

Scripts de génération de code

Plusieurs scripts de génération de code sont utilisés pendant le processus de construction de Bun. Ceux-ci sont exécutés automatiquement lorsque des modifications sont apportées à certains fichiers.

En particulier, ce sont :

• ./src/codegen/generate-jssink.ts -- Génère build/debug/codegen/JSSink.cpp, build/debug/codegen/JSSink.h qui implémentent diverses classes pour l'interfaçage avec ReadableStream. C'est ainsi que fonctionnent internement FileSink, ArrayBufferSink, les streams "type": "direct" et autre code lié aux streams.
• ./src/codegen/generate-classes.ts -- Génère build/debug/codegen/ZigGeneratedClasses*, qui génère les liaisons Zig et C++ pour les classes JavaScriptCore implémentées en Zig. Dans les fichiers **/*.classes.ts, nous définissons les interfaces pour diverses classes, méthodes, prototypes, getters/setters, etc. que le générateur de code lit pour générer le code boilerplate implémentant les objets JavaScript en C++ et les reliant à Zig
• ./src/codegen/cppbind.ts -- Génère automatiquement les liaisons Zig pour les fonctions C++ marquées avec des attributs [[ZIG_EXPORT]].
• ./src/codegen/bundle-modules.ts -- Bundle des modules intégrés comme node:fs, bun:ffi dans des fichiers que nous pouvons inclure dans le binaire final. En développement, ceux-ci peuvent être rechargés sans reconstruire Zig (vous devez toujours exécuter bun run build, mais il relit les fichiers transpilés depuis le disque ensuite). Dans les versions release, ceux-ci sont intégrés dans le binaire.
• ./src/codegen/bundle-functions.ts -- Bundle des fonctions accessibles globalement implémentées en JavaScript/TypeScript comme ReadableStream, WritableStream, et quelques autres. Celles-ci sont utilisées de manière similaire aux modules intégrés, mais la sortie correspond plus étroitement à ce que WebKit/Safari fait pour les fonctions intégrées de Safari afin que nous puissions copier-coller les implémentations de WebKit comme point de départ.

Modifier les modules ESM

Certains modules comme node:fs, node:stream, bun:sqlite, et ws sont implémentés en JavaScript. Ceux-ci se trouvent dans les fichiers src/js/{node,bun,thirdparty} et sont pré-bundlés en utilisant Bun.

Version release

Pour compiler une version release de Bun, exécutez :

bun run build:release

Le binaire sera situé à ./build/release/bun et ./build/release/bun-profile.

Télécharger une version release depuis des pull requests

Pour vous faire gagner du temps passé à construire une version release localement, nous fournissons un moyen d'exécuter des versions release depuis des pull requests. C'est utile pour tester manuellement les modifications dans une version release avant qu'elles ne soient fusionnées.

Pour exécuter une version release depuis une pull request, vous pouvez utiliser le package 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> # Linux x64 uniquement

Cela téléchargera la version release depuis la pull request et l'ajoutera à $PATH sous le nom bun-${pr-number}. Vous pouvez ensuite exécuter la construction avec bun-${pr-number}.

bun-1234566 --version

Cela fonctionne en téléchargeant la version release depuis les artefacts GitHub Actions sur la pull request liée. Vous pourriez avoir besoin du CLI gh installé pour vous authentifier auprès de GitHub.

AddressSanitizer

AddressSanitizer aide à trouver les problèmes de mémoire, et est activé par défaut dans les versions de débogage de Bun sur Linux et macOS. Cela inclut le code Zig et toutes les dépendances. Cela rend le code Zig environ 2 fois plus long à construire, si cela vous empêche d'être productif, vous pouvez le désactiver en définissant -Denable_asan=$<IF:$<BOOL:${ENABLE_ASAN}>,true,false> à -Denable_asan=false dans le fichier cmake/targets/BuildBun.cmake, mais généralement nous recommandons de regrouper vos modifications entre les constructions.

Pour construire une version release avec Address Sanitizer, exécutez :

bun run build:release:asan

En CI, nous exécutons notre suite de tests avec au moins une cible qui est construite avec Address Sanitizer.

Construire WebKit localement + Mode débogage de JSC

WebKit n'est pas cloné par défaut (pour gagner du temps et de l'espace disque). Pour cloner et construire WebKit localement, exécutez :

# Cloner WebKit dans ./vendor/WebKit
$ git clone https://github.com/oven-sh/WebKit vendor/WebKit

# Extraire le hash de commit spécifié dans `set(WEBKIT_VERSION <commit_hash>)` dans cmake/tools/SetupWebKit.cmake
$ git -C vendor/WebKit checkout <commit_hash>

# Faire une construction de débogage de JSC. Cela produira des artefacts de construction dans ./vendor/WebKit/WebKitBuild/Debug
# En option, vous pouvez utiliser `bun run jsc:build` pour une version release
bun run jsc:build:debug && rm vendor/WebKit/WebKitBuild/Debug/JavaScriptCore/DerivedSources/inspector/InspectorProtocolObjects.h

# Après une première exécution de `make jsc-debug`, vous pouvez reconstruire JSC avec :
$ cmake --build vendor/WebKit/WebKitBuild/Debug --target jsc && rm vendor/WebKit/WebKitBuild/Debug/JavaScriptCore/DerivedSources/inspector/InspectorProtocolObjects.h

# Construire bun avec la construction JSC locale
bun run build:local

L'utilisation de bun run build:local construira Bun dans le répertoire ./build/debug-local (au lieu de ./build/debug), vous devrez modifier quelques endroits pour utiliser ce nouveau répertoire :

• La première ligne dans src/js/builtins.d.ts
• La ligne CompilationDatabase dans la config .clangd devrait être CompilationDatabase: build/debug-local
• Dans build.zig, l'option codegen_path devrait être build/debug-local/codegen (au lieu de build/debug/codegen)
• Dans .vscode/launch.json, de nombreuses configurations utilisent ./build/debug/, modifiez-les selon vos besoins

Notez que le dossier WebKit, y compris les artefacts de construction, fait plus de 8 Go.

Si vous utilisez une construction de débogage JSC et utilisez VScode, assurez-vous d'exécuter la commande C/C++: Select a Configuration pour configurer intellisense afin de trouver les en-têtes de débogage.

Notez que si vous apportez des modifications à notre fork WebKit, vous devrez également modifier SetupWebKit.cmake pour pointer vers le hash de commit.

Dépannage

Fichier 'span' introuvable sur Ubuntu

Le compilateur Clang utilise généralement la bibliothèque standard C++ libstdc++ par défaut. libstdc++ est l'implémentation de bibliothèque standard C++ par défaut fournie par la GNU Compiler Collection (GCC). Bien que Clang puisse se lier à la bibliothèque libc++, cela nécessite de fournir explicitement le drapeau -stdlib lors de l'exécution de Clang.

Bun s'appuie sur des fonctionnalités C++20 comme std::span, qui ne sont pas disponibles dans les versions GCC inférieures à 11. GCC 10 n'a pas toutes les fonctionnalités C++20 implémentées. Par conséquent, l'exécution de make setup peut échouer avec l'erreur suivante :

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

Le problème peut se manifester lors de l'exécution initiale de bun setup car Clang est incapable de compiler un programme simple :

The C++ compiler

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

is not able to compile a simple test program.

Pour corriger l'erreur, nous devons mettre à jour la version GCC vers 11. Pour ce faire, nous devrons vérifier si la dernière version est disponible dans les dépôts officiels de la distribution ou utiliser un dépôt tiers qui fournit des packages GCC 11. Voici les étapes générales :

$ sudo apt update
$ sudo apt install gcc-11 g++-11
# Si la commande ci-dessus échoue avec `Unable to locate package gcc-11` nous devons
# ajouter le dépôt APT
$ sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
# Maintenant exécutez `apt install` à nouveau
$ sudo apt install gcc-11 g++-11

Maintenant, nous devons définir GCC 11 comme compilateur par défaut :

$ 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

Si vous voyez une erreur sur macOS lors de la compilation de libarchive, exécutez :

$ brew install pkg-config

macOS library not found for -lSystem

Si vous voyez cette erreur lors de la compilation, exécutez :

$ xcode-select --install

Impossible de trouver libatomic.a

Bun utilise par défaut la liaison statique de libatomic, car tous les systèmes ne l'ont pas. Si vous construisez sur une distribution qui n'a pas de libatomic statique disponible, vous pouvez exécuter la commande suivante pour activer la liaison dynamique :

bun run build -DUSE_STATIC_LIBATOMIC=OFF

La version construite de Bun peut ne pas fonctionner sur d'autres systèmes si elle est compilée de cette façon.

Utiliser bun-debug

• Désactiver la journalisation : BUN_DEBUG_QUIET_LOGS=1 bun-debug ... (pour désactiver toute la journalisation de débogage)
• Activer la journalisation pour un scope zig spécifique : BUN_DEBUG_EventLoop=1 bun-debug ... (pour autoriser std.log.scoped(.EventLoop))
• Bun transpile chaque fichier qu'il exécute, pour voir la source réellement exécutée dans une construction de débogage, trouvez-la dans /tmp/bun-debug-src/...chemin/vers/fichier, par exemple la version transpilée de /home/bun/index.ts serait dans /tmp/bun-debug-src/home/bun/index.ts