mirror of
https://github.com/oven-sh/bun
synced 2026-02-09 10:28:47 +00:00
Rewrite Developer Docs, Improve DX for new users, moving away from Devcontainer (#2588)
* new docs starting point. missing alot of information * very experimental idea: make setup * run on ubuntu 20 * builds on ubuntu 20 (wsl) now * add release instructions * add valgrind note from jarred/new-bundler branch, just in case it gets lost when rebasing * changes requested
This commit is contained in:
dave caruso
committed by
Dylan Conway
Dylan Conway
parent
302c860915
commit
fc07f76774
1
.gitignore
vendored
1
.gitignore
vendored
@@ -45,6 +45,7 @@ outcss
|
||||
txt.js
|
||||
.idea
|
||||
.vscode/cpp*
|
||||
.vscode/clang*
|
||||
|
||||
node_modules_*
|
||||
*.jsb
|
||||
|
||||
@@ -7,3 +7,6 @@ if [ -d ./node_modules/bun-webkit ]; then
|
||||
# get the first matching bun-webkit-* directory name
|
||||
ln -s ./node_modules/$(ls ./node_modules | grep bun-webkit- | head -n 1) ./bun-webkit
|
||||
fi
|
||||
|
||||
# sets up vscode C++ intellisense
|
||||
ln -s $(which clang++-15 || which clang++) .vscode/clang++ 2>/dev/null
|
||||
|
||||
6
.vscode/c_cpp_properties.json
vendored
6
.vscode/c_cpp_properties.json
vendored
@@ -2,9 +2,7 @@
|
||||
"configurations": [
|
||||
{
|
||||
"name": "Mac",
|
||||
"forcedInclude": [
|
||||
"${workspaceFolder}/src/bun.js/bindings/root.h"
|
||||
],
|
||||
"forcedInclude": ["${workspaceFolder}/src/bun.js/bindings/root.h"],
|
||||
"includePath": [
|
||||
"${workspaceFolder}/../webkit-build/include/",
|
||||
"${workspaceFolder}/bun-webkit/include/",
|
||||
@@ -57,7 +55,7 @@
|
||||
"DU_DISABLE_RENAMING=1"
|
||||
],
|
||||
"macFrameworkPath": [],
|
||||
"compilerPath": "/opt/homebrew/opt/llvm/bin/clang++",
|
||||
"compilerPath": "${workspaceFolder}/.vscode/clang++",
|
||||
"cStandard": "c17",
|
||||
"cppStandard": "c++20"
|
||||
}
|
||||
|
||||
3
.vscode/extensions.json
vendored
3
.vscode/extensions.json
vendored
@@ -4,6 +4,7 @@
|
||||
"esbenp.prettier-vscode",
|
||||
"xaver.clang-format",
|
||||
"vadimcn.vscode-lldb",
|
||||
"bierner.comment-tagged-templates"
|
||||
"bierner.comment-tagged-templates",
|
||||
"ms-vscode.cpptools"
|
||||
]
|
||||
}
|
||||
|
||||
@@ -18,7 +18,7 @@ The JavaScript transpiler & module resolver is mostly independent from the runti
|
||||
|
||||
## Getting started
|
||||
|
||||
Please refer to [Bun's Development Guide](https://bun.sh/docs/project/developing) to get your dev environment setup!
|
||||
Please refer to [Bun's Development Guide](https://bun.sh/docs/project/development) to get your dev environment setup!
|
||||
|
||||
## Memory management in Bun
|
||||
|
||||
|
||||
85
Makefile
85
Makefile
@@ -1,4 +1,4 @@
|
||||
SHELL := $(shell which bash) # Use bash syntax to be consistent
|
||||
SHELL := $(shell which bash) # Use bash syntax to be consistent
|
||||
|
||||
OS_NAME := $(shell uname -s | tr '[:upper:]' '[:lower:]')
|
||||
ARCH_NAME_RAW := $(shell uname -m)
|
||||
@@ -43,7 +43,7 @@ BUN_BASE_VERSION = 0.6
|
||||
|
||||
AR=
|
||||
|
||||
BUN_OR_NODE = $(shell which bun || which node)
|
||||
BUN_OR_NODE = $(shell which bun 2>/dev/null || which node 2>/dev/null)
|
||||
|
||||
CXX_VERSION=c++2a
|
||||
TRIPLET = $(OS_NAME)-$(ARCH_NAME)
|
||||
@@ -52,30 +52,31 @@ PACKAGES_REALPATH = $(realpath packages)
|
||||
PACKAGE_DIR = $(PACKAGES_REALPATH)/$(PACKAGE_NAME)
|
||||
DEBUG_PACKAGE_DIR = $(PACKAGES_REALPATH)/debug-$(PACKAGE_NAME)
|
||||
RELEASE_BUN = $(PACKAGE_DIR)/bun
|
||||
DEBUG_BIN = $(DEBUG_PACKAGE_DIR)/
|
||||
DEBUG_BIN = $(DEBUG_PACKAGE_DIR)
|
||||
DEBUG_BUN = $(DEBUG_BIN)/bun-debug
|
||||
BUILD_ID = $(shell cat ./src/build-id)
|
||||
PACKAGE_JSON_VERSION = $(BUN_BASE_VERSION).$(BUILD_ID)
|
||||
BUN_BUILD_TAG = bun-v$(PACKAGE_JSON_VERSION)
|
||||
BUN_RELEASE_BIN = $(PACKAGE_DIR)/bun
|
||||
PRETTIER ?= $(shell which prettier || echo "./node_modules/.bin/prettier")
|
||||
DSYMUTIL ?= $(shell which dsymutil || which dsymutil-15)
|
||||
PRETTIER ?= $(shell which prettier 2>/dev/null || echo "./node_modules/.bin/prettier")
|
||||
ESBUILD = $(shell which esbuild 2>/dev/null || echo "./node_modules/.bin/esbuild")
|
||||
DSYMUTIL ?= $(shell which dsymutil 2>/dev/null || which dsymutil-15 2>/dev/null)
|
||||
WEBKIT_DIR ?= $(realpath src/bun.js/WebKit)
|
||||
WEBKIT_RELEASE_DIR ?= $(WEBKIT_DIR)/WebKitBuild/Release
|
||||
WEBKIT_DEBUG_DIR ?= $(WEBKIT_DIR)/WebKitBuild/Debug
|
||||
WEBKIT_RELEASE_DIR_LTO ?= $(WEBKIT_DIR)/WebKitBuild/ReleaseLTO
|
||||
|
||||
|
||||
NPM_CLIENT ?= $(shell which bun || which npm)
|
||||
ZIG ?= $(shell which zig || echo -e "error: Missing zig. Please make sure zig is in PATH. Or set ZIG=/path/to-zig-executable")
|
||||
NPM_CLIENT ?= $(shell which bun 2>/dev/null || which npm 2>/dev/null)
|
||||
ZIG ?= $(shell which zig 2>/dev/null || echo -e "error: Missing zig. Please make sure zig is in PATH. Or set ZIG=/path/to-zig-executable")
|
||||
|
||||
# We must use the same compiler version for the JavaScriptCore bindings and JavaScriptCore
|
||||
# If we don't do this, strange memory allocation failures occur.
|
||||
# This is easier to happen than you'd expect.
|
||||
# Using realpath here causes issues because clang uses clang++ as a symlink
|
||||
# so if that's resolved, it won't build for C++
|
||||
REAL_CC = $(shell which clang-15 || which clang)
|
||||
REAL_CXX = $(shell which clang++-15 || which clang++)
|
||||
REAL_CC = $(shell which clang-15 2>/dev/null || which clang 2>/dev/null)
|
||||
REAL_CXX = $(shell which clang++-15 2>/dev/null || which clang++ 2>/dev/null)
|
||||
|
||||
CC = $(REAL_CC)
|
||||
CXX = $(REAL_CXX)
|
||||
@@ -85,7 +86,7 @@ CCACHE_PATH := $(shell which ccache 2>/dev/null)
|
||||
|
||||
CCACHE_CC_FLAG = CC=$(CCACHE_CC_OR_CC)
|
||||
|
||||
ifeq (,$(findstring,$(shell which ccache),ccache))
|
||||
ifeq (,$(findstring,$(shell which ccache 2>/dev/null),ccache))
|
||||
CMAKE_CXX_COMPILER_LAUNCHER_FLAG := -DCMAKE_CXX_COMPILER_LAUNCHER=$(CCACHE_PATH) -DCMAKE_C_COMPILER_LAUNCHER=$(CCACHE_PATH)
|
||||
CCACHE_CC_OR_CC := "$(CCACHE_PATH) $(REAL_CC)"
|
||||
export CCACHE_COMPILERTYPE = clang
|
||||
@@ -117,7 +118,7 @@ ifeq ($(OS_NAME),darwin)
|
||||
endif
|
||||
|
||||
# macOS sed is different
|
||||
SED = $(shell which gsed || which sed)
|
||||
SED = $(shell which gsed 2>/dev/null || which sed 2>/dev/null)
|
||||
|
||||
BUN_DIR ?= $(shell dirname $(realpath $(firstword $(MAKEFILE_LIST))))
|
||||
BUN_DEPS_DIR ?= $(shell pwd)/src/deps
|
||||
@@ -146,7 +147,7 @@ CMAKE_FLAGS_WITHOUT_RELEASE = -DCMAKE_C_COMPILER=$(CC) \
|
||||
-DCMAKE_OSX_DEPLOYMENT_TARGET=$(MIN_MACOS_VERSION) \
|
||||
$(CMAKE_CXX_COMPILER_LAUNCHER_FLAG) \
|
||||
-DCMAKE_AR=$(AR) \
|
||||
-DCMAKE_RANLIB=$(which llvm-15-ranlib || which llvm-ranlib)
|
||||
-DCMAKE_RANLIB=$(which llvm-15-ranlib 2>/dev/null || which llvm-ranlib 2>/dev/null)
|
||||
|
||||
|
||||
|
||||
@@ -168,7 +169,7 @@ endif
|
||||
|
||||
ifeq ($(OS_NAME),linux)
|
||||
LIBICONV_PATH =
|
||||
AR = $(shell which llvm-ar-15 || which llvm-ar || which ar)
|
||||
AR = $(shell which llvm-ar-15 2>/dev/null || which llvm-ar 2>/dev/null || which ar 2>/dev/null)
|
||||
endif
|
||||
|
||||
OPTIMIZATION_LEVEL=-O3 $(MARCH_NATIVE)
|
||||
@@ -266,7 +267,7 @@ STRIP=/usr/bin/strip
|
||||
endif
|
||||
|
||||
ifeq ($(OS_NAME),linux)
|
||||
STRIP=$(shell which llvm-strip || which llvm-strip-15 || which strip || echo "Missing strip")
|
||||
STRIP=$(shell which llvm-strip 2>/dev/null || which llvm-strip-15 2>/dev/null || which strip 2>/dev/null || echo "Missing strip")
|
||||
endif
|
||||
|
||||
|
||||
@@ -484,7 +485,9 @@ PLATFORM_LINKER_FLAGS = $(BUN_CFLAGS) \
|
||||
-static-libgcc \
|
||||
-fno-omit-frame-pointer \
|
||||
-Wl,--compress-debug-sections,zlib \
|
||||
-l:libatomic.a \
|
||||
-Bstatic \
|
||||
-latomic \
|
||||
-Bdynamic \
|
||||
${STATIC_MUSL_FLAG} \
|
||||
-Wl,-Bsymbolic-functions \
|
||||
-fno-semantic-interposition \
|
||||
@@ -540,13 +543,16 @@ tinycc:
|
||||
make -j10 && \
|
||||
cp $(TINYCC_DIR)/*.a $(BUN_DEPS_OUT_DIR)
|
||||
|
||||
PYTHON=$(shell which python 2>/dev/null || which python3 2>/dev/null || which python2 2>/dev/null)
|
||||
|
||||
.PHONY: builtins
|
||||
builtins: ## to generate builtins
|
||||
@if [ -z "$(WEBKIT_DIR)" ] || [ ! -d "$(WEBKIT_DIR)/Source" ]; then echo "WebKit is not cloned. Please run make init-submodules"; exit 1; fi
|
||||
rm -f src/bun.js/bindings/*Builtin*.cpp src/bun.js/bindings/*Builtin*.h src/bun.js/bindings/*Builtin*.cpp
|
||||
rm -rf src/bun.js/builtins/cpp
|
||||
mkdir -p src/bun.js/builtins/cpp
|
||||
$(shell which python || which python2) $(realpath $(WEBKIT_DIR)/Source/JavaScriptCore/Scripts/generate-js-builtins.py) -i $(realpath src)/bun.js/builtins/js -o $(realpath src)/bun.js/builtins/cpp --framework WebCore --force
|
||||
$(shell which python || which python2) $(realpath $(WEBKIT_DIR)/Source/JavaScriptCore/Scripts/generate-js-builtins.py) -i $(realpath src)/bun.js/builtins/js -o $(realpath src)/bun.js/builtins/cpp --framework WebCore --wrappers-only
|
||||
$(PYTHON) $(realpath $(WEBKIT_DIR)/Source/JavaScriptCore/Scripts/generate-js-builtins.py) -i $(realpath src)/bun.js/builtins/js -o $(realpath src)/bun.js/builtins/cpp --framework WebCore --force
|
||||
$(PYTHON) $(realpath $(WEBKIT_DIR)/Source/JavaScriptCore/Scripts/generate-js-builtins.py) -i $(realpath src)/bun.js/builtins/js -o $(realpath src)/bun.js/builtins/cpp --framework WebCore --wrappers-only
|
||||
rm -rf /tmp/1.h src/bun.js/builtins/cpp/WebCoreJSBuiltinInternals.h.1
|
||||
echo -e '// clang-format off\nnamespace Zig { class GlobalObject; }\n#include "root.h"\n' >> /tmp/1.h
|
||||
cat /tmp/1.h src/bun.js/builtins/cpp/WebCoreJSBuiltinInternals.h > src/bun.js/builtins/cpp/WebCoreJSBuiltinInternals.h.1
|
||||
@@ -665,7 +671,8 @@ require:
|
||||
@echo "Checking if the required utilities are available..."
|
||||
@if [ $(CLANG_VERSION) -lt "15" ]; then echo -e "ERROR: clang version >=15 required, found: $(CLANG_VERSION). Install with:\n\n $(POSIX_PKG_MANAGER) install llvm@15"; exit 1; fi
|
||||
@cmake --version >/dev/null 2>&1 || (echo -e "ERROR: cmake is required."; exit 1)
|
||||
@esbuild --version >/dev/null 2>&1 || (echo -e "ERROR: esbuild is required."; exit 1)
|
||||
@$(PYTHON) --version >/dev/null 2>&1 || (echo -e "ERROR: python is required."; exit 1)
|
||||
@$(ESBUILD) --version >/dev/null 2>&1 || (echo -e "ERROR: esbuild is required."; exit 1)
|
||||
@$(NPM_CLIENT) --version >/dev/null 2>&1 || (echo -e "ERROR: NPM client (bun or npm) is required."; exit 1)
|
||||
@go version >/dev/null 2>&1 || (echo -e "ERROR: go is required."; exit 1)
|
||||
@which aclocal > /dev/null || (echo -e "ERROR: automake is required. Install with:\n\n $(POSIX_PKG_MANAGER) install automake"; exit 1)
|
||||
@@ -674,7 +681,7 @@ require:
|
||||
@echo "You have the dependencies installed! Woo"
|
||||
|
||||
init-submodules:
|
||||
git submodule update --init --recursive --progress --depth=1
|
||||
git submodule update --init --recursive --progress --depth=1 --checkout
|
||||
|
||||
.PHONY: build-obj
|
||||
build-obj:
|
||||
@@ -720,10 +727,10 @@ wasm: api build-obj-wasm-small
|
||||
@cp src/api/schema.d.ts packages/bun-wasm/schema.d.ts
|
||||
@cp src/api/schema.js packages/bun-wasm/schema.js
|
||||
@cd packages/bun-wasm && $(NPM_CLIENT) run tsc -- -p .
|
||||
@esbuild --sourcemap=external --external:fs --define:process.env.NODE_ENV='"production"' --outdir=packages/bun-wasm --target=esnext --bundle packages/bun-wasm/index.ts --format=esm --minify 2> /dev/null
|
||||
@$(ESBUILD) --sourcemap=external --external:fs --define:process.env.NODE_ENV='"production"' --outdir=packages/bun-wasm --target=esnext --bundle packages/bun-wasm/index.ts --format=esm --minify 2> /dev/null
|
||||
@mv packages/bun-wasm/index.js packages/bun-wasm/index.mjs
|
||||
@mv packages/bun-wasm/index.js.map packages/bun-wasm/index.mjs.map
|
||||
@esbuild --sourcemap=external --external:fs --define:process.env.NODE_ENV='"production"' --outdir=packages/bun-wasm --target=esnext --bundle packages/bun-wasm/index.ts --format=cjs --minify --platform=node 2> /dev/null
|
||||
@$(ESBUILD) --sourcemap=external --external:fs --define:process.env.NODE_ENV='"production"' --outdir=packages/bun-wasm --target=esnext --bundle packages/bun-wasm/index.ts --format=cjs --minify --platform=node 2> /dev/null
|
||||
@mv packages/bun-wasm/index.js packages/bun-wasm/index.cjs
|
||||
@mv packages/bun-wasm/index.js.map packages/bun-wasm/index.cjs.map
|
||||
@rm -rf packages/bun-wasm/*.tsbuildinfo
|
||||
@@ -806,21 +813,21 @@ node-fallbacks:
|
||||
|
||||
.PHONY: fallback_decoder
|
||||
fallback_decoder:
|
||||
@esbuild --target=esnext --bundle src/fallback.ts --format=iife --platform=browser --minify > src/fallback.out.js
|
||||
@$(ESBUILD) --target=esnext --bundle src/fallback.ts --format=iife --platform=browser --minify > src/fallback.out.js
|
||||
|
||||
.PHONY: runtime_js
|
||||
runtime_js:
|
||||
@NODE_ENV=production esbuild --define:process.env.NODE_ENV="production" --target=esnext --bundle src/runtime/index.ts --format=iife --platform=browser --global-name=BUN_RUNTIME --minify --external:/bun:* > src/runtime.out.js; cat src/runtime.footer.js >> src/runtime.out.js
|
||||
@NODE_ENV=production esbuild --define:process.env.NODE_ENV="production" --target=esnext --bundle src/runtime/index-with-refresh.ts --format=iife --platform=browser --global-name=BUN_RUNTIME --minify --external:/bun:* > src/runtime.out.refresh.js; cat src/runtime.footer.with-refresh.js >> src/runtime.out.refresh.js
|
||||
@NODE_ENV=production esbuild --define:process.env.NODE_ENV="production" --target=esnext --bundle src/runtime/index-without-hmr.ts --format=iife --platform=node --global-name=BUN_RUNTIME --minify --external:/bun:* > src/runtime.node.pre.out.js; cat src/runtime.node.pre.out.js src/runtime.footer.node.js > src/runtime.node.out.js
|
||||
@NODE_ENV=production esbuild --define:process.env.NODE_ENV="production" --target=esnext --bundle src/runtime/index-without-hmr.ts --format=iife --platform=node --global-name=BUN_RUNTIME --minify --external:/bun:* > src/runtime.bun.pre.out.js; cat src/runtime.bun.pre.out.js src/runtime.footer.bun.js > src/runtime.bun.out.js
|
||||
@NODE_ENV=production $(ESBUILD) --define:process.env.NODE_ENV="production" --target=esnext --bundle src/runtime/index.ts --format=iife --platform=browser --global-name=BUN_RUNTIME --minify --external:/bun:* > src/runtime.out.js; cat src/runtime.footer.js >> src/runtime.out.js
|
||||
@NODE_ENV=production $(ESBUILD) --define:process.env.NODE_ENV="production" --target=esnext --bundle src/runtime/index-with-refresh.ts --format=iife --platform=browser --global-name=BUN_RUNTIME --minify --external:/bun:* > src/runtime.out.refresh.js; cat src/runtime.footer.with-refresh.js >> src/runtime.out.refresh.js
|
||||
@NODE_ENV=production $(ESBUILD) --define:process.env.NODE_ENV="production" --target=esnext --bundle src/runtime/index-without-hmr.ts --format=iife --platform=node --global-name=BUN_RUNTIME --minify --external:/bun:* > src/runtime.node.pre.out.js; cat src/runtime.node.pre.out.js src/runtime.footer.node.js > src/runtime.node.out.js
|
||||
@NODE_ENV=production $(ESBUILD) --define:process.env.NODE_ENV="production" --target=esnext --bundle src/runtime/index-without-hmr.ts --format=iife --platform=node --global-name=BUN_RUNTIME --minify --external:/bun:* > src/runtime.bun.pre.out.js; cat src/runtime.bun.pre.out.js src/runtime.footer.bun.js > src/runtime.bun.out.js
|
||||
|
||||
.PHONY: runtime_js_dev
|
||||
runtime_js_dev:
|
||||
@NODE_ENV=development esbuild --define:process.env.NODE_ENV="development" --target=esnext --bundle src/runtime/index.ts --format=iife --platform=browser --global-name=BUN_RUNTIME --external:/bun:* > src/runtime.out.js; cat src/runtime.footer.js >> src/runtime.out.js
|
||||
@NODE_ENV=development esbuild --define:process.env.NODE_ENV="development" --target=esnext --bundle src/runtime/index-with-refresh.ts --format=iife --platform=browser --global-name=BUN_RUNTIME --external:/bun:* > src/runtime.out.refresh.js; cat src/runtime.footer.with-refresh.js >> src/runtime.out.refresh.js
|
||||
@NODE_ENV=development esbuild --define:process.env.NODE_ENV="development" --target=esnext --bundle src/runtime/index-without-hmr.ts --format=iife --platform=node --global-name=BUN_RUNTIME --external:/bun:* > src/runtime.node.pre.out.js; cat src/runtime.node.pre.out.js src/runtime.footer.node.js > src/runtime.node.out.js
|
||||
@NODE_ENV=development esbuild --define:process.env.NODE_ENV="development" --target=esnext --bundle src/runtime/index-without-hmr.ts --format=iife --platform=node --global-name=BUN_RUNTIME --external:/bun:* > src/runtime.bun.pre.out.js; cat src/runtime.bun.pre.out.js src/runtime.footer.bun.js > src/runtime.bun.out.js
|
||||
@NODE_ENV=development $(ESBUILD) --define:process.env.NODE_ENV="development" --target=esnext --bundle src/runtime/index.ts --format=iife --platform=browser --global-name=BUN_RUNTIME --external:/bun:* > src/runtime.out.js; cat src/runtime.footer.js >> src/runtime.out.js
|
||||
@NODE_ENV=development $(ESBUILD) --define:process.env.NODE_ENV="development" --target=esnext --bundle src/runtime/index-with-refresh.ts --format=iife --platform=browser --global-name=BUN_RUNTIME --external:/bun:* > src/runtime.out.refresh.js; cat src/runtime.footer.with-refresh.js >> src/runtime.out.refresh.js
|
||||
@NODE_ENV=development $(ESBUILD) --define:process.env.NODE_ENV="development" --target=esnext --bundle src/runtime/index-without-hmr.ts --format=iife --platform=node --global-name=BUN_RUNTIME --external:/bun:* > src/runtime.node.pre.out.js; cat src/runtime.node.pre.out.js src/runtime.footer.node.js > src/runtime.node.out.js
|
||||
@NODE_ENV=development $(ESBUILD) --define:process.env.NODE_ENV="development" --target=esnext --bundle src/runtime/index-without-hmr.ts --format=iife --platform=node --global-name=BUN_RUNTIME --external:/bun:* > src/runtime.bun.pre.out.js; cat src/runtime.bun.pre.out.js src/runtime.footer.bun.js > src/runtime.bun.out.js
|
||||
|
||||
.PHONY: bun_error
|
||||
bun_error:
|
||||
@@ -829,7 +836,7 @@ bun_error:
|
||||
.PHONY: generate-install-script
|
||||
generate-install-script:
|
||||
@rm -f $(PACKAGES_REALPATH)/bun/install.js
|
||||
@esbuild --log-level=error --define:BUN_VERSION="\"$(PACKAGE_JSON_VERSION)\"" --define:process.env.NODE_ENV="\"production\"" --platform=node --format=cjs $(PACKAGES_REALPATH)/bun/install.ts > $(PACKAGES_REALPATH)/bun/install.js
|
||||
@$(ESBUILD) --log-level=error --define:BUN_VERSION="\"$(PACKAGE_JSON_VERSION)\"" --define:process.env.NODE_ENV="\"production\"" --platform=node --format=cjs $(PACKAGES_REALPATH)/bun/install.ts > $(PACKAGES_REALPATH)/bun/install.js
|
||||
|
||||
.PHONY: fetch
|
||||
fetch: $(IO_FILES)
|
||||
@@ -1844,3 +1851,19 @@ vendor: require init-submodules vendor-without-check
|
||||
.PHONY: bun
|
||||
bun: vendor identifier-cache build-obj bun-link-lld-release bun-codesign-release-local
|
||||
|
||||
.PHONY: regenerate-bindings
|
||||
regenerate-bindings:
|
||||
@make clean-bindings builtins
|
||||
@make bindings -j$(CPU_COUNT)
|
||||
|
||||
.PHONY: setup
|
||||
setup: require
|
||||
# make init-submodules
|
||||
# cd test && $(NPM_CLIENT) install --production
|
||||
# cd packages/bun-types && $(NPM_CLIENT) install --production
|
||||
# make vendor-without-check builtins identifier-cache clean-bindings
|
||||
make bindings -j$(CPU_COUNT)
|
||||
@echo ""
|
||||
@echo "Development environment setup complete"
|
||||
@echo "Run \`make dev\` to build \`bun-debug\`"
|
||||
@echo ""
|
||||
|
||||
@@ -130,7 +130,7 @@ bun upgrade --canary
|
||||
|
||||
## Contributing
|
||||
|
||||
Refer to the [Project > Contributing](https://bun.sh/docs/project/developing) guide to start contributing to Bun.
|
||||
Refer to the [Project > Development](https://bun.sh/docs/project/development) guide to start contributing to Bun.
|
||||
|
||||
## License
|
||||
|
||||
|
||||
@@ -186,7 +186,7 @@ export default {
|
||||
page("project/benchmarking", "Benchmarking", {
|
||||
description: `Bun is designed for performance. Learn how to benchmark Bun yourself.`,
|
||||
}),
|
||||
page("project/developing", "Development", {
|
||||
page("project/development", "Development", {
|
||||
description: "Learn how to contribute to Bun and get your local development environment up and running.",
|
||||
}),
|
||||
page("project/licensing", "License", {
|
||||
|
||||
@@ -1,10 +1,191 @@
|
||||
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:
|
||||
|
||||
{% codetabs %}
|
||||
|
||||
```bash#macOS (Homebrew)
|
||||
$ brew install llvm@15
|
||||
```
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
```bash#Arch
|
||||
$ sudo pacman -S llvm clang lld
|
||||
```
|
||||
|
||||
{% /codetabs %}
|
||||
|
||||
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).
|
||||
|
||||
Make sure LLVM 15 is in your path:
|
||||
|
||||
```
|
||||
$ which clang-15
|
||||
```
|
||||
|
||||
If not, run this to manually link it:
|
||||
|
||||
{% 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"
|
||||
```
|
||||
|
||||
{% /codetabs %}
|
||||
|
||||
## Install Dependencies
|
||||
|
||||
Using your system's package manager, install the rest of Bun's dependencies:
|
||||
|
||||
{% codetabs %}
|
||||
|
||||
```bash#macOS (Homebrew)
|
||||
$ brew install automake ccache cmake coreutils esbuild gnu-sed go libiconv libtool ninja pkg-config rust
|
||||
```
|
||||
|
||||
```bash#Ubuntu/Debian
|
||||
$ sudo apt install cargo ccache cmake esbuild git golang libtool ninja-build pkg-config rustc
|
||||
```
|
||||
|
||||
```bash#Arch
|
||||
$ pacman -S base-devel ccache cmake esbuild git go libiconv libtool make ninja pkg-config python rust sed unzip
|
||||
```
|
||||
|
||||
{% /codetabs %}
|
||||
|
||||
In addition to this, you will need either `bun` or `npm` installed to install the package.json dependencies.
|
||||
|
||||
## Install Zig
|
||||
|
||||
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).
|
||||
|
||||
```
|
||||
$ bun install -g @oven/zig
|
||||
$ zigup master
|
||||
```
|
||||
|
||||
## Building
|
||||
|
||||
After cloning the repository, prepare bun to be built:
|
||||
|
||||
```bash
|
||||
$ make setup
|
||||
```
|
||||
|
||||
Then to build Bun:
|
||||
|
||||
```bash
|
||||
$ make dev
|
||||
```
|
||||
|
||||
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
|
||||
$ 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/*` or switch branches, run this:
|
||||
|
||||
```bash
|
||||
$ 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.
|
||||
|
||||
The [./src/bun.js/bindings/headers.h](https://github.com/oven-sh/bun/blob/main/src/bun.js/bindings/headers.h) file has bindings to & from Zig <> C++ code. This file is generated by running the following:
|
||||
|
||||
```bash
|
||||
$ make headers
|
||||
```
|
||||
|
||||
This ensures that the types for Zig and the types for C++ match up correctly, by using comptime reflection over functions exported/imported.
|
||||
|
||||
TypeScript files that end with `*.classes.ts` are another code generation script. They generate C++ boilerplate for classes implemented in Zig. The generated code lives in:
|
||||
|
||||
- [src/bun.js/bindings/ZigGeneratedClasses.cpp](https://github.com/oven-sh/bun/tree/main/src/bun.js/bindings/ZigGeneratedClasses.cpp)
|
||||
- [src/bun.js/bindings/ZigGeneratedClasses.h](https://github.com/oven-sh/bun/tree/main/src/bun.js/bindings/ZigGeneratedClasses.h)
|
||||
- [src/bun.js/bindings/generated_classes.zig](https://github.com/oven-sh/bun/tree/main/src/bun.js/bindings/generated_classes.zig)
|
||||
To generate the code, run:
|
||||
|
||||
```bash
|
||||
$ make codegen
|
||||
```
|
||||
|
||||
Lastly, we also have a [code generation script](src/bun.js/scripts/generate-jssink.js) for our native stream implementations.
|
||||
To run that, run:
|
||||
|
||||
```bash
|
||||
$ make generate-sink
|
||||
```
|
||||
|
||||
You probably won't need to run that one much.
|
||||
|
||||
## Modifying ESM core modules
|
||||
|
||||
Certain modules like `node:fs`, `node:path`, `node:stream`, and `bun:sqlite` are implemented in JavaScript. These live in `src/bun.js/*.exports.js` files.
|
||||
|
||||
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.
|
||||
|
||||
## Release build
|
||||
|
||||
To build a release build of Bun, run:
|
||||
|
||||
```bash
|
||||
make release-bindings -j12
|
||||
make release
|
||||
```
|
||||
|
||||
The binary will be located at `packages/bun-{platform}-{arch}/bun`.
|
||||
|
||||
## Valgrind
|
||||
|
||||
On Linux, valgrind can help find memory issues.
|
||||
|
||||
Keep in mind:
|
||||
|
||||
- JavaScriptCore doesn't support valgrind. It will report spurious errors.
|
||||
- Valgrind is slow
|
||||
- Mimalloc will sometimes cause spurious errors when debug build is enabled
|
||||
|
||||
You'll need a very recent version of Valgrind due to DWARF 5 debug symbols. You may need to manually compile Valgrind instead of using it from your Linux package manager.
|
||||
|
||||
`--fair-sched=try` is necessary if running multithreaded code in Bun (such as the bundler). Otherwise it will hang.
|
||||
|
||||
```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.
|
||||
|
||||
@@ -72,76 +253,7 @@ $ make dev
|
||||
$ bun-debug
|
||||
```
|
||||
|
||||
## MacOS
|
||||
|
||||
Install LLVM 15 and `homebrew` dependencies:
|
||||
|
||||
```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
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
$ zigup 0.11.0-dev.1783+436e99d13
|
||||
```
|
||||
|
||||
### Building
|
||||
|
||||
To install and build dependencies:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
To compile the C++ bindings:
|
||||
|
||||
```bash
|
||||
# without -j this will take 30+ minutes
|
||||
$ make bindings -j12
|
||||
```
|
||||
|
||||
<!-- 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. -->
|
||||
|
||||
<!-- You can still work with the generated binary locally at `packages/debug-bun-*/bun-debug` even if the code signing fails. -->
|
||||
|
||||
### Testing
|
||||
|
||||
To verify the build worked, lets print the version number on the development build of Bun.
|
||||
|
||||
```bash
|
||||
$ packages/debug-bun-darwin-*/bun-debug --version
|
||||
bun 0.x.y__dev
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
### Troubleshooting
|
||||
## Troubleshooting
|
||||
|
||||
If you see an error when compiling `libarchive`, run this:
|
||||
|
||||
@@ -154,73 +266,3 @@ If you see an error about missing files on `zig build obj`, make sure you built
|
||||
```bash
|
||||
$ make headers
|
||||
```
|
||||
|
||||
## JavaScript builtins
|
||||
|
||||
When you change anything in `src/bun.js/builtins/js/*`, run this:
|
||||
|
||||
```bash
|
||||
$ make clean-bindings generate-builtins && make bindings -j12
|
||||
```
|
||||
|
||||
That inlines the JavaScript code into C++ headers using the same builtins generator script that Safari uses.
|
||||
|
||||
## Code generation scripts
|
||||
|
||||
Bun leverages a lot of code generation scripts.
|
||||
|
||||
The [./src/bun.js/bindings/headers.h](https://github.com/oven-sh/bun/blob/main/src/bun.js/bindings/headers.h) file has bindings to & from Zig <> C++ code. This file is generated by running the following:
|
||||
|
||||
```bash
|
||||
$ make headers
|
||||
```
|
||||
|
||||
This ensures that the types for Zig and the types for C++ match up correctly, by using comptime reflection over functions exported/imported.
|
||||
|
||||
TypeScript files that end with `*.classes.ts` are another code generation script. They generate C++ boilerplate for classes implemented in Zig. The generated code lives in:
|
||||
|
||||
- [src/bun.js/bindings/ZigGeneratedClasses.cpp](https://github.com/oven-sh/bun/tree/main/src/bun.js/bindings/ZigGeneratedClasses.cpp)
|
||||
- [src/bun.js/bindings/ZigGeneratedClasses.h](https://github.com/oven-sh/bun/tree/main/src/bun.js/bindings/ZigGeneratedClasses.h)
|
||||
- [src/bun.js/bindings/generated_classes.zig](https://github.com/oven-sh/bun/tree/main/src/bun.js/bindings/generated_classes.zig)
|
||||
To generate the code, run:
|
||||
|
||||
```bash
|
||||
$ make codegen
|
||||
```
|
||||
|
||||
Lastly, we also have a [code generation script](src/bun.js/scripts/generate-jssink.js) for our native stream implementations.
|
||||
To run that, run:
|
||||
|
||||
```bash
|
||||
$ make generate-sink
|
||||
```
|
||||
|
||||
You probably won't need to run that one much.
|
||||
|
||||
## Modifying ESM core modules
|
||||
|
||||
Certain modules like `node:fs`, `node:path`, `node:stream`, and `bun:sqlite` are implemented in JavaScript. These live in `src/bun.js/*.exports.js` files.
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
## Valgrind
|
||||
|
||||
On Linux, valgrind can help find memory issues.
|
||||
|
||||
Keep in mind:
|
||||
|
||||
- JavaScriptCore doesn't support valgrind. It will report spurious errors.
|
||||
- Valgrind is slow
|
||||
- Mimalloc will sometimes cause spurious errors when debug build is enabled
|
||||
|
||||
You'll need a very recent version of Valgrind due to DWARF 5 debug symbols. You may need to manually compile Valgrind instead of using it from your Linux package manager.
|
||||
|
||||
`--fair-sched=try` is necessary if running multithreaded code in Bun (such as the bundler). Otherwise it will hang.
|
||||
|
||||
```bash
|
||||
valgrind --fair-sched=try --track-origins=yes bun-debug <args>
|
||||
```
|
||||
@@ -1,5 +1,6 @@
|
||||
{
|
||||
"dependencies": {
|
||||
"esbuild": "^0.17.15",
|
||||
"eslint": "^8.20.0",
|
||||
"eslint-config-prettier": "^8.5.0",
|
||||
"mitata": "^0.1.3",
|
||||
|
||||
Reference in New Issue
Block a user