pycc

Architecture · Updated 2026-08-02

Python source to native code.

pycc is a pre-alpha Rust compiler pipeline with an LLVM backend. The implemented v0.1 language surface runs end to end with documented gaps; SSA, ownership analysis, and broader runtime and standard library support remain staged roadmap work.

Frontend v0.1 checked Backend LLVM 22 · v0.1 implemented Output native executable

Implemented now

The first compiler path crosses every major stage.

  1. 01
    Parse Python

    pycc_parser wraps the vendored Ruff Python parser and converts supported syntax into pycc_ast nodes with source ranges.

  2. 02
    Lower to HIR

    pycc_hir represents the implemented v0.1 frontend subset: expressions, assignments, functions, control flow, primitive values, range, and basic f-strings.

  3. 03
    Resolve and type-check

    pycc_types::check_and_resolve enforces public annotations, rejects Any, infers private helpers, validates expressions and control flow, and materializes concrete signatures before MIR.

  4. 04
    Cross the backend boundary

    MIR and code generation cover the implemented v0.1 surface: typed arithmetic and comparisons, control flow, functions and recursion, module globals, primitive values, strings, basic f-strings, and type-aware print. Known representation and lifetime gaps remain explicit in the roadmap.

  5. 05
    Generate and link

    pycc_codegen uses LLVM to emit an object. The driver invokes the host toolchain to link a native executable with the minimal runtime.

Repository boundaries

Nine implementation crates exist today.

pyccCLI and orchestration
pycc_astCurrent source model
pycc_parserParser adapter
pycc_hirv0.1 high-level IR
pycc_typesStrict checking and inference
pycc_mirv0.1 typed mid-level IR
pycc_codegenv0.1 LLVM backend
pycc_rtMinimal runtime
pycc_diagHuman and JSON diagnostics

The architecture specification also reserves pycc_lexer, pycc_own, pycc_std, and pycc_testkit. Those boundaries are deliberate future work, not current modules hidden behind marketing language.

Design contract

The target pipeline is richer than the current v0.1 implementation.

The implemented frontend already resolves and checks the v0.1 primitive subset. The target architecture extends that checked surface into fully typed SSA MIR, ownership and escape analysis, optimizations such as reference-count elision and monomorphization, and complete runtime and standard-library components linked into a standalone native binary for native and pure builds. Planned permitted CPython interop instead adds the pinned interpreter and dependency closure to an autonomous application bundle.

Standard Python, not a compiler dialect.

The v1 language contract is Python 3.14. Static restrictions must be expressed as documented diagnostics rather than new syntax.

Portability model

Five Tier-1 targets gate the project.

Linux x64 and arm64, macOS x64 and arm64, and Windows x64 are native CI targets. Same-OS, cross-architecture macOS compilation is proven; arbitrary cross-OS builds are not yet supported because target sysroots and link environments are not bundled.

Working behavior and gaps Current status → Normative system contract Full architecture spec ↗