Configurar um ambiente de desenvolvimento para o Bun pode levar de 10 a 30 minutos, dependendo da sua conexão de internet e velocidade do computador. Você precisará de ~10GB de espaço livre em disco para o repositório e artefatos de compilação.

Se você estiver usando Windows, consulte este guia

Usando Nix (Alternativa)

Um Nix flake é fornecido como uma alternativa à instalação manual de dependências:

nix develop
# ou explicitamente use o shell puro
# nix develop .#pure
export CMAKE_SYSTEM_PROCESSOR=$(uname -m)
bun bd

Isso fornece todas as dependências em um ambiente isolado e reprodutível sem exigir sudo.

Instalar Dependências (Manual)

Usando o gerenciador de pacotes do seu sistema, instale as dependências do 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: O compilador Zig é automaticamente instalado e atualizado pelos scripts de compilação. Instalação manual não é necessária.

Antes de começar, você já precisará ter uma versão de release do Bun instalada, pois usamos nosso bundler para transpilar e minificar nosso código, bem como para scripts de geração de código.

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

$ npm install -g bun

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

Opcional: Instalar sccache

sccache é usado para cachear artefatos de compilação, acelerando significativamente as compilações. Deve ser instalado com suporte a S3:

# Para macOS
$ brew install sccache

# Para Linux. Note que a versão no seu gerenciador de pacotes pode não ter suporte a S3.
$ cargo install sccache --features=s3

Isso instalará o sccache com suporte a S3. Nossos scripts de compilação detectarão e usarão automaticamente o sccache com nosso cache S3 compartilhado. Nota: Nem todas as versões do sccache são compiladas com suporte a S3, por isso recomendamos instalá-lo via cargo.

Registrando Credenciais AWS para sccache (Apenas Desenvolvedores Principais)

Desenvolvedores principais têm acesso de gravação ao cache S3 compartilhado. Para habilitar o acesso de gravação, você deve fazer login com credenciais AWS. A maneira mais fácil de fazer isso é usar a aws CLI e invocar aws configure para fornecer suas informações de segurança AWS.

Os scripts cmake devem detectar automaticamente suas credenciais AWS do ambiente ou do arquivo ~/.aws/credentials.

Fazendo login na `aws` CLI

1. Instale a AWS CLI seguindo [o guia oficial](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
2. Faça login no console da sua conta AWS. Um membro da equipe deve fornecer suas credenciais.
3. Clique no seu nome no canto superior direito > Credenciais de segurança.
4. Role até "Chaves de acesso" e crie uma nova chave de acesso.
5. Execute `aws configure` no seu terminal e forneça o ID da chave de acesso e a chave de acesso secreta quando solicitado.

Problemas Comuns que Você Pode Encontrar

- Para confirmar que o cache está sendo usado, você pode usar o comando `sccache --show-stats` logo após uma compilação. Isso exporá estatísticas muito úteis, incluindo acertos/erros de cache.
- Se você tiver múltiplos perfis AWS configurados, certifique-se de que o perfil correto está definido na variável de ambiente `AWS_PROFILE`.
- `sccache` segue um modelo cliente-servidor. Se encontrar problemas estranhos onde o `sccache` se recusa a usar S3, mesmo tendo credenciais AWS configuradas, tente encerrar quaisquer servidores `sccache` em execução com `sccache --stop-server` e depois execute a compilação novamente.

Instalar LLVM

O Bun requer LLVM 19 (clang faz parte do LLVM). Este requisito de versão é para corresponder ao WebKit (pré-compilado), pois versões incompatíveis causarão falhas de alocação de memória em tempo de execução. Na maioria dos casos, você pode instalar o LLVM através do gerenciador de pacotes do sistema:

$ brew install llvm@19

$ # LLVM tem um script de instalação automática compatível com todas as versões do 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 nenhuma das soluções acima se aplicar, você terá que instalá-lo manualmente.

Certifique-se de que Clang/LLVM 19 está no seu caminho:

$ which clang-19

Se não, execute isto para adicioná-lo manualmente:

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

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

Compilando o Bun

Após clonar o repositório, execute o seguinte comando para compilar. Isso pode demorar um pouco, pois clonará submódulos e compilará dependências.

bun run build

O binário estará localizado em ./build/debug/bun-debug. É recomendado adicionar isso ao seu $PATH. Para verificar se a compilação funcionou, vamos imprimir o número da versão na versão de desenvolvimento do Bun.

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

VSCode

O VSCode é a IDE recomendada para trabalhar no Bun, pois foi configurada. Após abrir, você pode executar Extensions: Show Recommended Extensions para instalar as extensões recomendadas para Zig e C++. O ZLS é configurado automaticamente.

Se você usar um editor diferente, certifique-se de dizer ao ZLS para usar o compilador Zig instalado automaticamente, que está localizado em ./vendor/zig/zig.exe. O nome do arquivo é zig.exe para que funcione conforme o esperado no Windows, mas ainda funciona no macOS/Linux (apenas tem uma extensão de arquivo surpreendente).

Recomendamos adicionar ./build/debug ao seu $PATH para que você possa executar bun-debug no seu terminal:

bun-debug

Executando compilações de depuração

O script bd do package.json compila e executa uma compilação de depuração do Bun, imprimindo apenas a saída do processo de compilação se falhar.

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

O Bun geralmente leva cerca de 2,5 minutos para compilar uma compilação de depuração quando há alterações no Zig. Se seu fluxo de trabalho de desenvolvimento for "alterar uma linha, salvar, recompilar", você passará muito tempo esperando a compilação terminar. Em vez disso:

• Agrupe suas alterações
• Certifique-se de que o zls está em execução com watching incremental para erros LSP (se você usar VSCode e instalar Zig e executar bun run build uma vez para baixar o Zig, isso deve funcionar)
• Prefira usar o depurador ("CodeLLDB" no VSCode) para percorrer o código.
• Use logs de depuração. BUN_DEBUG_<escopo>=1 habilitará o log de depuração para os logs Output.scoped(.<escopo>, .hidden) correspondentes. Você também pode definir BUN_DEBUG_QUIET_LOGS=1 para desabilitar todos os logs de depuração que não estão explicitamente habilitados. Para despejar logs de depuração em um arquivo, BUN_DEBUG=<caminho-para-arquivo>.log. Logs de depuração são agressivamente removidos em compilações de release.
• Alterações em src/js/**.ts são basicamente instantâneas para recompilar. Alterações em C++ são um pouco mais lentas, mas ainda muito mais rápidas que o código Zig (Zig é uma unidade de compilação, C++ são muitas).

Scripts de geração de código

Vários scripts de geração de código são usados durante o processo de compilação do Bun. Estes são executados automaticamente quando alterações são feitas em certos arquivos.

Em particular, estes são:

• ./src/codegen/generate-jssink.ts -- Gera build/debug/codegen/JSSink.cpp, build/debug/codegen/JSSink.h que implementam várias classes para interfacing com ReadableStream. É assim que internamente FileSink, ArrayBufferSink, streams "type": "direct" e outro código relacionado a streams funciona.
• ./src/codegen/generate-classes.ts -- Gera build/debug/codegen/ZigGeneratedClasses*, que gera bindings Zig e C++ para classes JavaScriptCore implementadas em Zig. Em arquivos **/*.classes.ts, definimos as interfaces para várias classes, métodos, protótipos, getters/setters etc que o gerador de código lê para gerar código boilerplate implementando os objetos JavaScript em C++ e conectando-os ao Zig
• ./src/codegen/cppbind.ts -- Gera bindings Zig automáticas para funções C++ marcadas com atributos [[ZIG_EXPORT]].
• ./src/codegen/bundle-modules.ts -- Empacota módulos built-in como node:fs, bun:ffi em arquivos que podemos incluir no binário final. Em desenvolvimento, estes podem ser recarregados sem recompilar o Zig (você ainda precisa executar bun run build, mas ele relê os arquivos transpilados do disco depois). Em compilações de release, estes são incorporados ao binário.
• ./src/codegen/bundle-functions.ts -- Empacota funções acessíveis globalmente implementadas em JavaScript/TypeScript como ReadableStream, WritableStream, e algumas outras. Estas são usadas de forma similar aos módulos built-in, mas a saída se alinha mais de perto com o que o WebKit/Safari faz para as funções built-in do Safari para que possamos copiar e colar as implementações do WebKit como ponto de partida.

Modificando módulos ESM

Certos módulos como node:fs, node:stream, bun:sqlite, e ws são implementados em JavaScript. Estes vivem em arquivos src/js/{node,bun,thirdparty} e são pré-empacotados usando o Bun.

Compilação de release

Para compilar uma compilação de release do Bun, execute:

bun run build:release

O binário estará localizado em ./build/release/bun e ./build/release/bun-profile.

Baixar compilação de release de pull requests

Para economizar tempo gasto compilando uma compilação de release localmente, fornecemos uma maneira de executar compilações de release de pull requests. Isso é útil para testar manualmente alterações em uma compilação de release antes de serem mescladas.

Para executar uma compilação de release de um pull request, você pode usar o pacote npm bun-pr:

bunx bun-pr <numero-pr>
bunx bun-pr <nome-branch>
bunx bun-pr "https://github.com/oven-sh/bun/pull/1234566"
bunx bun-pr --asan <numero-pr> # Apenas Linux x64

Isso baixará a compilação de release do pull request e a adicionará ao $PATH como bun-${numero-pr}. Você pode então executar a compilação com bun-${numero-pr}.

bun-1234566 --version

Isso funciona baixando a compilação de release dos artefatos do GitHub Actions no pull request vinculado. Você pode precisar da CLI gh instalada para autenticar com o GitHub.

AddressSanitizer

AddressSanitizer ajuda a encontrar problemas de memória e é habilitado por padrão em compilações de depuração do Bun no Linux e macOS. Isso inclui o código Zig e todas as dependências. Faz com que o código Zig leve cerca de 2x mais tempo para compilar; se isso estiver impedindo sua produtividade, você pode desabilitá-lo definindo -Denable_asan=$<IF:$<BOOL:${ENABLE_ASAN}>,true,false> para -Denable_asan=false no arquivo cmake/targets/BuildBun.cmake, mas geralmente recomendamos agrupar suas alterações entre compilações.

Para compilar uma compilação de release com Address Sanitizer, execute:

bun run build:release:asan

No CI, executamos nossa suíte de testes com pelo menos um alvo que é compilado com Address Sanitizer.

Compilando o WebKit localmente + Modo de depuração do JSC

O WebKit não é clonado por padrão (para economizar tempo e espaço em disco). Para clonar e compilar o WebKit localmente, execute:

# Clonar WebKit em ./vendor/WebKit
$ git clone https://github.com/oven-sh/WebKit vendor/WebKit

# Fazer checkout do commit hash especificado em `set(WEBKIT_VERSION <commit_hash>)` em cmake/tools/SetupWebKit.cmake
$ git -C vendor/WebKit checkout <commit_hash>

# Fazer uma compilação de depuração do JSC. Isso produzirá artefatos de compilação em ./vendor/WebKit/WebKitBuild/Debug
# Opcionalmente, você pode usar `bun run jsc:build` para uma compilação de release
bun run jsc:build:debug && rm vendor/WebKit/WebKitBuild/Debug/JavaScriptCore/DerivedSources/inspector/InspectorProtocolObjects.h

# Após uma execução inicial de `make jsc-debug`, você pode recompilar o JSC com:
$ cmake --build vendor/WebKit/WebKitBuild/Debug --target jsc && rm vendor/WebKit/WebKitBuild/Debug/JavaScriptCore/DerivedSources/inspector/InspectorProtocolObjects.h

# Compilar bun com a compilação local do JSC
bun run build:local

Usar bun run build:local compilará o Bun no diretório ./build/debug-local (em vez de ./build/debug), você terá que alterar alguns lugares para usar este novo diretório:

• A primeira linha em src/js/builtins.d.ts
• A linha CompilationDatabase na configuração .clangd deve ser CompilationDatabase: build/debug-local
• Em build.zig, a opção codegen_path deve ser build/debug-local/codegen (em vez de build/debug/codegen)
• Em .vscode/launch.json, muitas configurações usam ./build/debug/, altere-as conforme necessário

Note que a pasta WebKit, incluindo artefatos de compilação, tem mais de 8GB.

Se você estiver usando uma compilação de depuração do JSC e usando VScode, certifique-se de executar o comando C/C++: Select a Configuration para configurar o intellisense para encontrar os headers de depuração.

Note que se você fizer alterações no nosso fork do WebKit, você também terá que alterar o SetupWebKit.cmake para apontar para o commit hash.

Solução de Problemas

Arquivo 'span' não encontrado no Ubuntu

O compilador Clang normalmente usa a biblioteca padrão C++ libstdc++ por padrão. libstdc++ é a biblioteca padrão C++ padrão fornecida pelo GNU Compiler Collection (GCC). Embora o Clang possa vincular à biblioteca libc++, isso requer fornecer explicitamente a flag -stdlib ao executar o Clang.

O Bun depende de recursos C++20 como std::span, que não estão disponíveis em versões do GCC inferiores a 11. O GCC 10 não tem todos os recursos C++20 implementados. Como resultado, executar make setup pode falhar com o seguinte erro:

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

O problema pode se manifestar ao executar bun setup inicialmente como o Clang sendo incapaz de compilar um programa simples:

The C++ compiler

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

is not able to compile a simple test program.

Para corrigir o erro, precisamos atualizar a versão do GCC para 11. Para fazer isso, precisaremos verificar se a versão mais recente está disponível nos repositórios oficiais da distribuição ou usar um repositório de terceiros que forneça pacotes GCC 11. Aqui estão as etapas gerais:

$ sudo apt update
$ sudo apt install gcc-11 g++-11
# Se o comando acima falhar com `Unable to locate package gcc-11` precisamos
# adicionar o repositório APT
$ sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
# Agora execute `apt install` novamente
$ sudo apt install gcc-11 g++-11

Agora, precisamos definir o GCC 11 como compilador padrão:

$ 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 você vir um erro no macOS ao compilar libarchive, execute:

$ brew install pkg-config

macOS library not found for -lSystem

Se você vir este erro ao compilar, execute:

$ xcode-select --install

Não é possível encontrar libatomic.a

O Bun padrão vincula libatomic estaticamente, pois nem todos os sistemas o têm. Se você estiver compilando em uma distribuição que não tem libatomic estático disponível, pode executar o seguinte comando para habilitar vinculação dinâmica:

bun run build -DUSE_STATIC_LIBATOMIC=OFF

A versão compilada do Bun pode não funcionar em outros sistemas se compilada desta maneira.

Usando bun-debug

• Desabilitar logging: BUN_DEBUG_QUIET_LOGS=1 bun-debug ... (para desabilitar todo o log de depuração)
• Habilitar logging para um escopo zig específico: BUN_DEBUG_EventLoop=1 bun-debug ... (para permitir std.log.scoped(.EventLoop))
• O Bun transpila cada arquivo que executa, para ver o código fonte real executado em uma compilação de depuração, encontre-o em /tmp/bun-debug-src/...caminho/para/arquivo, por exemplo, a versão transpilada de /home/bun/index.ts estaria em /tmp/bun-debug-src/home/bun/index.ts