Bun 의 개발 환경을 구성하는 것은 인터넷 연결과 컴퓨터 속도에 따라 10-30 분이 소요될 수 있습니다. 저장소와 빌드 아티팩트를 위해 약 10GB 의 여유 디스크 공간이 필요합니다.

Windows 를 사용하는 경우 이 가이드 를 참조하세요.

Nix 사용 (대안)

수동 종속성 설치의 대안으로 Nix flake 가 제공됩니다.

nix develop
# 또는 명시적으로 pure 쉘 사용
# nix develop .#pure
export CMAKE_SYSTEM_PROCESSOR=$(uname -m)
bun bd

이것은 sudo 가 필요 없이 격리되고 재현 가능한 환경에서 모든 종속성을 제공합니다.

종속성 설치 (수동)

시스템의 패키지 매니저를 사용하여 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

참고: Zig 컴파일러는 빌드 스크립트에 의해 자동으로 설치 및 업데이트됩니다. 수동 설치는 필요하지 않습니다.

시작하기 전에 이미 Bun 의 릴리스 빌드가 설치되어 있어야 합니다. 코드를 변환하고 축소하며 코드 생성 스크립트를 위해 번들러를 사용하기 때문입니다.

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

$ npm install -g bun

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

선택 사항: sccache 설치

sccache 는 컴파일 아티팩트를 캐시하여 빌드를 상당히 빠르게 합니다. S3 지원과 함께 설치되어야 합니다.

# macOS 용
$ brew install sccache

# Linux 용. 패키지 매니저의 버전에는 S3 지원이 없을 수 있습니다.
$ cargo install sccache --features=s3

이것은 S3 지원과 함께 sccache 를 설치합니다. 빌드 스크립트는 자동으로 감지하여 공유 S3 캐시와 함께 사용합니다. 참고: 모든 sccache 버전이 S3 지원으로 컴파일되는 것은 아니므로 cargo 를 통한 설치를 권장합니다.

sccache 를 위한 AWS 자격 증명 등록 (핵심 개발자 전용)

핵심 개발자는 공유 S3 캐시에 대한 쓰기 권한이 있습니다. 쓰기 권한을 활성화하려면 AWS 자격 증명으로 로그인해야 합니다. 가장 쉬운 방법은 aws CLI 를 사용하고 aws configure 를 호출하여 AWS 보안 정보를 제공 하는 것입니다.

cmake 스크립트는 환경이나 ~/.aws/credentials 파일에서 AWS 자격 증명을 자동으로 감지해야 합니다.

`aws` CLI 로그인

1. [공식 가이드](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) 에 따라 AWS CLI 를 설치합니다.
2. AWS 계정 콘솔에 로그인합니다. 팀 구성원이 자격 증명을 제공해야 합니다.
3. 오른쪽 상단의 이름 > Security credentials 를 클릭합니다.
4. "Access keys" 로 스크롤하여 새 액세스 키를 생성합니다.
5. 터미널에서 `aws configure` 를 실행하고 프롬프트가 표시되면 액세스 키 ID 와 비밀 액세스 키를 입력합니다.

자주 발생하는 문제

- 캐시가 사용되고 있는지 확인하려면 빌드 직후 `sccache --show-stats` 명령을 사용할 수 있습니다. 이것은 캐시 히트/미스를 포함한 매우 유용한 통계를 노출합니다.
- 여러 AWS 프로필이 구성된 경우 `AWS_PROFILE` 환경 변수에 올바른 프로필이 설정되어 있는지 확인하세요.
- `sccache` 는 서버 - 클라이언트 모델을 따릅니다. AWS 자격 증명이 구성되어 있음에도 불구하고 `sccache` 가 S3 를 사용하지 않는 이상한 문제가 발생하면 `sccache --stop-server` 로 실행 중인 `sccache` 서버를 종료한 다음 빌드를 다시 실행해 보세요.

LLVM 설치

Bun 에는 LLVM 19(clang 은 LLVM 의 일부) 가 필요합니다. 이 버전 요구사항은 WebKit(사전 컴파일됨) 과 일치하기 위한 것으로, 버전이 일치하지 않으면 런타임에 메모리 할당 오류가 발생합니다. 대부분의 경우 시스템 패키지 매니저를 통해 LLVM 을 설치할 수 있습니다.

$ brew install llvm@19

$ # LLVM 은 모든 버전의 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

위 솔루션 중 어느 것도 적용되지 않는 경우 수동으로 설치해야 합니다.

Clang/LLVM 19 가 경로에 있는지 확인하세요.

$ which clang-19

없다면 수동으로 추가하려면:

# fish 를 사용하는 경우 fish_add_path 사용
# zsh 를 사용하는 경우 path+="$(brew --prefix llvm@19)/bin" 사용
$ export PATH="$(brew --prefix llvm@19)/bin:$PATH"

# fish 를 사용하는 경우 fish_add_path 사용
$ export PATH="$PATH:/usr/lib/llvm19/bin"

Bun 빌드하기

저장소를 클론한 후 다음 명령을 실행하여 빌드합니다. 하위 모듈을 클론하고 종속성을 빌드하므로 시간이 걸릴 수 있습니다.

bun run build

바이너리는 ./build/debug/bun-debug 에 위치합니다. 이것을 $PATH 에 추가하는 것이 좋습니다. 빌드가 작동했는지 확인하기 위해 Bun 의 개발 빌드에서 버전 번호를 출력해 봅시다.

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

VSCode

VSCode 는 Bun 작업용으로 구성된 IDE 입니다. 연 후 Extensions: Show Recommended Extensions 를 실행하여 Zig 와 C++ 에 권장되는 확장 프로그램을 설치할 수 있습니다. ZLS 는 자동으로 구성됩니다.

다른 편집기를 사용하는 경우 ZLS 가 ./vendor/zig/zig.exe 에 위치한 자동 설치된 Zig 컴파일러를 사용하도록 설정하세요. 파일명은 Windows 에서 예상대로 작동하도록 zig.exe 이지만 macOS/Linux 에서도 작동합니다 (놀라운 파일 확장자가 있을 뿐입니다).

터미널에서 bun-debug 를 실행할 수 있도록 ./build/debug 를 $PATH 에 추가하는 것을 권장합니다.

bun-debug

디버그 빌드 실행

bd package.json 스크립트는 Bun 의 디버그 빌드를 컴파일하고 실행하며, 실패할 경우 빌드 프로세스의 출력만 표시합니다.

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

Bun 은 Zig 변경 사항이 있을 때 디버그 빌드를 컴파일하는 데 약 2.5 분이 소요됩니다. 개발 워크플로우가 "한 줄 변경, 저장, 재빌드"라면 빌드 완료를 기다리는 데 너무 많은 시간을 보내게 됩니다. 대신:

• 변경 사항을 묶어서 처리
• LSP 오류에 대한 증분 감시를 위해 zls 가 실행 중인지 확인 (VSCode 를 사용하고 Zig 를 설치하고 bun run build 를 한 번 실행하면 자동으로 작동)
• 코드를 단계별로 실행하기 위해 디버거 사용 (VSCode 에서 "CodeLLDB")
• 디버그 로그 사용. BUN_DEBUG_<scope>=1 은 해당 Output.scoped(.<scope>, .hidden) 로그에 대한 디버그 로깅을 활성화합니다. BUN_DEBUG_QUIET_LOGS=1 을 설정하여 명시적으로 활성화되지 않은 모든 디버그 로깅을 비활성화할 수도 있습니다. 디버그 로그를 파일로 덤프하려면 BUN_DEBUG=<path-to-file>.log 를 사용하세요. 디버그 로그는 릴리스 빌드에서 적극적으로 제거됩니다.
• src/js/**.ts 변경 사항은 재빌드가 거의 즉시 완료됩니다. C++ 변경 사항은 조금 느리지만 여전히 Zig 코드보다는 훨씬 빠릅니다 (Zig 는 하나의 컴파일 단위, C++ 는 여러 단위).

코드 생성 스크립트

Bun 의 빌드 프로세스 중 여러 코드 생성 스크립트가 사용됩니다. 이러한 스크립트는 특정 파일이 변경될 때 자동으로 실행됩니다.

특히 다음 스크립트가 있습니다.

• ./src/codegen/generate-jssink.ts -- ReadableStream 과 인터페이스하기 위한 다양한 클래스를 구현하는 build/debug/codegen/JSSink.cpp, build/debug/codegen/JSSink.h 생성. 내부적으로 FileSink, ArrayBufferSink, "type": "direct" 스트림 및 스트림 관련 다른 코드가 작동하는 방식입니다.
• ./src/codegen/generate-classes.ts -- build/debug/codegen/ZigGeneratedClasses* 생성. Zig 에서 구현된 JavaScriptCore 클래스에 대한 Zig 및 C++ 바인딩 생성. **/*.classes.ts 파일에서 다양한 클래스, 메서드, 프로토타입, getter/setter 등의 인터페이스를 정의하며, 코드 생성기가 이를 읽어 C++ 에서 JavaScript 객체를 구현하고 Zig 에 연결하는 보일러플레이트 코드를 생성합니다.
• ./src/codegen/cppbind.ts -- [[ZIG_EXPORT]] 속성이 표시된 C++ 함수에 대한 자동 Zig 바인딩 생성.
• ./src/codegen/bundle-modules.ts -- node:fs, bun:ffi 와 같은 내장 모듈을 최종 바이너리에 포함할 수 있는 파일로 번들링. 개발 중에는 Zig 를 재빌드하지 않고도 다시 로드할 수 있습니다 (여전히 bun run build 를 실행해야 하지만 이후에 디스크에서 변환된 파일을 다시 읽습니다). 릴리스 빌드에서는 바이너리에 임베드됩니다.
• ./src/codegen/bundle-functions.ts -- ReadableStream, WritableStream 및 몇 가지 더 있는 JavaScript/TypeScript 로 구현된 전역 액세스 가능 함수를 번들링. 내장 모듈과 유사하게 사용되지만 출력은 WebKit/Safari 가 Safari 의 내장 함수에 대해 수행하는 방식과 더 밀접하게 일치하여 WebKit 에서 구현을 복사하여 붙여넣을 수 있습니다.

ESM 모듈 수정

node:fs, node:stream, bun:sqlite, ws 와 같은 특정 모듈은 JavaScript 로 구현됩니다. 이들은 src/js/{node,bun,thirdparty} 파일에 위치하며 Bun 을 사용하여 사전 번들링됩니다.

릴리스 빌드

Bun 의 릴리스 빌드를 컴파일하려면 다음을 실행하세요.

bun run build:release

바이너리는 ./build/release/bun 및 ./build/release/bun-profile 에 위치합니다.

풀 리퀘스트에서 릴리스 빌드 다운로드

로컬에서 릴리스 빌드를 빌드하는 시간을 절약하기 위해 풀 리퀘스트에서 릴리스 빌드를 실행하는 방법을 제공합니다. 이는 병합되기 전에 릴리스 빌드에서 변경 사항을 수동으로 테스트할 때 유용합니다.

풀 리퀘스트에서 릴리스 빌드를 실행하려면 bun-pr npm 패키지를 사용할 수 있습니다.

bunx bun-pr <pr-number>
bunx bun-pr <branch-name>
bunx bun-pr "https://github.com/oven-sh/bun/pull/1234566"
bunx bun-pr --asan <pr-number> # Linux x64 전용

이것은 풀 리퀘스트에서 릴리스 빌드를 다운로드하고 $PATH 에 bun-${pr-number} 로 추가합니다. 그런 다음 bun-${pr-number} 로 빌드를 실행할 수 있습니다.

bun-1234566 --version

이것은 연결된 풀 리퀘스트의 GitHub Actions 아티팩트에서 릴리스 빌드를 다운로드하여 작동합니다. GitHub 인증을 위해 gh CLI 가 필요할 수 있습니다.

AddressSanitizer

AddressSanitizer 는 메모리 문제를 찾는 데 도움이 되며 Linux 와 macOS 에서 Bun 의 디버그 빌드에서 기본적으로 활성화됩니다. 여기에는 Zig 코드와 모든 종속성이 포함됩니다. Zig 코드의 빌드 시간을 약 2 배 길게 만듭니다. 이것이 생산성을 떨어뜨린다면 cmake/targets/BuildBun.cmake 파일에서 -Denable_asan=$<IF:$<BOOL:${ENABLE_ASAN}>,true,false> 를 -Denable_asan=false 로 설정하여 비활성화할 수 있지만 일반적으로 빌드 간에 변경 사항을 묶어 처리하는 것을 권장합니다.

Address Sanitizer 와 함께 릴리스 빌드를 빌드하려면 다음을 실행하세요.

bun run build:release:asan

CI 에서 테스트 스위트는 Address Sanitizer 로 빌드된 하나 이상의 대상으로 실행됩니다.

로컬에서 WebKit 빌드하기 + JSC 디버그 모드

WebKit 은 기본적으로 클론되지 않습니다 (시간과 디스크 공간 절약). WebKit 을 로컬에서 클론하고 빌드하려면 다음을 실행하세요.

# WebKit 을 ./vendor/WebKit 에 클론
$ git clone https://github.com/oven-sh/WebKit vendor/WebKit

# cmake/tools/SetupWebKit.cmake 의 `set(WEBKIT_VERSION <commit_hash>)` 에 지정된 커밋 해시 확인
$ git -C vendor/WebKit checkout <commit_hash>

# JSC 디버그 빌드 생성. ./vendor/WebKit/WebKitBuild/Debug 에 빌드 아티팩트 출력
# 선택적으로 릴리스 빌드는 `bun run jsc:build` 사용
bun run jsc:build:debug && rm vendor/WebKit/WebKitBuild/Debug/JavaScriptCore/DerivedSources/inspector/InspectorProtocolObjects.h

# `make jsc-debug` 초기 실행 후 다음을 사용하여 JSC 재빌드 가능
$ cmake --build vendor/WebKit/WebKitBuild/Debug --target jsc && rm vendor/WebKit/WebKitBuild/Debug/JavaScriptCore/DerivedSources/inspector/InspectorProtocolObjects.h

# 로컬 JSC 빌드로 bun 빌드
bun run build:local

bun run build:local 을 사용하면 Bun 이 ./build/debug 디렉토리 대신 ./build/debug-local 디렉토리에 빌드됩니다. 몇 군데를 변경해야 합니다.

• src/js/builtins.d.ts 의 첫 번째 줄
• .clangd 설정의 CompilationDatabase 줄은 CompilationDatabase: build/debug-local 이어야 함
• build.zig 에서 codegen_path 옵션은 build/debug-local/codegen 이어야 함 (build/debug/codegen 대신)
• .vscode/launch.json 에서 많은 설정이 ./build/debug/ 를 사용하므로 필요에 따라 변경

WebKit 폴더는 빌드 아티팩트를 포함하여 8GB 이상입니다.

JSC 디버그 빌드를 사용하고 VScode 를 사용하는 경우 C/C++: Select a Configuration 명령을 실행하여 인텔리센스가 디버그 헤더를 찾도록 구성하세요.

WebKit 포크 를 변경하는 경우 SetupWebKit.cmake 를 변경하여 커밋 해시를 가리키도록 해야 합니다.

문제 해결

Ubuntu 에서 'span' 파일을 찾을 수 없음

Clang 컴파일러는 일반적으로 기본적으로 libstdc++ C++ 표준 라이브러리를 사용합니다. libstdc++ 는 GNU Compiler Collection(GCC) 에서 제공하는 기본 C++ 표준 라이브러리 구현입니다. Clang 이 libc++ 라이브러리에 링크될 수 있지만 Clang 실행 시 -stdlib 플래그를 명시적으로 제공해야 합니다.

Bun 은 GCC 11 미만 버전에서 사용할 수 없는 std::span 과 같은 C++20 기능에 의존합니다. GCC 10 은 모든 C++20 기능이 구현되어 있지 않습니다. 결과적으로 make setup 실행이 다음 오류로 실패할 수 있습니다.

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

이 문제는 처음 bun setup 실행 시 Clang 이 간단한 프로그램을 컴파일할 수 없는 것으로 나타날 수 있습니다.

The C++ compiler

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

is not able to compile a simple test program.

오류를 수정하려면 GCC 버전을 11 로 업데이트해야 합니다. 이를 위해 공식 저장소에서 최신 버전을 사용할 수 있는지 확인하거나 GCC 11 패키지를 제공하는 타사 저장소를 사용해야 합니다. 일반적인 단계는 다음과 같습니다.

$ sudo apt update
$ sudo apt install gcc-11 g++-11
# 위 명령이 `Unable to locate package gcc-11` 으로 실패하면 APT 저장소를 추가해야 합니다
$ sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
# 이제 `apt install` 다시 실행
$ sudo apt install gcc-11 g++-11

이제 GCC 11 을 기본 컴파일러로 설정해야 합니다.

$ 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

macOS 에서 libarchive 컴파일 시 오류가 발생하면 다음을 실행하세요.

$ brew install pkg-config

macOS library not found for -lSystem

컴파일 시 이 오류가 발생하면 다음을 실행하세요.

$ xcode-select --install

libatomic.a 를 찾을 수 없음

Bun 은 모든 시스템에 있는 것이 아니므로 기본적으로 libatomic 을 정적으로 링크합니다. 정적 libatomic 을 사용할 수 없는 배포판에서 빌드하는 경우 다음 명령을 실행하여 동적 링크를 활성화할 수 있습니다.

bun run build -DUSE_STATIC_LIBATOMIC=OFF

이렇게 컴파일된 Bun 버전은 다른 시스템에서 작동하지 않을 수 있습니다.

bun-debug 사용

• 로깅 비활성화: BUN_DEBUG_QUIET_LOGS=1 bun-debug ... (모든 디버그 로깅 비활성화)
• 특정 zig 스코프에 대한 로깅 활성화: BUN_DEBUG_EventLoop=1 bun-debug ... (std.log.scoped(.EventLoop) 허용)
• Bun 은 실행하는 모든 파일을 변환합니다. 디버그 빌드에서 실제 실행된 소스를 보려면 /tmp/bun-debug-src/...path/to/file 에서 찾으면 됩니다. 예를 들어 /home/bun/index.ts 의 변환된 버전은 /tmp/bun-debug-src/home/bun/index.ts 에 있습니다.