The Ora Compiler Field Guide

A practical, reader-first book for onboarding contributors and new compiler engineers.

How to use this guide

This guide is written in two “lanes”:

• Lane A — Contributor: no compiler background required. You’ll ship tests, repros, docs, diagnostics, and small safe changes.
• Lane B — Compiler Engineer: you’ll touch parsing, semantics, type resolution, MLIR lowering, legality, and verification.

You can read the whole book, or follow the lane markers inside chapters.

Guiding rule: Ora is a pipeline. Every phase produces an artifact. When something breaks, find the first artifact that looks wrong, then fix the phase that produced it.

Table of contents

Main chapters

• Welcome
• Your First Win
• The Compiler Shape
• Contribution Tracks
• One Story End-to-End
• A Walkthrough That Intentionally Fails
• The Core Systems
• Debugging Playbook
• Your First Compiler PR
• Advanced Topics

Appendices

• Appendix A — Glossary
• Appendix B — Codebase Map
• Appendix C — Add a Feature Checklist
• Appendix D — Where to Add Tests