PyC

Lightweight compiler/toolchain project with a canonical cross-platform CMake build and stable core targets for deterministic CI.

Overview

PyC currently focuses on stable build/link contracts and deterministic CI behavior:

• pyc_core_obj: object library for stable core objects.
• pyc_core: canonical static library from pyc_core_obj.
• pyc_foundation: compatibility static library from the same objects.
• pyc: minimal deterministic executable used by smoke tests.

The next-generation compiler scaffolding is available behind PYC_BUILD_COMPILER_NEXT=ON.

Repository Layout

• Core/C_Files/: C sources.
• Core/Header_Files/: C headers.
• .github/workflows/cmake-multi-platform.yml: canonical CI workflow.
• benchmark/: benchmark harness and workloads.
• AI/: linked AI bridge layer that applies optimization-policy contracts to compiler-next options.
• docs/: project docs, benchmarking, build/CI, performance reports.

Build

Prerequisites

• CMake >= 3.10
• C compiler with C11 support
• Python 3 (for benchmark harness)

Configure + Build Stable Targets

cmake -S . -B build
cmake --build build --parallel --target pyc pyc_core pyc_foundation

Smoke Test

Linux/macOS:

./build/pyc

Windows (multi-config generators):

.\build\Release\pyc.exe

Expected output:

PyC CI driver: core targets configured successfully.

CI

The project uses one canonical workflow: CI in .github/workflows/cmake-multi-platform.yml.

It runs on Ubuntu, macOS, and Windows, and performs:

1. CMake configure
2. Explicit build of pyc, pyc_core, pyc_foundation
3. OS-specific smoke test for pyc
4. Non-fatal ctest

CI also enforces source coverage for active C sources (Core/C_Files, compiler, AI, tests/compiler_next): if a .c file is not referenced by CMakeLists.txt, the suite fails.

Build Efficiency

You do not need to rebuild everything from scratch locally on every push.

1. Reuse the same build/ directory between edits.
2. Re-run cmake --build build --parallel for incremental builds.
3. CI runners are ephemeral, but Linux/macOS jobs now use ccache to reduce repeated compile time across runs.

Benchmarking

PyC includes a deterministic benchmark harness for stable core targets.

Run:

python3 benchmark/harness.py --repeats 7 --micro-rounds 4000

Outputs:

• benchmark/results/latest.json
• benchmark/results/latest.md
• docs/performance-results.md

How To Use PyC

Stable CLI Entrypoint (Recommended)

Build and run the deterministic CI driver:

cmake -S . -B build
cmake --build build --parallel --target pyc pyc_core pyc_foundation
./build/pyc

Expected output:

PyC CI driver: core targets configured successfully.

Link pyc_core in Your Own Project

1. Build pyc_core:

cmake -S . -B build
cmake --build build --parallel --target pyc_core

2. In your C/C++ project:

• Add include path: Core/Header_Files/
• Link static library: build/libpyc_core.a (or platform-equivalent)

Use pyc_foundation only when downstream compatibility requires it.

Compiler-Next (Experimental)

Build and run the compiler-next smoke test:

cmake -S . -B build -D PYC_BUILD_COMPILER_NEXT=ON -D PYC_BUILD_COMPILER_NEXT_TESTS=ON
cmake --build build --parallel --target pyc_compiler_next pyc_compiler_next_smoke
./build/pyc_compiler_next_smoke

Public interfaces:

• include/pyc/compiler_api.h
• include/pyc/ir.h
• include/pyc/pass_manager.h
• include/pyc/runtime_allocator.h
• include/pyc/kernel_registry.h
• include/pyc/runtime_control.h
• include/pyc/ai_bridge.h

Binary Distribution

Release binaries are packaged and published by:

• .github/workflows/release-binaries.yml

Assets are published per OS:

• pyc-linux-x86_64.tar.gz
• pyc-macos-arm64.tar.gz
• pyc-windows-x86_64.zip

Static download page for end users:

• index.html (uses styles.css and app.js at repo root)

When published with GitHub Pages, this page auto-detects OS and links the latest release asset.

Status

• Stable CI/link targets are in place and cross-platform oriented.
• Experimental compiler pipeline is not yet part of stable CI guarantees.
• Benchmark harness is active for measuring build and runtime behavior of stable targets.

Documentation

Start at docs/README.md.

Key docs:

• docs/project-status.md
• docs/build-and-ci.md
• docs/benchmarking.md
• docs/performance-results.md
• docs/REPO_RULES.md
• docs/compiler-next/runtime-integration-spec.md

Community

• CODE_OF_CONDUCT.md
• CONTRIBUTING.md
• SECURITY.md
• SUPPORT.md
• .github/ISSUE_TEMPLATE/
• .github/pull_request_template.md

License

Licensed under Apache 2.0. See LICENSE.