Configurar un entorno de desarrollo para Bun puede tomar entre 10 y 30 minutos dependiendo de tu conexión a Internet y la velocidad de tu computadora. Necesitarás aproximadamente 10 GB de espacio libre en disco para el repositorio y los artefactos de compilación.

Si estás usando Windows, consulta esta guía

Usar Nix (Alternativa)

Se proporciona un Nix flake como alternativa a la instalación manual de dependencias:

nix develop
# o usar explícitamente el shell puro
# nix develop .#pure
export CMAKE_SYSTEM_PROCESSOR=$(uname -m)
bun bd

Esto proporciona todas las dependencias en un entorno aislado y reproducible sin requerir sudo.

Instalar dependencias (Manual)

Usando el gestor de paquetes de tu sistema, instala las dependencias 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

Nota: El compilador Zig se instala y actualiza automáticamente mediante los scripts de compilación. No es necesario instalarlo manualmente.

Antes de comenzar, ya debes tener instalada una versión de lanzamiento de Bun, ya que usamos nuestro empaquetador para transpilar y minificar nuestro código, así como para los scripts de generación 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 se usa para cachear artefactos de compilación, acelerando significativamente las compilaciones. Debe instalarse con soporte S3:

# Para macOS
$ brew install sccache

# Para Linux. Ten en cuenta que la versión en tu gestor de paquetes puede no tener soporte S3.
$ cargo install sccache --features=s3

Esto instalará sccache con soporte S3. Nuestros scripts de compilación detectarán y usarán automáticamente sccache con nuestro caché S3 compartido. Nota: No todas las versiones de sccache se compilan con soporte S3, por lo que recomendamos instalarlo mediante cargo.

Registrar credenciales de AWS para sccache (Solo desarrolladores principales)

Los desarrolladores principales tienen acceso de escritura al caché S3 compartido. Para habilitar el acceso de escritura, debes iniciar sesión con credenciales de AWS. La forma más fácil de hacerlo es usar la CLI de aws e invocar aws configure para proporcionar tu información de seguridad de AWS.

Los scripts de cmake deberían detectar automáticamente tus credenciales de AWS desde el entorno o el archivo ~/.aws/credentials.

Iniciar sesión en la CLI de `aws`

1. Instala la CLI de AWS siguiendo [la guía oficial](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
2. Inicia sesión en la consola de tu cuenta de AWS. Un miembro del equipo debería proporcionarte tus credenciales.
3. Haz clic en tu nombre en la parte superior derecha > Credenciales de seguridad.
4. Desplázate hasta "Claves de acceso" y crea una nueva clave de acceso.
5. Ejecuta `aws configure` en tu terminal y proporciona el ID de clave de acceso y la clave de acceso secreta cuando se te solicite.

Problemas comunes que puedes encontrar

- Para confirmar que se está usando el caché, puedes usar el comando `sccache --show-stats` justo después de una compilación. Esto mostrará estadísticas muy útiles, incluidos los aciertos/fallos del caché.
- Si tienes múltiples perfiles de AWS configurados, asegúrate de que el perfil correcto esté establecido en la variable de entorno `AWS_PROFILE`.
- `sccache` sigue un modelo cliente-servidor. Si encuentras problemas extraños donde `sccache` se niega a usar S3, aunque tengas credenciales de AWS configuradas, intenta detener cualquier servidor `sccache` en ejecución con `sccache --stop-server` y luego vuelve a ejecutar la compilación.

Instalar LLVM

Bun requiere LLVM 19 (clang es parte de LLVM). Este requisito de versión es para coincidir con WebKit (precompilado), ya que las versiones que no coinciden causarán fallos de asignación de memoria en tiempo de ejecución. En la mayoría de los casos, puedes instalar LLVM a través del gestor de paquetes de tu sistema:

$ brew install llvm@19

$ # LLVM tiene un script de instalación automática compatible con todas las versiones de 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 ninguna de las soluciones anteriores funciona, tendrás que instalarlo manualmente.

Asegúrate de que Clang/LLVM 19 esté en tu ruta:

$ which clang-19

Si no, ejecuta esto para agregarlo manualmente:

# usa fish_add_path si estás usando fish
# usa path+="$(brew --prefix llvm@19)/bin" si estás usando zsh
$ export PATH="$(brew --prefix llvm@19)/bin:$PATH"

# usa fish_add_path si estás usando fish
$ export PATH="$PATH:/usr/lib/llvm19/bin"

Compilar Bun

Después de clonar el repositorio, ejecuta el siguiente comando para compilar. Esto puede tomar un tiempo ya que clonará los submódulos y compilará las dependencias.

bun run build

El binario se ubicará en ./build/debug/bun-debug. Se recomienda agregar esto a tu $PATH. Para verificar que la compilación funcionó, imprimamos el número de versión en la versión de desarrollo de Bun.

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

VSCode

VSCode es el IDE recomendado para trabajar en Bun, ya que ha sido configurado. Una vez abierto, puedes ejecutar Extensions: Show Recommended Extensions para instalar las extensiones recomendadas para Zig y C++. ZLS se configura automáticamente.

Si usas un editor diferente, asegúrate de indicarle a ZLS que use el compilador Zig instalado automáticamente, que se encuentra en ./vendor/zig/zig.exe. El nombre del archivo es zig.exe para que funcione como se espera en Windows, pero aún funciona en macOS/Linux (solo tiene una extensión de archivo sorprendente).

Recomendamos agregar ./build/debug a tu $PATH para que puedas ejecutar bun-debug en tu terminal:

bun-debug

Ejecutar compilaciones de depuración

El script de package.json bd compila y ejecuta una compilación de depuración de Bun, mostrando solo la salida del proceso de compilación si falla.

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

Bun generalmente toma aproximadamente 2.5 minutos compilar una compilación de depuración cuando hay cambios en Zig. Si tu flujo de trabajo de desarrollo es "cambiar una línea, guardar, recompilar", pasarás demasiado tiempo esperando que termine la compilación. En su lugar:

• Agrupa tus cambios
• Asegúrate de que zls esté ejecutándose con vigilancia incremental para errores de LSP (si usas VSCode e instalas Zig y ejecutas bun run build una vez para descargar Zig, esto debería funcionar)
• Prefiere usar el depurador ("CodeLLDB" en VSCode) para recorrer el código.
• Usa registros de depuración. BUN_DEBUG_<scope>=1 habilitará el registro de depuración para los registros Output.scoped(.<scope>, .hidden) correspondientes. También puedes establecer BUN_DEBUG_QUIET_LOGS=1 para deshabilitar todo el registro de depuración que no esté explícitamente habilitado. Para volcar los registros de depuración en un archivo, BUN_DEBUG=<ruta-al-archivo>.log. Los registros de depuración se eliminan agresivamente en las compilaciones de lanzamiento.
• Los cambios en src/js/**.ts son prácticamente instantáneos para recompilar. Los cambios en C++ son un poco más lentos, pero aún mucho más rápidos que el código Zig (Zig es una unidad de compilación, C++ son muchas).

Scripts de generación de código

Varios scripts de generación de código se usan durante el proceso de compilación de Bun. Estos se ejecutan automáticamente cuando se realizan cambios en ciertos archivos.

En particular, estos son:

• ./src/codegen/generate-jssink.ts -- Genera build/debug/codegen/JSSink.cpp, build/debug/codegen/JSSink.h que implementan varias clases para interactuar con ReadableStream. Así es como funcionan internamente FileSink, ArrayBufferSink, los flujos "type": "direct" y otro código relacionado con flujos.
• ./src/codegen/generate-classes.ts -- Genera build/debug/codegen/ZigGeneratedClasses*, que genera enlaces Zig y C++ para clases de JavaScriptCore implementadas en Zig. En archivos **/*.classes.ts, definimos las interfaces para varias clases, métodos, prototipos, getters/setters, etc., que el generador de código lee para generar código boilerplate que implementa los objetos de JavaScript en C++ y los conecta con Zig
• ./src/codegen/cppbind.ts -- Genera enlaces Zig automáticos para funciones C++ marcadas con atributos [[ZIG_EXPORT]].
• ./src/codegen/bundle-modules.ts -- Empaqueta módulos integrados como node:fs, bun:ffi en archivos que podemos incluir en el binario final. En desarrollo, estos se pueden recargar sin recompilar Zig (aún necesitas ejecutar bun run build, pero vuelve a leer los archivos transpilados del disco después). En compilaciones de lanzamiento, estos se incrustan en el binario.
• ./src/codegen/bundle-functions.ts -- Empaqueta funciones accesibles globalmente implementadas en JavaScript/TypeScript como ReadableStream, WritableStream, y algunas más. Estas se usan de manera similar a los módulos integrados, pero el resultado se alinea más estrechamente con lo que WebKit/Safari hace para las funciones integradas de Safari para que podamos copiar y pegar las implementaciones de WebKit como punto de partida.

Modificar módulos ESM

Ciertos módulos como node:fs, node:stream, bun:sqlite, y ws están implementados en JavaScript. Estos viven en archivos src/js/{node,bun,thirdparty} y se empaquetan previamente usando Bun.

Compilación de lanzamiento

Para compilar una versión de lanzamiento de Bun, ejecuta:

bun run build:release

El binario se ubicará en ./build/release/bun y ./build/release/bun-profile.

Descargar compilación de lanzamiento desde solicitudes de extracción

Para ahorrarte tiempo compilando una versión de lanzamiento localmente, proporcionamos una forma de ejecutar compilaciones de lanzamiento desde solicitudes de extracción. Esto es útil para probar manualmente cambios en una compilación de lanzamiento antes de que se fusionen.

Para ejecutar una compilación de lanzamiento desde una solicitud de extracción, puedes usar el paquete npm bun-pr:

bunx bun-pr <número-pr>
bunx bun-pr <nombre-rama>
bunx bun-pr "https://github.com/oven-sh/bun/pull/1234566"
bunx bun-pr --asan <número-pr> # Solo Linux x64

Esto descargará la compilación de lanzamiento desde los artefactos de GitHub Actions en la solicitud de extracción vinculada y la agregará a $PATH como bun-${pr-number}. Luego puedes ejecutar la compilación con bun-${pr-number}.

bun-1234566 --version

Esto funciona descargando la compilación de lanzamiento desde los artefactos de GitHub Actions en la solicitud de extracción vinculada. Es posible que necesites la CLI gh instalada para autenticarte con GitHub.

AddressSanitizer

AddressSanitizer ayuda a encontrar problemas de memoria y está habilitado de forma predeterminada en las compilaciones de depuración de Bun en Linux y macOS. Esto incluye el código Zig y todas las dependencias. Hace que el código Zig tarde aproximadamente el doble en compilarse, si eso te impide ser productivo, puedes deshabilitarlo estableciendo -Denable_asan=$<IF:$<BOOL:${ENABLE_ASAN}>,true,false> a -Denable_asan=false en el archivo cmake/targets/BuildBun.cmake, pero generalmente recomendamos agrupar tus cambios entre compilaciones.

Para compilar una versión de lanzamiento con Address Sanitizer, ejecuta:

bun run build:release:asan

En CI, ejecutamos nuestra suite de pruebas con al menos un objetivo que se compila con Address Sanitizer.

Compilar WebKit localmente + Modo de depuración de JSC

WebKit no se clona de forma predeterminada (para ahorrar tiempo y espacio en disco). Para clonar y compilar WebKit localmente, ejecuta:

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

# Hacer checkout del hash de commit especificado en `set(WEBKIT_VERSION <commit_hash>)` en cmake/tools/SetupWebKit.cmake
$ git -C vendor/WebKit checkout <commit_hash>

# Hacer una compilación de depuración de JSC. Esto generará artefactos de compilación en ./vendor/WebKit/WebKitBuild/Debug
# Opcionalmente, puedes usar `bun run jsc:build` para una compilación de lanzamiento
bun run jsc:build:debug && rm vendor/WebKit/WebKitBuild/Debug/JavaScriptCore/DerivedSources/inspector/InspectorProtocolObjects.h

# Después de una ejecución inicial de `make jsc-debug`, puedes recompilar JSC con:
$ cmake --build vendor/WebKit/WebKitBuild/Debug --target jsc && rm vendor/WebKit/WebKitBuild/Debug/JavaScriptCore/DerivedSources/inspector/InspectorProtocolObjects.h

# Compilar bun con la compilación local de JSC
bun run build:local

Usar bun run build:local compilará Bun en el directorio ./build/debug-local (en lugar de ./build/debug), tendrás que cambiar un par de lugares para usar este nuevo directorio:

• La primera línea en src/js/builtins.d.ts
• La línea CompilationDatabase en la configuración .clangd debe ser CompilationDatabase: build/debug-local
• En build.zig, la opción codegen_path debe ser build/debug-local/codegen (en lugar de build/debug/codegen)
• En .vscode/launch.json, muchas configuraciones usan ./build/debug/, cámbialas según corresponda

Ten en cuenta que la carpeta WebKit, incluidos los artefactos de compilación, tiene un tamaño de más de 8 GB.

Si estás usando una compilación de depuración de JSC y usando VScode, asegúrate de ejecutar el comando C/C++: Select a Configuration para configurar intellisense para encontrar los encabezados de depuración.

Ten en cuenta que si realizas cambios en nuestra bifurcación de WebKit, también tendrás que cambiar SetupWebKit.cmake para que apunte al hash de commit.

Solución de problemas

Archivo 'span' no encontrado en Ubuntu

El compilador Clang generalmente usa la biblioteca estándar C++ libstdc++ de forma predeterminada. libstdc++ es la implementación de biblioteca estándar C++ proporcionada por la Colección de Compiladores GNU (GCC). Aunque Clang puede vincularse con la biblioteca libc++, esto requiere proporcionar explícitamente la bandera -stdlib al ejecutar Clang.

Bun depende de características de C++20 como std::span, que no están disponibles en versiones de GCC inferiores a 11. GCC 10 no tiene todas las características de C++20 implementadas. Como resultado, ejecutar make setup puede fallar con el siguiente error:

error fatal: archivo 'span' no encontrado
#include <span>
         ^~~~~~

El problema puede manifestarse al ejecutar inicialmente bun setup como Clang sin poder compilar un programa simple:

El compilador C++

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

no puede compilar un programa de prueba simple.

Para corregir el error, necesitamos actualizar la versión de GCC a 11. Para hacer esto, necesitaremos verificar si la última versión está disponible en los repositorios oficiales de la distribución o usar un repositorio de terceros que proporcione paquetes GCC 11. Aquí están los pasos generales:

$ sudo apt update
$ sudo apt install gcc-11 g++-11
# Si el comando anterior falla con `Unable to locate package gcc-11` necesitamos
# agregar el repositorio APT
$ sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
# Ahora ejecuta `apt install` nuevamente
$ sudo apt install gcc-11 g++-11

Ahora, necesitamos establecer GCC 11 como el compilador predeterminado:

$ 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 ves un error en macOS al compilar libarchive, ejecuta:

$ brew install pkg-config

macOS library not found for -lSystem

Si ves este error al compilar, ejecuta:

$ xcode-select --install

No se puede encontrar libatomic.a

Bun predetermina vincular libatomic estáticamente, ya que no todos los sistemas lo tienen. Si estás compilando en una distribución que no tiene libatomic estático disponible, puedes ejecutar el siguiente comando para habilitar la vinculación dinámica:

bun run build -DUSE_STATIC_LIBATOMIC=OFF

La versión compilada de Bun puede no funcionar en otros sistemas si se compila de esta manera.

Usar bun-debug

• Deshabilitar registro: BUN_DEBUG_QUIET_LOGS=1 bun-debug ... (para deshabilitar todo el registro de depuración)
• Habilitar registro para un ámbito zig específico: BUN_DEBUG_EventLoop=1 bun-debug ... (para permitir std.log.scoped(.EventLoop))
• Bun transpila cada archivo que ejecuta, para ver el código fuente ejecutado real en una compilación de depuración, encuéntralo en /tmp/bun-debug-src/...ruta/al/archivo, por ejemplo, la versión transpilada de /home/bun/index.ts estaría en /tmp/bun-debug-src/home/bun/index.ts