More instructions

1 files changed, 54 insertions, 0 deletions

diff --git a/README.md b/README.md
index b5a12fc81..16e898d66 100644
--- a/README.md
+++ b/README.md
@@ -5119,6 +5119,60 @@ It should print `bun 0.4.0__dev` or something similar.
 
 You will want to add `packages/debug-bun-darwin-arm64/` or `packages/debug-bun-darwin-x64/` to your `$PATH` so you can run `bun-debug` from anywhere.
 
+#### JavaScript builtins
+
+When you change anything in `src/bun.js/builtins/js/*`, you need to 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
+
+[./src/bun.js/bindings/headers.h](./src/bun.js/bindings/headers.h) 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
+
+How to modify ESM modules like `node:fs`, `node:path`, `node:stream`, `bun:sqlite`:
+
+ESM modules implemented in JavaScript live in `*.exports.js` within src/bun.js.
+
+While bun is in beta, you can modify them at runtime in release builds via the environment variable `BUN_OVERRIDE_MODULE_PATH`.
+
+This will look at a folder for a file with the same name as in src/bun.js/\*.exports.js and if it exists, it will use that instead. This is useful for testing changes to the ESM modules without needing to compile Bun.
+
 #### Troubleshooting (macOS)
 
 If you see an error when compiling `libarchive`, run this: