|
| 1 | +# Contributing to Lazarus |
| 2 | + |
| 3 | +Thanks for wanting to contribute. This document covers how to get set up, how the project is structured, and what to keep in mind before opening a PR. |
| 4 | + |
| 5 | +## Getting started |
| 6 | + |
| 7 | +You need Lua 5.4 installed. Clone the repo and verify everything works: |
| 8 | + |
| 9 | +```sh |
| 10 | +git clone https://github.com/NightmarePog/Lazarus |
| 11 | +cd Lazarus |
| 12 | +make selfhost |
| 13 | +``` |
| 14 | + |
| 15 | +If `make selfhost` prints `fixpoint verified`, you're good. That command rebuilds the compiler from its own source and checks that the output is identical to the input binary. |
| 16 | + |
| 17 | +## Project layout |
| 18 | + |
| 19 | +``` |
| 20 | +compiler/ Lazarus compiler source (written in Lazarus) |
| 21 | +std/ Standard library |
| 22 | +doc/ Documentation |
| 23 | +bin/ Compiled compiler binary (bin/lazarusc.lua) |
| 24 | +examples/ Example programs |
| 25 | +``` |
| 26 | + |
| 27 | +The compiler pipeline goes: Linker → Expander → Lexer → Parser → Schematic → Typecheck → Optimizer → Codegen → Bundler. Each stage has its own directory under `compiler/frontend/` or `compiler/backend/`. |
| 28 | + |
| 29 | +## Adding a language feature |
| 30 | + |
| 31 | +Read `doc/adding-features.md` before touching anything. The short version: one concept, one file, registered in a `HANDLERS` or `TOKENS` table. Never add to an existing `if/elseif` chain. Walk the pipeline front to back. |
| 32 | + |
| 33 | +## Before submitting a PR |
| 34 | + |
| 35 | +Run all three: |
| 36 | + |
| 37 | +```sh |
| 38 | +make selfhost # must print "fixpoint verified" |
| 39 | +make lint # selene |
| 40 | +make format # stylua |
| 41 | +``` |
| 42 | + |
| 43 | +All three must pass. If `make selfhost` fails, the compiler can no longer compile itself and the PR won't be merged. |
| 44 | + |
| 45 | +## Commit style |
| 46 | + |
| 47 | +Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`. Keep the subject line under 72 characters. No `Co-Authored-By` trailers. |
| 48 | + |
| 49 | +## Opening issues |
| 50 | + |
| 51 | +Bug reports and feature requests are welcome. For bugs, include the source file that triggers the issue and the error output. For feature requests, check the open issues first -- a lot of planned work is already tracked there. |
| 52 | + |
| 53 | +## Code style |
| 54 | + |
| 55 | +- No comments that describe what the code does -- only comments that explain why something non-obvious is happening |
| 56 | +- Follow the patterns already in the file you're editing |
| 57 | +- Stylua handles formatting -- don't fight it |
| 58 | + |
| 59 | +## What's a good first contribution |
| 60 | + |
| 61 | +Issues tagged [`good first issue`](https://github.com/NightmarePog/Lazarus/issues?q=is%3Aopen+label%3A%22good+first+issue%22) are scoped to be approachable without deep knowledge of the full pipeline. |
0 commit comments