Configuring a development environment for Bun can take 10-30 minutes depending on your internet connection and computer speed. You will need ~10GB of free disk space for the repository and build artifacts.
If you are using Windows, you must use a WSL environment as Bun does not yet compile on Windows natively.
Install LLVM
Bun requires LLVM 15 and Clang 15 (clang
is part of LLVM). This version requirement is to match WebKit (precompiled), as mismatching versions will cause memory allocation failures at runtime. In most cases, you can install LLVM through your system package manager:
brew install llvm@15
# On Ubuntu 22.04 and newer, LLVM 15 is available in the default repositories
sudo apt install llvm-15 lld-15
# On older versions,
wget https://apt.llvm.org/llvm.sh -O - | sudo bash -s -- 15 all
sudo pacman -S llvm clang lld
If none of the above solutions apply, you will have to install it manually.
Make sure LLVM 15 is in your path:
which clang-15
If not, run this to manually link it:
# use fish_add_path if you're using fish
export PATH="$PATH:$(brew --prefix llvm@15)/bin"
export LDFLAGS="$LDFLAGS -L$(brew --prefix llvm@15)/lib"
export CPPFLAGS="$CPPFLAGS -I$(brew --prefix llvm@15)/include"
Install Dependencies
Using your system's package manager, install the rest of Bun's dependencies:
brew install automake ccache cmake coreutils esbuild gnu-sed go libiconv libtool ninja pkg-config rust
sudo apt install cargo ccache cmake esbuild git golang libtool ninja-build pkg-config rustc
pacman -S base-devel ccache cmake esbuild git go libiconv libtool make ninja pkg-config python rust sed unzip
In addition to this, you will need either bun
or npm
installed to install the package.json dependencies.
Install Zig
Zig can be installed either with our npm package @oven/zig
, or by using zigup.
bun install -g @oven/zig
zigup master
Building
After cloning the repository, prepare bun to be built:
make setup
Then to build Bun:
make dev
The binary will be located at packages/debug-bun-{platform}-{arch}/bun-debug
. It is recommended to add this to your $PATH
. To verify the build worked, lets print the version number on the development build of Bun.
packages/debug-bun-*/bun-debug --version
bun 0.x.y__dev
VSCode
VSCode is the recommended IDE for working on Bun, as it has been configured. Once opening, you can run Extensions: Show Recommended Extensions
to install the recommended extensions for Zig and C++. ZLS is automatically configured.
JavaScript builtins
When you change anything in src/bun.js/builtins/js/*
or switch branches, run this:
make regenerate-bindings
That inlines the JavaScript code into C++ headers using the same builtins generator script that Safari uses.
Make sure you have ccache
installed, otherwise regeneration will take much longer than it should.
Code generation scripts
Bun leverages a lot of code generation scripts.
The ./src/bun.js/bindings/headers.h file has bindings to & from Zig <> C++ code. This file is generated by running the following:
make headers
This ensures that the types for Zig and the types for C++ match up correctly, by using comptime reflection over functions exported/imported.
TypeScript files that end with *.classes.ts
are another code generation script. They generate C++ boilerplate for classes implemented in Zig. The generated code lives in:
- src/bun.js/bindings/ZigGeneratedClasses.cpp
- src/bun.js/bindings/ZigGeneratedClasses.h
- src/bun.js/bindings/generated_classes.zig To generate the code, run:
make codegen
Lastly, we also have a code generation script for our native stream implementations. To run that, run:
make generate-sink
You probably won't need to run that one much.
Modifying ESM core modules
Certain modules like node:fs
, node:path
, node:stream
, and bun:sqlite
are implemented in JavaScript. These live in src/bun.js/*.exports.js
files.
While Bun is in beta, you can modify them at runtime in release builds via the environment variable BUN_OVERRIDE_MODULE_PATH
. When set, Bun will look in the override directory for <name>.exports.js
before checking the files from src/bun.js
(which are now baked in to the binary). This lets you test changes to the ESM modules without needing to re-compile Bun.
Release build
To build a release build of Bun, run:
make release-bindings -j12
make release
The binary will be located at packages/bun-{platform}-{arch}/bun
.
Valgrind
On Linux, valgrind can help find memory issues.
Keep in mind:
- JavaScriptCore doesn't support valgrind. It will report spurious errors.
- Valgrind is slow
- Mimalloc will sometimes cause spurious errors when debug build is enabled
You'll need a very recent version of Valgrind due to DWARF 5 debug symbols. You may need to manually compile Valgrind instead of using it from your Linux package manager.
--fair-sched=try
is necessary if running multithreaded code in Bun (such as the bundler). Otherwise it will hang.
valgrind --fair-sched=try --track-origins=yes bun-debug <args>
Troubleshooting
libarchive
If you see an error when compiling libarchive
, run this:
brew install pkg-config
missing files on zig build obj
If you see an error about missing files on zig build obj
, make sure you built the headers.
make headers
cmakeconfig.h not found
If you see an error about cmakeconfig.h
not being found, this is because the precompiled WebKit did not install properly.
bun install
Check to see the command installed webkit, and you can manully look for node_modules/bun-webkit-{platform}-{arch}
:
# this should reveal two directories. if not, something went wrong
echo node_modules/bun-webkit*
macOS library not found for -lSystem
If you see this error when compiling, run:
xcode-select --install
Arch Linux / Cannot find libatomic.a
Bun requires libatomic
to be statically linked. On Arch Linux, it is only given as a shared library, but as a workaround you can symlink it to get the build working locally.
sudo ln -s /lib/libatomic.so /lib/libatomic.a
The built version of bun may not work on other systems if compiled this way.