1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
|
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:
{% codetabs %}
```bash#macOS (Homebrew)
$ brew install llvm@15
```
```bash#Ubuntu/Debian
# 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
```
```bash#Arch
$ sudo pacman -S llvm clang lld
```
{% /codetabs %}
If none of the above solutions apply, you will have to install it [manually](https://github.com/llvm/llvm-project/releases/tag/llvmorg-15.0.7).
Make sure LLVM 15 is in your path:
```
$ which clang-15
```
If not, run this to manually link it:
{% codetabs %}
```bash#macOS (Homebrew)
# 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"
```
{% /codetabs %}
## Install Dependencies
Using your system's package manager, install the rest of Bun's dependencies:
{% codetabs %}
```bash#macOS (Homebrew)
$ brew install automake ccache cmake coreutils esbuild gnu-sed go libiconv libtool ninja pkg-config rust
```
```bash#Ubuntu/Debian
$ sudo apt install cargo ccache cmake esbuild git golang libtool ninja-build pkg-config rustc
```
```bash#Arch
$ pacman -S base-devel ccache cmake esbuild git go libiconv libtool make ninja pkg-config python rust sed unzip
```
{% /codetabs %}
In addition to this, you will need either `bun` or `npm` installed to install the package.json dependencies.
## Install Zig
Zig can installed either with our npm package [`@oven/zig`](https://www.npmjs.com/package/@oven/zig), or by using [zigup](https://github.com/marler8997/zigup).
```
$ bun install -g @oven/zig
$ zigup master
```
## Building
After cloning the repository, prepare bun to be built:
```bash
$ make setup
```
Then to build Bun:
```bash
$ 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.
```bash
$ 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:
```bash
$ make regenerate-bindings
```
That inlines the JavaScript code into C++ headers using the same builtins generator script that Safari uses.
{% callout %}
Make sure you have `ccache` installed, otherwise regeneration will take much longer than it should.
{% /callout %}
## Code generation scripts
Bun leverages a lot of code generation scripts.
The [./src/bun.js/bindings/headers.h](https://github.com/oven-sh/bun/blob/main/src/bun.js/bindings/headers.h) file has bindings to & from Zig <> C++ code. This file is generated by running the following:
```bash
$ 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](https://github.com/oven-sh/bun/tree/main/src/bun.js/bindings/ZigGeneratedClasses.cpp)
- [src/bun.js/bindings/ZigGeneratedClasses.h](https://github.com/oven-sh/bun/tree/main/src/bun.js/bindings/ZigGeneratedClasses.h)
- [src/bun.js/bindings/generated_classes.zig](https://github.com/oven-sh/bun/tree/main/src/bun.js/bindings/generated_classes.zig)
To generate the code, run:
```bash
$ make codegen
```
Lastly, we also have a [code generation script](src/bun.js/scripts/generate-jssink.js) for our native stream implementations.
To run that, run:
```bash
$ 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:
```bash
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.
```bash
valgrind --fair-sched=try --track-origins=yes bun-debug <args>
```
## Docker Devcontainer
Bun has a [Dev Container](https://containers.dev), which can be used to quickly get a development environment. We do not recommend using this, as the setup instructions above are much more complete.
To develop on Linux/Windows, [Docker](https://www.docker.com) is required. If using WSL on Windows, it is recommended to use [Docker Desktop](https://docs.microsoft.com/en-us/windows/wsl/tutorials/wsl-containers) for its WSL2 integration.
### VSCode
If you're using VSCode, you'll need to have the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension installed.
To get started, open VS Code in the `bun` repository. The first time you try to open the dev container, the extension will automatically build it for you, based on [`Dockerfile.devcontainer`](https://github.com/oven-sh/bun/blob/main/Dockerfile.devcontainer).
To open the dev container, open the command palette (`Ctrl` + `Shift` + `P`) and run: `Dev Containers: Reopen in Container`. To later rebuild it (only needed when the devcontainer itself changes, not the Bun code), run: `Dev Containers: Rebuild and Reopen in Container`.
### Other editors and CLI
If you're using another editor or want to manually control the dev container from the command line or a script, you'll need to install the [Dev Container CLI](https://www.npmjs.com/package/@devcontainers/cli): `npm install -g @devcontainers/cli`.
To create and start the dev container, in the `bun` repository, locally run:
```bash
# `make devcontainer-<command>` should be equivalent
# to `devcontainer <command>`, it just sets the architecture
# so if you're on ARM64, it'll do the right thing
$ make devcontainer-up
```
To just build the dev container image, run:
```bash
$ make devcontainer-build
```
To start a shell inside the container, run:
```bash
$ make devcontainer-sh
# if it attaches to the container non-interactively,
# instead use the regular docker exec command:
$ docker exec -it <container-name/id> zsh
```
### Cloning
You will then need to clone the GitHub repository inside that container.
```bash
# First time setup
$ gh auth login # if it fails to open a browser, use Personal Access Token instead
$ gh repo clone oven-sh/bun . -- --depth=1 --progress -j8
```
### Building
```bash
# Compile Bun dependencies (zig is already compiled)
$ make devcontainer
# It initializes and updates all submodules except WebKit, because WebKit
# takes a while and it's already compiled for you. To do it manually, use:
$ git -c submodule."src/bun.js/WebKit".update=none submodule update --init --recursive --depth=1 --progress
# Build Bun for development
$ make dev
# Run Bun
$ bun-debug
```
## Troubleshooting
### libarchive
If you see an error when compiling `libarchive`, run this:
```bash
$ 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.
```bash
$ 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.
```bash
$ bun install
```
Check to see the command installed webkit, and you can manully look for `node_modules/bun-webkit-{platform}-{arch}`:
```bash
# this should reveal two directories. if not, something went wrong
$ echo node_modules/bun-webkit*
```
|