From 53bf855c1837153bbd6b305d656e803624a66939 Mon Sep 17 00:00:00 2001 From: Jarred Sumner Date: Tue, 14 May 2024 18:17:08 -0700 Subject: [PATCH] Update CONTRIBUTING.md --- CONTRIBUTING.md | 61 ++++++++++++++++++++++++------------------------- 1 file changed, 30 insertions(+), 31 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6b83ae316396e9..2cfa3f8e1303b9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -144,59 +144,58 @@ Advanced users can pass CMake flags to customize the build. 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. -If you use a different editor, make sure that you tell ZLS to use the automatically installed Zig compiler, which is located at `./.cache/zig/zig` (`zig.exe` on Windows). +If you use a different editor, make sure that you tell ZLS to use the automatically installed Zig compiler, which is located at `./.cache/zig/zig.exe`. The filename is `zig.exe` so that it works as expected on Windows, but it still works on macOS/Linux (it just has a surprising file extension). -## Code generation scripts +We recommend adding `./build` to your `$PATH` so that you can run `bun-debug` in your terminal: -{% callout %} +```sh +$ bun-debug +``` -**Note**: This section is outdated. The code generators are run automatically by ninja, instead of by `make`. +## Code generation scripts -{% /callout %} +Several code generation scripts are used during Bun's build process. These are run automatically when changes are made to certain files. -Bun leverages a lot of code generation scripts. +In particular, these are: -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: +- `./src/codegen/generate-jssink.ts` -- Generates `build/codegen/JSSink.cpp`, `build/codegen/JSSink.h` which implement various classes for interfacing with `ReadableStream`. This is internally how `FileSink`, `ArrayBufferSink`, `"type": "direct"` streams and other code related to streams works. +- `./src/codegen/generate-classes.ts` -- Generates `build/codegen/ZigGeneratedClasses*`, which generates Zig & C++ bindings for JavaScriptCore classes implemented in Zig. In `**/*.classes.ts` files, we define the interfaces for various classes, methods, prototypes, getters/setters etc which the code generator reads to generate boilerplate code implementing the JavaScript objects in C++ and wiring them up to Zig +- `./src/codegen/bundle-modules.ts` -- Bundles built-in modules like `node:fs`, `bun:ffi` into files we can include in the final binary. In development, these can be reloaded without rebuilding Zig (you still need to run `bun run build`, but it re-reads the transpiled files from disk afterwards). In release builds, these are embedded into the binary. +- `./src/codegen/bundle-functions.ts` -- Bundles globally-accessible functions implemented in JavaScript/TypeScript like `ReadableStream`, `WritableStream`, and a handful more. These are used similarly to the builtin modules, but the output more closely aligns with what WebKit/Safari does for Safari's built-in functions so that we can copy-paste the implementations from WebKit as a starting point. -```bash -$ make headers -``` +## Modifying ESM modules -This ensures that the types for Zig and the types for C++ match up correctly, by using comptime reflection over functions exported/imported. +Certain modules like `node:fs`, `node:stream`, `bun:sqlite`, and `ws` are implemented in JavaScript. These live in `src/js/{node,bun,thirdparty}` files and are pre-bundled using Bun. -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: +## Release build -- [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: +To compile a release build of Bun, run: ```bash -$ make codegen +$ bun run build:release ``` -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 -``` +The binary will be located at `./build-release/bun` and `./build-release/bun-profile`. -You probably won't need to run that one much. +### Download release build from pull requests -## Modifying ESM modules +To save you time spent building a release build locally, we provide a way to run release builds from pull requests. This is useful for testing changes before they are merged. -Certain modules like `node:fs`, `node:stream`, `bun:sqlite`, and `ws` are implemented in JavaScript. These live in `src/js/{node,bun,thirdparty}` files and are pre-bundled using Bun. In debug builds, Bun automatically loads these from the filesystem, wherever it was compiled, so no need to re-run `make dev`. +To run a release build from a pull request, you can use the `bun-pr` npm package: -## Release build +```sh +bunx bun-pr pr-number +bunx bun-pr branch/branch-name +bunx bun-pr "https://github.com/oven-sh/bun/pull/1234566" +``` -To build a release build of Bun, run: +This will download the release build from the pull request and add it to `$PATH` as `bun-${pr-number}`. You can then run the build with `bun-${pr-number}`. -```bash -$ bun run build:release +```sh +bun-1234566 --version ``` -The binary will be located at `./build-release/bun` and `./build-release/bun-profile`. +This works by downloading the release build from the GitHub Actions artifacts on the linked pull request. You may need the `gh` CLI installed to authenticate with GitHub. ## Valgrind