This page documents Bun's CMake-based build system, which orchestrates the compilation of C++ code (JavaScriptCore bindings), Zig code (runtime and bundler), and integration of third-party dependencies. CMake serves as the top-level build orchestrator that configures compilers, manages dependencies, and defines build targets.
For information about the Zig-specific build system, see Zig Build System. For code generation steps that occur before compilation, see Code Generation Pipeline. For CI/CD pipeline configuration, see CI/CD Pipeline.
Bun's build system uses CMake (minimum version 3.24) as the top-level configuration layer, which then invokes Zig's build system for Zig code and LLVM/Clang for C++ code. The build process produces a single bun executable that links together compiled C++ objects (bun-cpp.a) and Zig objects (bun-zig.o).
Diagram: CMake Configuration Flow
Sources: CMakeLists.txt1-67
CMake searches for included modules in directories specified in CMAKE_MODULE_PATH. Bun's build system organizes modules into subdirectories under cmake/:
Diagram: CMake Module Organization
The module path is configured as:
${CMAKE_SOURCE_DIR}/cmake - Base modules (policies, globals, options)${CMAKE_SOURCE_DIR}/cmake/targets - Build target definitions${CMAKE_SOURCE_DIR}/cmake/tools - Tool setup (compilers, build tools)${CMAKE_SOURCE_DIR}/cmake/analysis - Static analysis tool configurations${CMAKE_SOURCE_DIR}/cmake/scripts - Build scripts and utilitiesSources: CMakeLists.txt4-10
The project version is parsed from package.json and can be overridden with the VERSION CMake option:
Diagram: Version and Project Setup
The project is configured with:
Bunpackage.json (currently 1.3.10)Sources: CMakeLists.txt30-36 package.json4
On all platforms, SetupLLVM.cmake is included to configure the C++ compiler. Bun requires Clang/LLVM for C++ compilation due to its specific compiler features and optimizations.
On macOS hosts, SetupMacSDK.cmake is included before compiler setup to configure the macOS SDK paths:
Diagram: Platform-Specific Compiler Setup
On Windows hosts, CMake TLS verification is disabled as a workaround for certificate verification issues when downloading dependencies from GitHub:
Sources: CMakeLists.txt15-19 CMakeLists.txt23-26
Bun's build requires multiple tools that are configured through dedicated CMake modules:
| Module | Purpose |
|---|---|
SetupGit.cmake | Configure Git for version control operations |
SetupBuildkite.cmake | CI/CD pipeline integration |
SetupBun.cmake | Bootstrap Bun for build scripts |
SetupEsbuild.cmake | JavaScript bundler for internal modules |
SetupZig.cmake | Zig compiler for runtime/bundler compilation |
SetupRust.cmake | Rust toolchain for dependency version tracking |
SetupCcache.cmake | Compiler cache for faster rebuilds |
Diagram: Tool Setup Dependencies
Sources: CMakeLists.txt43-50
The GenerateDependencyVersions.cmake module generates a C++ header file containing version information for all dependencies. This is implemented using Rust code that extracts version numbers:
Diagram: Dependency Version Tracking
This header is used at runtime to report dependency versions in debug output and error messages.
Sources: CMakeLists.txt52-53
The main build targets are defined in BuildBun.cmake:
Diagram: Build Target Composition
Sources: CMakeLists.txt57
Bun supports multiple build configurations through CMake build types and custom options. These are typically invoked through npm scripts in package.json:
| Configuration | CMake Flags | Purpose |
|---|---|---|
| Debug | -DCMAKE_BUILD_TYPE=Debug | Development builds with symbols |
| Release | -DCMAKE_BUILD_TYPE=Release | Optimized production builds |
| RelWithDebInfo | -DCMAKE_BUILD_TYPE=RelWithDebInfo -DENABLE_ASSERTIONS=ON | Optimized with assertions |
| MinSizeRel | -DCMAKE_BUILD_TYPE=MinSizeRel | Size-optimized builds |
| ASAN | -DENABLE_ASAN=ON | AddressSanitizer for memory debugging |
| Local WebKit | -DWEBKIT_LOCAL=ON | Use locally built WebKit instead of prebuilt |
Diagram: Build Configuration Invocation
The standard debug build is configured with:
bun ./scripts/build.mjs -GNinja -DCMAKE_BUILD_TYPE=Debug -B build/debug
Key characteristics:
build/debugProduction builds use:
bun ./scripts/build.mjs -GNinja -DCMAKE_BUILD_TYPE=Release -B build/release
Key characteristics:
-DCMAKE_BUILD_TYPE=RelWithDebInfo)build/releaseCI builds use specific flags for reproducibility:
bun ./scripts/build.mjs -GNinja -DCMAKE_BUILD_TYPE=Release -DCMAKE_VERBOSE_MAKEFILE=ON -DCI=true -B build/release-ci --verbose --fresh
Key characteristics:
CMAKE_VERBOSE_MAKEFILE=ON - Show full compilation commandsCI=true - CI-specific behavior--fresh - Clean build from scratchSources: package.json36-48
Bun defines several custom CMake options that control build behavior:
Diagram: CMake Build Options
These options are set via -D flags when invoking CMake. The Options.cmake module processes these and sets up appropriate compiler flags and definitions.
Sources: CMakeLists.txt38 package.json36-48
When ENABLE_ANALYSIS=ON is set, CMake configures static analysis tools:
Diagram: Analysis Tool Integration
These tools can be invoked via CMake targets:
clang-format - Format C++ codeclang-format-check - Check C++ formattingclang-tidy - Run static analysis on C++zig-format - Format Zig codeprettier - Format JavaScript/TypeScriptThe analysis configuration disables ccache (ENABLE_CCACHE=OFF) to ensure accurate analysis results.
Sources: CMakeLists.txt61-66 package.json76-85
The CMake build generates artifacts in build directories:
Diagram: Build Directory Layout
All build directories are listed in .gitignore under the pattern /build-*/ and build/. The compile_commands.json file is generated for IDE and static analysis tool integration.
Sources: .gitignore56 .gitignore66-67 .gitignore73-78
The build.mjs script wraps CMake invocation with additional logic:
Diagram: Build Script Execution Flow
The build script is invoked through npm/bun scripts, which set up appropriate environment variables and CMake flags for different build configurations.
Sources: package.json30 package.json36-48
CMake configures the Zig build system through SetupZig.cmake, but the actual Zig compilation is managed by build.zig. CMake:
zig build as part of the CMake build processThe ZIG_OPTIMIZE CMake option controls the Zig optimization level independently of the C++ optimization level:
Debug - No optimizationsReleaseSafe - Optimizations with safety checksReleaseFast - Maximum optimizationsReleaseSmall - Size optimizationsSources: CMakeLists.txt47 package.json44 package.json49
Bun's build system supports incremental compilation through:
The watch npm script demonstrates incremental compilation for development:
bun run zig build check --watch -fincremental
This enables Zig's watch mode with incremental compilation, recompiling only changed modules.
Sources: CMakeLists.txt50 package.json32-33
Refresh this wiki