diff options
Diffstat (limited to 'docs/project')
| -rw-r--r-- | docs/project/configuration.md | 182 | ||||
| -rw-r--r-- | docs/project/developing.md | 227 | ||||
| -rw-r--r-- | docs/project/licensing.md | 207 | ||||
| -rw-r--r-- | docs/project/profiling.md | 193 | ||||
| -rw-r--r-- | docs/project/roadmap.md | 87 |
5 files changed, 896 insertions, 0 deletions
diff --git a/docs/project/configuration.md b/docs/project/configuration.md new file mode 100644 index 000000000..08eeb13ca --- /dev/null +++ b/docs/project/configuration.md @@ -0,0 +1,182 @@ +## Environment variables + +- `GOMAXPROCS`: For `bun bun`, this sets the maximum number of threads to use. If you’re experiencing an issue with `bun bun`, try setting `GOMAXPROCS=1` to force Bun to run single-threaded +- `DISABLE_BUN_ANALYTICS=1` this disables Bun's analytics. Bun records bundle timings (so we can answer with data, "is Bun getting faster?") and feature usage (e.g., "are people actually using macros?"). The request body size is about 60 bytes, so it’s not a lot of data +- `TMPDIR`: Before `bun bun` completes, it stores the new `.bun` in `$TMPDIR`. If unset, `TMPDIR` defaults to the platform-specific temporary directory (on Linux, `/tmp` and on macOS `/private/tmp`) + +## `bunfig.toml` + +Bun's configuration file is called `bunfig.toml`. Configuring with `bunfig.toml` is optional. Bun aims to be zero-configuration out of the box, but is also highly configurable for advanced use cases.. + +Your `bunfig.toml` should live in your project root alongside `package.json`. You can also create a global configuration file at the following paths: + +- `$HOME/.bunfig.toml` +- `$XDG_CONFIG_HOME/.bunfig.toml` + +If both a global and local `bunfig` are detected, the results are shallow-merged, with local overridding global. CLI flags will override `bunfig` setting where applicable. + +## Configure `bun install` + +Package management is a complex issue; to support a range of use cases, the behavior of `bun install` can be configured in [`bunfig.toml`](/docs/project/configuration). + +### Default flags + +The following settings modify the core behavior of Bun's package management commands. **The default values are shown below.** + +```toml +[install] + +# whether to install optionalDependencies +optional = true + +# whether to install devDependencies +dev = true + +# whether to install devDependencies +peer = false + +# equivalent to `--production` flag +production = false + +# equivalent to `--dry-run` flag +dryRun = false +``` + +### Registries + +The default registry is `https://registry.npmjs.org/`. This can be globally configured in `bunfig.toml`: + +```toml +[install] +# set default registry as a string +registry = "https://registry.npmjs.org" +# set a token +registry = { url = "https://registry.npmjs.org", token = "123456" } +# set a username/password +registry = "https://username:password@registry.npmjs.org" +``` + +To configure scoped registries: + +```toml +[install.scopes] +# registry as string +myorg1 = "https://username:password@registry.myorg.com/" + +# registry with username/password +# you can reference environment variables +myorg12 = { username = "myusername", password = "$NPM_PASS", url = "https://registry.myorg.com/" } + +# registry with token +myorg3 = { token = "$npm_token", url = "https://registry.myorg.com/" } +``` + +### Cache + +To configure caching behavior: + +```toml +[install] +# where `bun install --global` installs packages +globalDir = "~/.bun/install/global" + +# where globally-installed package bins are linked +globalBinDir = "~/.bun/bin" + +[install.cache] +# the directory to use for the cache +dir = "~/.bun/install/cache" + +# when true, don't load from the global cache. +# Bun may still write to node_modules/.cache +disable = false + +# when true, always resolve the latest versions from the registry +disableManifest = false +``` + +### Lockfile + +To configure lockfile behavior: + +```toml {% disabled %} +[install.lockfile] + +# path to read bun.lockb from +path = "bun.lockb" + +# path to save bun.lockb to +savePath = "bun.lockb" + +# whether to save the lockfile to disk +save = true + +# whether to save a non-Bun lockfile alongside bun.lockb +# only "yarn" is supported +print = "yarn" +``` + +## Configure `bun dev` + +Here is an example: + +```toml +# Set a default framework to use +# By default, Bun will look for an npm package like `bun-framework-${framework}`, followed by `${framework}` +framework = "next" +logLevel = "debug" + +# publicDir = "public" +# external = ["jquery"] + +[macros] +# Remap any import like this: +# import {graphql} from 'react-relay'; +# To: +# import {graphql} from 'macro:bun-macro-relay'; +react-relay = { "graphql" = "bun-macro-relay" } + +[bundle] +saveTo = "node_modules.bun" +# Don't need this if `framework` is set, but showing it here as an example anyway +entryPoints = ["./app/index.ts"] + +[bundle.packages] +# If you're bundling packages that do not actually live in a `node_modules` folder or do not have the full package name in the file path, you can pass this to bundle them anyway +"@bigapp/design-system" = true + +[dev] +# Change the default port from 3000 to 5000 +# Also inherited by Bun.serve +port = 5000 + +[define] +# Replace any usage of "process.env.bagel" with the string `lox`. +# The values are parsed as JSON, except single-quoted strings are supported and `'undefined'` becomes `undefined` in JS. +# This will probably change in a future release to be just regular TOML instead. It is a holdover from the CLI argument parsing. +"process.env.bagel" = "'lox'" + +[loaders] +# When loading a .bagel file, run the JS parser +".bagel" = "js" + +[debug] +# When navigating to a blob: or src: link, open the file in your editor +# If not, it tries $EDITOR or $VISUAL +# If that still fails, it will try Visual Studio Code, then Sublime Text, then a few others +# This is used by Bun.openInEditor() +editor = "code" + +# List of editors: +# - "subl", "sublime" +# - "vscode", "code" +# - "textmate", "mate" +# - "idea" +# - "webstorm" +# - "nvim", "neovim" +# - "vim","vi" +# - "emacs" +# - "atom" +# If you pass it a file path, it will open with the file path instead +# It will recognize non-GUI editors, but I don't think it will work yet +``` diff --git a/docs/project/developing.md b/docs/project/developing.md new file mode 100644 index 000000000..e532a3d0a --- /dev/null +++ b/docs/project/developing.md @@ -0,0 +1,227 @@ +{% callout %} +**⚠️ Warning** — Bun currently needs about 22 GB of RAM to compile. If you have less than that, it will be difficult or impossible to building Bun locally. We're working on improving this. +{% /callout %} + +Configuring a development environment for Bun usually takes 30-90 minutes depending on your operating system. + +## Linux/Windows + +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, `vscode-zig`, and more pre-installed on an instance of Ubuntu. + +{% image src="https://user-images.githubusercontent.com/709451/147319227-6446589c-a4d9-480d-bd5b-43037a9e56fd.png" /%} + +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. + +### VSCode + +If you're using VSCode, you'll need to have the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension installed. + +To get started, open VS Code in the `bun` repository. The first time you try to open the dev container, the extension will automatically build it for you, based on [`Dockerfile.devcontainer`](Dockerfile.devcontainer). + +To open the dev container, open the command palette (`Ctrl` + `Shift` + `P`) and run: `Dev Containers: Reopen in Container`. To later rebuild it (only needed when the devcontainer itself changes, not the Bun code), run: `Dev Containers: Rebuild and Reopen in Container`. + +### Other editors and CLI + +If you're using another editor or want to manually control the dev container from the command line or a script, you'll need to install the [Dev Container CLI](https://www.npmjs.com/package/@devcontainers/cli): `npm install -g @devcontainers/cli`. + +To create and start the dev container, in the `bun` repository, locally run: + +```bash +# `make devcontainer-<command>` should be equivalent +# to `devcontainer <command>`, it just sets the architecture +# so if you're on ARM64, it'll do the right thing +$ make devcontainer-up +``` + +To just build the dev container image, run: + +```bash +$ make devcontainer-build +``` + +To start a shell inside the container, run: + +```bash +$ make devcontainer-sh + +# if it attaches to the container non-interactively, +# instead use the regular docker exec command: +$ docker exec -it <container-name/id> zsh +``` + +### Cloning + +You will then need to clone the GitHub repository inside that container. + +```bash +# First time setup +$ gh auth login # if it fails to open a browser, use Personal Access Token instead +$ gh repo clone oven-sh/bun . -- --depth=1 --progress -j8 +``` + +### Building + +```bash +# Compile Bun dependencies (zig is already compiled) +$ make devcontainer + +# It initializes and updates all submodules except WebKit, because WebKit +# takes a while and it's already compiled for you. To do it manually, use: +$ git -c submodule."src/bun.js/WebKit".update=none submodule update --init --recursive --depth=1 --progress + +# Build Bun for development +$ make dev + +# Run Bun +$ 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`](<[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.1393+38eebf3c4 +``` + +### 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 webcrypto-debug +``` + +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 + +If you see an error when compiling `libarchive`, run this: + +```bash +$ brew install pkg-config +``` + +If you see an error about missing files on `zig build obj`, make sure you built the headers. + +```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](src/bun.js/bindings/ZigGeneratedClasses.cpp) +- [src/bun.js/bindings/ZigGeneratedClasses.h](src/bun.js/bindings/ZigGeneratedClasses.h) +- [src/bun.js/bindings/generated_classes.zig](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. + +## `vscode-zig` + +{% callout %} +**Note** — This is automatically installed on the devcontainer. +{% /callout %} + +We maintain a fork of the `vscode-zig` extension that adds a `Run test` and a `Debug test` button into the dev environment. To install it: + +```bash +$ curl -L https://github.com/Jarred-Sumner/vscode-zig/releases/download/fork-v1/zig-0.2.5.vsix > vscode-zig.vsix +$ code --install-extension vscode-zig.vsix +``` + +{% image src="https://pbs.twimg.com/media/FBZsKHlUcAYDzm5?format=jpg&name=large" href="https://github.com/jarred-sumner/vscode-zig" /%} + +## 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 22 GB of RAM to compile. diff --git a/docs/project/licensing.md b/docs/project/licensing.md new file mode 100644 index 000000000..ef88d0674 --- /dev/null +++ b/docs/project/licensing.md @@ -0,0 +1,207 @@ +Bun itself is MIT-licensed. + +## JavaScriptCore + +Bun statically links JavaScriptCore (and WebKit) which is LGPL-2 licensed. WebCore files from WebKit are also licensed under LGPL2. Per LGPL2: + +> (1) If you statically link against an LGPL’d library, you must also provide your application in an object (not necessarily source) format, so that a user has the opportunity to modify the library and relink the application. + +You can find the patched version of WebKit used by Bun here: <https://github.com/oven-sh/webkit>. If you would like to relink Bun with changes: + +- `git submodule update --init --recursive` +- `make jsc` +- `zig build` + +This compiles JavaScriptCore, compiles Bun’s `.cpp` bindings for JavaScriptCore (which are the object files using JavaScriptCore) and outputs a new `bun` binary with your changes. + +## Linked libraries + +Bun statically links these libraries: + +{% table %} + +- Library +- License + +--- + +- [`boringssl`](https://boringssl.googlesource.com/boringssl/) +- [several licenses](https://boringssl.googlesource.com/boringssl/+/refs/heads/master/LICENSE) + +--- + +- [`libarchive`](https://github.com/libarchive/libarchive) +- [several licenses](https://github.com/libarchive/libarchive/blob/master/COPYING) + +--- + +- [`lol-html`](https://github.com/cloudflare/lol-html/tree/master/c-api) +- BSD 3-Clause + +--- + +- [`mimalloc`](https://github.com/microsoft/mimalloc) +- MIT + +--- + +- [`picohttp`](https://github.com/h2o/picohttpparser) +- dual-licensed under the Perl License or the MIT License + +--- + +- [`simdutf`](https://github.com/simdutf/simdutf) +- Apache 2.0 + +--- + +- [`tinycc`](https://github.com/tinycc/tinycc) +- LGPL v2.1 + +--- + +- [`uSockets`](https://github.com/uNetworking/uSockets) +- Apache 2.0 + +--- + +- [`zlib-cloudflare`](https://github.com/cloudflare/zlib) +- zlib + +--- + +- [`c-ares`](https://github.com/c-ares/c-ares) +- MIT licensed + +--- + +- [`libicu`](https://github.com/unicode-org/icu) 72 +- [license here](https://github.com/unicode-org/icu/blob/main/icu4c/LICENSE) + +--- + +- A fork of [`uWebsockets`](https://github.com/jarred-sumner/uwebsockets) +- Apache 2.0 licensed + +{% /table %} + +## Polyfills + +For compatibility reasons, the following packages are embedded into Bun's binary and injected if imported. + +{% table %} + +- Package +- License + +--- + +- [`assert`](https://npmjs.com/package/assert) +- MIT + +--- + +- [`browserify-zlib`](https://npmjs.com/package/browserify-zlib) +- MIT + +--- + +- [`buffer`](https://npmjs.com/package/buffer) +- MIT + +--- + +- [`constants-browserify`](https://npmjs.com/package/constants-browserify) +- MIT + +--- + +- [`crypto-browserify`](https://npmjs.com/package/crypto-browserify) +- MIT + +--- + +- [`domain-browser`](https://npmjs.com/package/domain-browser) +- MIT + +--- + +- [`events`](https://npmjs.com/package/events) +- MIT + +--- + +- [`https-browserify`](https://npmjs.com/package/https-browserify) +- MIT + +--- + +- [`os-browserify`](https://npmjs.com/package/os-browserify) +- MIT + +--- + +- [`path-browserify`](https://npmjs.com/package/path-browserify) +- MIT + +--- + +- [`process`](https://npmjs.com/package/process) +- MIT + +--- + +- [`punycode`](https://npmjs.com/package/punycode) +- MIT + +--- + +- [`querystring-es3`](https://npmjs.com/package/querystring-es3) +- MIT + +--- + +- [`stream-browserify`](https://npmjs.com/package/stream-browserify) +- MIT + +--- + +- [`stream-http`](https://npmjs.com/package/stream-http) +- MIT + +--- + +- [`string_decoder`](https://npmjs.com/package/string_decoder) +- MIT + +--- + +- [`timers-browserify`](https://npmjs.com/package/timers-browserify) +- MIT + +--- + +- [`tty-browserify`](https://npmjs.com/package/tty-browserify) +- MIT + +--- + +- [`url`](https://npmjs.com/package/url) +- MIT + +--- + +- [`util`](https://npmjs.com/package/util) +- MIT + +--- + +- [`vm-browserify`](https://npmjs.com/package/vm-browserify) +- MIT + +{% /table %} + +## Additional credits + +- Bun's JS transpiler, CSS lexer, and Node.js module resolver source code is a Zig port of [@evanw](https://github.com/evanw)’s [esbuild](https://github.com/evanw/esbuild) project. +- Credit to [@kipply](https://github.com/kipply) for the name "Bun"! diff --git a/docs/project/profiling.md b/docs/project/profiling.md new file mode 100644 index 000000000..d734588b2 --- /dev/null +++ b/docs/project/profiling.md @@ -0,0 +1,193 @@ +To precisely measure time, Bun offers two runtime APIs functions: + +1. The web-standard [`performance.now()`](https://developer.mozilla.org/en-US/docs/Web/API/Performance/now) function +2. `Bun.nanoseconds()` which is similar to `performance.now()` except it returns the current time since the application started in nanoseconds. You can use `performance.timeOrigin` to convert this to a Unix timestamp. + +## Benchmarking `Bun.serve` + +You will need an HTTP client which is at least as fast as `Bun.serve()`. + +That means popular Node.js-based benchmarking tools like **autocannon is not fast enough**. + +Recommended HTTP clients: + +- [`bombardier`](https://github.com/codesenberg/bombardier) +- [`oha`](https://github.com/hatoo/oha) +- [`http_load_test`](https://github.com/uNetworking/uSockets/blob/master/examples/http_load_test.c) + +## Measuring memory usage + +Bun has two heaps. One heap is for the JavaScript runtime and the other heap is for everything else. + +### JavaScript heap stats + +The `bun:jsc` module exposes a few functions for measuring memory usage: + +```ts +import { heapStats } from "bun:jsc"; +console.log(heapStats()); + +// will show something like this: +{ + heapSize: 1657575, + heapCapacity: 2872775, + extraMemorySize: 598199, + objectCount: 13790, + protectedObjectCount: 62, + globalObjectCount: 1, + protectedGlobalObjectCount: 1, + // A count of every object type in the heap + objectTypeCounts: { + CallbackObject: 25, + FunctionExecutable: 2078, + AsyncGeneratorFunction: 2, + 'RegExp String Iterator': 1, + FunctionCodeBlock: 188, + ModuleProgramExecutable: 13, + String: 1, + UnlinkedModuleProgramCodeBlock: 13, + JSON: 1, + AsyncGenerator: 1, + Symbol: 1, + GetterSetter: 68, + ImportMeta: 10, + DOMAttributeGetterSetter: 1, + UnlinkedFunctionCodeBlock: 174, + RegExp: 52, + ModuleLoader: 1, + Intl: 1, + WeakMap: 4, + Generator: 2, + PropertyTable: 95, + 'Array Iterator': 1, + JSLexicalEnvironment: 75, + UnlinkedFunctionExecutable: 2067, + WeakSet: 1, + console: 1, + Map: 23, + SparseArrayValueMap: 14, + StructureChain: 19, + Set: 18, + 'String Iterator': 1, + FunctionRareData: 3, + JSGlobalLexicalEnvironment: 1, + Object: 481, + BigInt: 2, + StructureRareData: 55, + Array: 179, + AbortController: 2, + ModuleNamespaceObject: 11, + ShadowRealm: 1, + 'Immutable Butterfly': 103, + Primordials: 1, + 'Set Iterator': 1, + JSProxy: 1, + AsyncFromSyncIterator: 1, + ModuleRecord: 13, + FinalizationRegistry: 1, + AsyncIterator: 1, + InternalPromise: 22, + Iterator: 1, + CustomGetterSetter: 65, + Promise: 19, + WeakRef: 1, + InternalPromisePrototype: 1, + Function: 2381, + AsyncFunction: 2, + GlobalObject: 1, + ArrayBuffer: 2, + Boolean: 1, + Math: 1, + CallbackConstructor: 1, + Error: 2, + JSModuleEnvironment: 13, + WebAssembly: 1, + HashMapBucket: 300, + Callee: 3, + symbol: 37, + string: 2484, + Performance: 1, + ModuleProgramCodeBlock: 12, + JSSourceCode: 13, + JSPropertyNameEnumerator: 3, + NativeExecutable: 290, + Number: 1, + Structure: 1550, + SymbolTable: 108, + GeneratorFunction: 2, + 'Map Iterator': 1 + }, + protectedObjectTypeCounts: { + CallbackConstructor: 1, + BigInt: 1, + RegExp: 2, + GlobalObject: 1, + UnlinkedModuleProgramCodeBlock: 13, + HashMapBucket: 2, + Structure: 41, + JSPropertyNameEnumerator: 1 + } +} +``` + +JavaScript is a garbage-collected language, not reference counted. It's normal and correct for objects to not be freed immediately in all cases, though it's not normal for objects to never be freed. + +You can force garbage collection to run manually by calling: + +```js +const synchronously = true; +Bun.gc(synchronously); +``` + +### JavaScript heap snapshot + +Heap snapshots let you inspect what objects are not being freed. You can use the `bun:jsc` module to take a heap snapshot and then view it with Safari or WebKit GTK developer tools. + +{% image alt="image" src="https://user-images.githubusercontent.com/709451/204429337-b0d8935f-3509-4071-b991-217794d1fb27.png" /%} + +To generate a heap snapshot: + +```ts +import { generateHeapSnapshot } from "bun"; + +const snapshot = generateHeapSnapshot(); +await Bun.write("heap.json", JSON.stringify(snapshot, null, 2)); +``` + +To view the snapshot, open the `heap.json` file in Safari's Developer Tools (or WebKit GTK) + +1. Open the Developer Tools +2. Click "Timeline" +3. Click "JavaScript Allocations" in the menu on the left. It might not be visible until you click the pencil icon to show all the timelines +4. Click "Import" and select your heap snapshot JSON + + + +### Native heap stats + +Bun uses mimalloc for the other heap. To report a summary of non-JavaScript memory usage, set the `MIMALLOC_SHOW_STATS=1` environment variable. and stats will print on exit. + +```js +MIMALLOC_SHOW_STATS=1 bun script.js + +# will show something like this: +heap stats: peak total freed current unit count + reserved: 64.0 MiB 64.0 MiB 0 64.0 MiB not all freed! + committed: 64.0 MiB 64.0 MiB 0 64.0 MiB not all freed! + reset: 0 0 0 0 ok + touched: 128.5 KiB 128.5 KiB 5.4 MiB -5.3 MiB ok + segments: 1 1 0 1 not all freed! +-abandoned: 0 0 0 0 ok + -cached: 0 0 0 0 ok + pages: 0 0 53 -53 ok +-abandoned: 0 0 0 0 ok + -extended: 0 + -noretire: 0 + mmaps: 0 + commits: 0 + threads: 0 0 0 0 ok + searches: 0.0 avg +numa nodes: 1 + elapsed: 0.068 s + process: user: 0.061 s, system: 0.014 s, faults: 0, rss: 57.4 MiB, commit: 64.0 MiB +``` diff --git a/docs/project/roadmap.md b/docs/project/roadmap.md new file mode 100644 index 000000000..7c5c28cf6 --- /dev/null +++ b/docs/project/roadmap.md @@ -0,0 +1,87 @@ +Bun is a project with an incredibly large scope and is still in its early days. Long-term, Bun aims to provide an all-in-one tookit to replace the complex, fragmented toolchains common today: Node.js, Jest, Webpack, esbuild, Babel, yarn, PostCSS, etc. + +Refer to [Bun's Roadmap](https://github.com/oven-sh/bun/issues/159) on GitHub to learn more about the project's long-term plans and priorities. + +<!-- +{% table %} + +- Feature +- Implemented in + +--- + +- Web Streams with HTMLRewriter +- Bun.js + +--- + +- Source Maps (unbundled is supported) +- JS Bundler + +--- + +- Source Maps +- CSS + +--- + +- JavaScript Minifier +- JS Transpiler + +--- + +- CSS Minifier +- CSS + +--- + +- CSS Parser (it only bundles) +- CSS + +--- + +- Tree-shaking +- JavaScript + +--- + +- Tree-shaking +- CSS + +--- + +- [TypeScript Decorators](https://www.typescriptlang.org/docs/handbook/decorators.html) +- TS Transpiler + +--- + +- `@jsxPragma` comments +- JS Transpiler + +--- + +- Sharing `.bun` files +- Bun + +--- + +- Dates & timestamps +- TOML parser + +--- + +- [Hash components for Fast Refresh](https://github.com/oven-sh/bun/issues/18) +- JSX Transpiler + +{% /table %} --> + +<!-- ## Limitations & intended usage + +Today, Bun is mostly focused on Bun.js: the JavaScript runtime. + +While you could use Bun's bundler & transpiler separately to build for browsers or node, Bun doesn't have a minifier or support tree-shaking yet. For production browser builds, you probably should use a tool like esbuild or swc. + +## Upcoming breaking changes + +- Bun's CLI flags will change to better support Bun as a JavaScript runtime. They were chosen when Bun was just a frontend development tool. +- Bun's bundling format will change to accommodate production browser bundles and on-demand production bundling --> |