Start

Requirements

• Python 3.13 or newer
• uv for the Python environment
• Zig 0.16.0 to build generated Zig output
• Bun to build the docs site locally

Install

git clone https://github.com/code5717/a7-py.git
cd a7-py
uv sync
zig version

The preferred compiler entry point is:

uv run a7 examples/001_hello.a7

The repository wrapper is equivalent:

uv run python main.py examples/001_hello.a7

First compile

uv run a7 examples/001_hello.a7 --mode compile
zig run examples/001_hello.zig

The backend writes one Zig file per A7 input. Multi-file A7 input can be resolved by the compiler, but the generated Zig output remains single-file.

Language tour

Read the current language surface in one verified example file:

uv run a7 examples/037_language_tour.a7 --mode pipeline

See Language for a short reference. Full semantics live in docs/SPEC.md.

Useful modes

Mode	Purpose
tokens	Show lexer output
ast	Show parsed structure
semantic	Run semantic checks
pipeline	Run the full compiler pipeline without writing a file
compile	Emit Zig
doc	Emit compiler documentation output

Use --format json for tools and agents. CLI modes and exit codes are listed on the Compiler page.

Verify locally

Quick check after a compiler change:

uv run python scripts/verify_examples_e2e.py

Full release gate (heavier):

./run_all_tests.sh

Use the full gate before tagging or claiming a compiler change is complete. See Release for the complete checklist.