Metadata-Version: 2.4
Name: piarun
Version: 0.0.2
Summary: piarun: a native C, agent-friendly Rust-to-IR compiler
Author-Email: Dima Korolev <dmitry.korolev@gmail.com>
License-Expression: LicenseRef-Proprietary
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: C
Classifier: Topic :: Software Development :: Compilers
Project-URL: Repository, https://github.com/piarun/prn-v2-uvx-piarun
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# piarun

`piarun` compiles a supported Rust subset into base64-encoded, certified PRN IR. The `piarun` Python distribution contains one native C executable named `piarun`; Python is used for package installation, not command execution. No runtime package dependencies, compiler installation, credentials, or network access are required by the installed binary.

## Install and run

After publication:

```sh
uvx piarun version
uvx piarun help
uvx piarun advertise
uvx piarun rs2ir --source 'fn main() { println!("hello"); }'
uvx --from piarun piarun rs2ir --input main.rs
uv tool install piarun
piarun version
```

Before publication, build and run the local wheel:

```sh
uv build
uvx --from ./dist/piarun-0.0.2-py3-none-macosx_11_0_arm64.whl piarun version
```

Use the wheel filename produced on your platform. `uvx --from . piarun version` also builds directly from the checkout. `piarun` is the package name and the only executable name.

For source edits without a version bump, use `uvx --no-cache --from . piarun ...` to bypass a previously cached tool environment.

## Compiler contract

```sh
piarun rs2ir --input main.rs
printf 'fn main() { println!("hello"); }' | piarun rs2ir --input -
piarun rs2ir --source 'fn main() { println!("hello"); }' | base64 --decode
```

Successful `rs2ir` output is always a single line of base64, whether displayed in a terminal, piped, captured, or invoked with `--json`. Pipe it directly into `base64 --decode`; no JSON envelope or field extraction is needed. Metadata commands and ordinary errors retain their structured JSON output when piped or passed `--json`.

The code is RFC 4648 standard padded base64 of compact UTF-8 `Program` JSON, including its PUOPS certificate. The decoded JSON has no insignificant whitespace and no terminal newline; string contents retain their whitespace. An unsupported construct or failed certification is an error, never an uncertified success. Rust input is bounded to 4 MiB and JSON to 32 MiB. See [CLI-CONTRACT.md](CLI-CONTRACT.md) for fields and exit codes.

## Build

```sh
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel 4
ctest --test-dir build --output-on-failure
./build/piarun version
uv build
```

The executable is C11 throughout, including the compiler submodule. CMake and declarative `pyproject.toml` metadata build platform wheels with `scikit-build-core`. Python files are verification and release tooling only; there are no Python modules, launchers, or Python shared-library dependencies in the wheel. Wheels use `py3-none-PLATFORM` tags and support installers using Python 3.9+. Source builds require Git, CMake 3.20+, and a C11 compiler; wheels do not.

Builds default to `distribution: local`. Release workflows set `pypi`; other distributors can set `-DPRN_DISTRIBUTION=github` or another label. `version` also includes the UTC build date, source revision, frontend revision, and platform. `SOURCE_DATE_EPOCH` controls reproducible build dates. **Distribution describes artifact provenance, not the installer's download location:** a release wheel copied from PyPI and installed locally remains the same artifact. Missing Git history is honestly reported as `uncommitted`; release jobs supply the exact commit explicitly.

## Platforms and release

The wheel matrix targets macOS 11+ on Apple Silicon and Intel, Linux glibc 2.17+ and musl 1.2+ on x86-64/AArch64, and Windows 10 version 1903+ on AMD64 and Windows 11 on ARM64. [RELEASE.md](RELEASE.md) explains native build/test jobs, provenance, and trusted publishing. See [VALIDATION.md](VALIDATION.md) for what has actually been run locally; a configured target is not evidence of a successful execution test.

## Scope

| Capability | Owner |
| --- | --- |
| Rust subset parsing and certification | Submodule, pinned `prn-v2-rs2ir-c`; see [vendor/README.md](vendor/README.md) |
| IR schema authority | `prn-v2-schema` Rust/Serde definitions |
| Execution, persistence, generated code | `prn-v2-interpret-*`, `prn-v2-ir2code-*`, and `prn-v2-prnc-*` |
| Full Rust compilation and type checking | `rustc` |
| Gateway hosting | `prn-v2-prngwd` |

`piarun` does not execute submitted source, add dependencies, mutate the source file, or contact a service. A temporary IR stream is closed on success and reclaimed on process exit. The source repository is private. Publication remains a deliberate maintainer action.

## Clone the private source

```sh
git clone --recurse-submodules git@github.com:piarun/prn-v2-uvx-piarun.git
cd prn-v2-uvx-piarun
python3 tools/gate.py
```

An existing checkout needs `git submodule update --init --recursive`. Source archives include the pinned compiler sources and build without GitHub access.
