diff --git a/AGENTS.md b/AGENTS.md index a1a7f2ce9c8..9b5974bc0ff 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -72,6 +72,15 @@ JS IR JavaScript Code ``` +### Platform-specific compiler modules + +The Dune `browser` profile builds the playground compiler. Platform-dependent +modules are stored below `platform/native/` and `platform/playground/` in their +owning compiler directory. Rules in that directory's `dune` file copy the +selected implementation into the build directory as an ordinary `.ml` module; +all other profiles select the native source. Generated module paths in errors +or stack traces therefore map back to one of those two source directories. + ### Key Directory Structure ``` diff --git a/CHANGELOG.md b/CHANGELOG.md index 76551587577..eee2c3a2e70 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -35,6 +35,7 @@ - Add the `-check-lam` compiler option, enable Lambda invariant checking in compiler tests, and remove build-profile-dependent checking. https://github.com/rescript-lang/rescript/pull/8534 - Replace `-bs-diagnose` with `-debug-ir` and make IR diagnostic artifacts deterministic, compilation-local, and easy to clean. https://github.com/rescript-lang/rescript/pull/8535 +- Replace CPPO-based browser conditionals with Dune-selected native and playground compiler implementations. https://github.com/rescript-lang/rescript/pull/8541 # 13.0.0-alpha.5 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2802119dedb..46078febc0b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -297,6 +297,20 @@ The "Playground bundle" is a JS version of the ReScript compiler; including all The ReScript source code is compiled with a tool called [JSOO (js_of_ocaml)](https://ocsigen.org/js_of_ocaml/latest/manual/overview), which uses OCaml bytecode to compile to JavaScript and is part of the bigger OCaml ecosystem. +### Platform-specific compiler modules + +Within `compiler/`, the Dune `browser` profile specifically means the +playground compiler. A few modules have implementations under +`platform/native/` and `platform/playground/`; mutually exclusive rules in the +owning `dune` file copy the appropriate implementation into the build directory +as an ordinary `.ml` module. Other profiles select the native implementation. + +Consequently, a generated filename such as `ext_platform_primitives.ml` may +appear in a compiler stack trace even though it is not present in the source +tree. Its source is the corresponding file below `platform/native/` or +`platform/playground/` in the same compiler directory. Keep both +implementations API-compatible when changing one of these modules. + ### Building the Bundle The entry point of the JSOO bundle is located in `compiler/jsoo/jsoo_playground_main.ml`, the compiler and its relevant runtime cmij files can be built via make: @@ -310,9 +324,9 @@ Note that building the cmijs is based on the dependencies defined in `packages/p After a successful compilation, you will find following files in your project: -- `playground/compiler.js` -> This is the ReScript compiler, which binds the ReScript API to the `window` object. -- `playground/packages/compiler-builtins` -> The compiler base cmij containing all the relevant core modules (`Js`, `Belt`, `Pervasives`, etc.) -- `playground/packages/*` -> Contains third party deps with cmij.js files (as defined in `packages/playground/rescript.json`) +- `packages/playground/compiler.js` -> This is the ReScript compiler, which binds the ReScript API to the `window` object. +- `packages/playground/packages/compiler-builtins` -> The compiler base cmij containing all the relevant core modules (`Js`, `Belt`, `Pervasives`, etc.) +- `packages/playground/packages/*` -> Contains third party deps with cmij.js files (as defined in `packages/playground/rescript.json`) You can now use the `compiler.js` file either directly by using a `