diff options
Diffstat (limited to 'docs/project')
| -rw-r--r-- | docs/project/development.md (renamed from docs/project/developing.md) | 262 |
1 files changed, 152 insertions, 110 deletions
diff --git a/docs/project/developing.md b/docs/project/development.md index 967d5a9d5..3a0637b26 100644 --- a/docs/project/developing.md +++ b/docs/project/development.md @@ -1,170 +1,121 @@ -Configuring a development environment for Bun usually takes 30-90 minutes depending on your operating system. +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. -## Linux/Windows +If you are using Windows, you must use a WSL environment as Bun does not yet compile on Windows natively. -The best way to build Bun on Linux and Windows is with the official [Dev Container](https://containers.dev). It ships with Zig, JavaScriptCore, Zig Language Server, and more pre-installed on an instance of Ubuntu. +## Install LLVM -{% image src="https://user-images.githubusercontent.com/709451/147319227-6446589c-a4d9-480d-bd5b-43037a9e56fd.png" /%} +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: -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 -``` +{% codetabs %} -To just build the dev container image, run: - -```bash -$ make devcontainer-build +```bash#macOS (Homebrew) +$ brew install llvm@15 ``` -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 +```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 ``` -### 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 +```bash#Arch +$ sudo pacman -S llvm clang lld ``` -### 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 -``` +{% /codetabs %} -## MacOS +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). -Install LLVM 15 and `homebrew` dependencies: +Make sure LLVM 15 is in your path: -```bash -$ brew install llvm@15 coreutils libtool cmake libiconv automake ninja gnu-sed pkg-config esbuild go rust ``` - -Bun (& the version of Zig) need LLVM 15 and Clang 15 (`clang` is part of LLVM). Make sure LLVM 15 is in your `$PATH`: - -```bash $ which clang-15 ``` If not, run this to manually link it: -```bash#bash +{% 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" ``` -### Install Zig - -{% callout %} -**⚠️ Warning** — You must use the same version of Zig used by Bun in [oven-sh/zig](https://github.com/oven-sh/zig). Installing with `brew` or via Zig's download page will not work! -{% /callout %} - -Use [`zigup`](https://github.com/marler8997/zigup) to install the version of Zig (`ZIG_VERSION`) specified in the official [`Dockerfile`](https://github.com/oven-sh/bun/blob/main/Dockerfile). For example: +{% /codetabs %} -```bash -$ zigup 0.11.0-dev.1783+436e99d13 -``` +## Install Dependencies -### Building +Using your system's package manager, install the rest of Bun's dependencies: -To install and build dependencies: +{% codetabs %} -```bash -# without --depth=1 this will take 20+ minutes on 1gbps internet -# mostly due to WebKit -$ git submodule update --init --recursive --progress --depth=1 --checkout -$ bun install -$ make vendor identifier-cache +```bash#macOS (Homebrew) +$ brew install automake ccache cmake coreutils esbuild gnu-sed go libiconv libtool ninja pkg-config rust ``` -To compile the C++ bindings: +```bash#Ubuntu/Debian +$ sudo apt install cargo ccache cmake esbuild git golang libtool ninja-build pkg-config rustc +``` -```bash -# without -j this will take 30+ minutes -$ make bindings -j12 +```bash#Arch +$ pacman -S base-devel ccache cmake esbuild git go libiconv libtool make ninja pkg-config python rust sed unzip ``` -<!-- If you're building on a macOS device, you'll need to have a valid Developer Certificate, or else the code signing step will fail. To check if you have one, open the `Keychain Access` app, go to the `login` profile and search for `Apple Development`. You should have at least one certificate with a name like `Apple Development: user@example.com (WDYABC123)`. If you don't have one, follow [this guide](https://ioscodesigning.com/generating-code-signing-files/#generate-a-code-signing-certificate-using-xcode) to get one. --> +{% /codetabs %} -<!-- You can still work with the generated binary locally at `packages/debug-bun-*/bun-debug` even if the code signing fails. --> +In addition to this, you will need either `bun` or `npm` installed to install the package.json dependencies. -### Testing +## Install Zig -To verify the build worked, lets print the version number on the development build of Bun. +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). -```bash -$ packages/debug-bun-darwin-*/bun-debug --version -bun 0.x.y__dev +``` +$ bun install -g @oven/zig +$ zigup master ``` -You will want to add `packages/debug-bun-darwin-arm64/` or `packages/debug-bun-darwin-x64/` (depending on your architecture) to `$PATH` so you can run `bun-debug` from anywhere. +## Building -### Troubleshooting +After cloning the repository, prepare bun to be built: -If you see an error when compiling `libarchive`, run this: +```bash +$ make setup +``` + +Then to build Bun: ```bash -$ brew install pkg-config +$ make dev ``` -If you see an error about missing files on `zig build obj`, make sure you built the headers. +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 -$ make headers +$ 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/*`, run this: +When you change anything in `src/bun.js/builtins/js/*` or switch branches, run this: ```bash -$ make clean-bindings generate-builtins && make bindings -j12 +$ 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. +{% endcallout %} + ## Code generation scripts Bun leverages a lot of code generation scripts. @@ -203,9 +154,16 @@ Certain modules like `node:fs`, `node:path`, `node:stream`, and `bun:sqlite` are 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. -## Troubleshooting +## Release build + +To build a release build of Bun, run: + +```bash +make release-bindings -j12 +make release +``` -If you encounter `error: the build command failed with exit code 9` during the build process, this means you ran out of memory or swap. Bun currently needs about 8 GB of RAM to compile. +The binary will be located at `packages/bun-{platform}-{arch}/bun`. ## Valgrind @@ -224,3 +182,87 @@ You'll need a very recent version of Valgrind due to DWARF 5 debug symbols. You ```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 + +If you see an error when compiling `libarchive`, run this: + +```bash +$ brew install pkg-config +``` + +If you see an error about missing files on `zig build obj`, make sure you built the headers. + +```bash +$ make headers +``` |