Skip to main content

Contributing

Raven is developed in the open at github.com/Unkindnesses/raven. Bug reports, docs fixes and patches are all welcome – as is just showing up on Discord and asking questions.

Getting set up​

The compiler is written in TypeScript. You'll need Node.js:

git clone https://github.com/Unkindnesses/raven
cd raven
npm install
npm run build
npm i -g .        # puts `raven` on your path
npm run watch     # live-rebuild as you edit the source

For the full test suite you'll also want wasm-tools, wasmtime and llvm (MacOS/Linux only) – on MacOS these are all a brew install away – plus npx playwright install chromium for the browser tests. Then:

npm test

A map of the compiler​

The pipeline mirrors the phases you see in raven build --time:

Load          read & parse sources
Definitions   resolve modules & definitions
Interpret     compile-time evaluation
Inference     abstract interpretation / type inference
Expansion     specialise & expand methods
Inlining      inline & optimise
Refcounts     insert reference counting
WASM          emit the binary

In the source tree:

  • src/frontend/ – lexing, parsing, formatting, lowering to IR, modules and packages.
  • src/middle/ – the interesting parts: abstract interpretation (abstract.ts), inlining, refcount insertion, the tracing interpreter.
  • src/backend/ – wasm emission and JS support code.
  • src/cli/ – the raven command: REPL, build, fmt, lsp.
  • common/ – the standard library, written in Raven.
  • test/ – vitest suites; test/language/ runs Raven programs end to end.

The standard library is often the easiest place to start contributing – it's plain Raven code, and missing pieces are well known.

Working on the docs​

The website (including these docs) lives in website/, a Docusaurus site:

cd website
npm install
npm start      # live-reloading dev server

Typo fixes and clarifications are the classic first PR.