Building from Source

The downloaded compiler is all you need to write Refingere. To work on the compiler itself - or to use what only the repository has so far, such as --web - get it from source instead. This page sets that up; Working on the Compiler is where things are in it, and how to test a change.

1. Install the prerequisites

You need Git, to download the source, and Bun, the JavaScript runtime the compiler runs on. Most systems already have Git - check with git --version. To install Bun on macOS or Linux:

On Windows, in PowerShell:

Open a new terminal afterwards, so it picks up the bun command, and check it works with bun --version.

2. Get the source

Clone the repository, go into it, and install its dependencies:

Every command from here on runs inside Refingere-Language. To check that everything works, run the tests of one of the bundled example programs:

You should see the test pass:

3. The repository's command

The repository has its own command, the compiler written in TypeScript: bun run src/index.ts. It's what the compiler's development uses, and what compiles and runs the compiler written in Refingere, bootstrapping/ - which is the one you download (see below). It has what the downloaded command doesn't yet: --web, which serves a website - a folder with an index.html whose scripts import Refingere - rebuilding it on every save, or with --compile builds it into its dist/ (see Websites); and --compile --js, which writes a module with a loader and TypeScript declarations for JavaScript to call its @js definitions, or with --js=browser for a web page (see JavaScript and TypeScript).

Its output and most of its options are the downloaded command's, with a few differences:

  • The project is given on its own, as for the downloaded command, or as root="..." - relative to where the command runs. An option it doesn't take is an error.
  • --run and --test compile to WebAssembly unless --target=js says otherwise - and given together, run both @main and the tests.
  • --compile keeps what was compiled, named after the project - shop.wasm, or what out="..." says.
  • When the check finds errors, it still exits with status 0, so a pipeline should look for Found errors in its output.
  • It prints how long each step took, and runs the older tree-walking interpreter with --interpret.

bun link makes it a command, refingere, that works from any folder - in place of the downloaded one, if that's on your PATH too, whichever comes first:

4. Build the downloads

The downloaded compiler is bootstrapping/ compiled by itself to WebAssembly, with the standard library, the templates --new starts from, and Bun to run it, in one file for each platform. CI builds them from every commit to the main branch, next to the site; to build them yourself:

An executable starts with the standard library already done. While it's built, the compiler compiles a small program once, which leaves it holding the library lexed, parsed, analyzed, checked and lowered. Its memory and globals at that point are saved as a snapshot (src/compilerSnapshot.ts, src/6-compile-wasm/snapshot.ts), and every run starts from that snapshot, so only the program's own files are compiled. Each library file is kept with its hash, so a library that's been changed since is compiled again. The process's own context values - &env, &args, &clock and the rest - are left out of the snapshot, for each run to make its own.

See src/bootstrapExecutable.ts for what goes into one, and Working on the Compiler for testing a change to bootstrapping/.