Contributing to the Compiler

How to work on the compiler, and what a good change looks like.

vlatest

Testing your change

The test runner is a CLI subcommand rather than a build target:

pickle-cli test path/to/module.pkl

test fn items in a module are collected and run. The generated harness is built in, and expect(...).toBe(...) and friends are only available inside a test fn: they are a compile-time construct, not a function. See Writing and running tests.

An end-to-end program that exercises literals, strings, arithmetic, bitwise operators, every loop form, lists, maps, structs, classes with properties and named constructors, enums, match with a guard, options, casts, is, as?, and raw pointers in an unsafe block is the single most useful thing to run after a change.

Contribution checklist

  1. Add a failing case first. A language bug needs a test fn that fails before the fix does.
  2. Keep the phases separate. The checker must not print, and type checking must not generate code. If a construct needs both a check and a lowering, the two changes belong in different places.
  3. Add an error code when you add a diagnostic. A new diagnostic with no code renders as (uncoded). The catalogue and the page Diagnostics have to stay in step.
  4. Check the contract if you touch a serialized form. pickle lex and pickle irx are contracts that are expected to reproduce exactly, so changing either means re-checking the emitted output.
  5. Run the tests before you open a change. It is faster than finding out afterwards.