Cairo Compiler Setup for Provable Programs

Cairo's Provable Program Compilation Boundary

Cairo is described by the repository as a Turing-complete language for creating provable programs for general computation. The repository under review is not a separate application framework or a hosted proof service. It is the compiler toolchain, written in Rust, that turns Cairo source into lower-level representations used by execution and Starknet workflows. The intended users are developers working with Cairo programs who need command-line access to compilation, local execution, Sierra generation, Cairo assembly, or Starknet contract artifacts.

The project distinguishes several outputs. Cairo source can be compiled to Sierra, Sierra can be compiled to CASM, and Cairo code can be executed directly through the runner. Starknet contracts have a separate path that produces a Sierra `ContractClass` or a CASM `CompiledClass`. That separation matters because the input and output formats are not interchangeable. A Cairo file, a Sierra file, and a Starknet contract project each enter the toolchain at a different point.

The repository also contains `corelib/`, `examples/`, `tests/`, and a `crates/` workspace. Based on the repository layout, the compiler implementation is organized as many Rust crates, while the documented user entry points are binaries such as `cairo-compile`, `cairo-run`, `sierra-compile`, `starknet-compile`, and `starknet-sierra-compile`. The available binaries include formatting, testing, execution, profiling, syntax generation, lowering inspection, and Sierra upgrade validation tools, but the README focuses on the core compilation and execution paths.

Cairo, Sierra, and CASM Data Flow

The documented compiler flow is staged. First, `cairo-compile` takes a Cairo source file and writes a Sierra file while replacing identifiers through `--replace-ids`. Sierra is the intermediate artifact in the documented workflow. Next, `sierra-compile` consumes that Sierra output and writes CASM, identified in the README as Cairo assembly. This gives a developer a way to inspect or use intermediate output rather than jumping directly from source to assembly.

For direct execution, the repository provides `cairo-run`, which accepts a single Cairo file. The README points to `crates/cairo-lang-runner/README.md` for runner details and to the `examples/` directory for source files. The examples include basic and more specialized cases such as `fib.cairo`, `fib_loop.cairo`, `fib_match.cairo`, `hash_chain.cairo`, and `pedersen_test.cairo`. These names indicate that the repository includes examples for language features and computational patterns, although the README does not provide execution output or runtime measurements.

Starknet compilation has a parallel path. `starknet-compile` accepts either a crate or project path and produces a Sierra ContractClass JSON file. A project containing multiple contracts requires `--contract-path`, while a single Cairo file requires `--single-file`. Once the Sierra ContractClass exists, `starknet-sierra-compile` produces a CASM CompiledClass. This two-stage contract flow is the clearest indication that Cairo source, Sierra, and CASM are separate representations in the project.

Rust Prerequisites and Repository Validation

The README lists Rust as the prerequisite for building the compiler from this repository. Its setup command selects the stable toolchain and updates it. The documentation then asks the developer to run the workspace tests from the repository root. The commands below reproduce the documented setup and validation sequence.

rustup override set stable && rustup update

This command establishes the repository's Rust override and updates the installed toolchain. After it completes, the documented check is the workspace test command. The repository uses a Cargo workspace, so the root `Cargo.toml` is the starting point for building the documented binaries.

cargo test

The README does not state expected output for this command, so a successful completion status is the only documented expectation. It also does not document a non-Rust installation path for these binaries. Developers who need a packaged executable rather than a source build would need an installation source outside the commands shown here.

Compiling and Running a First Cairo File

The shortest documented first use is to compile one Cairo file to Sierra, then optionally compile the Sierra file to CASM. Substitute the paths with real files from the checkout. The first command uses `--single-file`, names the input and output paths, and enables `--replace-ids`.

cargo run --bin cairo-compile -- --single-file /path/to/input.cairo /path/to/output.sierra --replace-ids

The expected result, based on the command shape and README wording, is an output file at `/path/to/output.sierra`. The README does not describe diagnostic formatting or whether the generated file contains readable identifiers after replacement. A second command converts the Sierra artifact to CASM.

cargo run --bin sierra-compile -- /path/to/input.sierra /path/to/output.casm

The second step consumes `/path/to/input.sierra` and writes `/path/to/output.casm`. To run a Cairo file without manually performing the two compilation steps, use the runner binary documented by the README.

cargo run --bin cairo-run -- --single-file /path/to/file.cairo

The README directs readers to the examples directory for suitable input files and to the runner README for behavior not covered by the top-level guide.

Starknet Contract Compilation Paths

Starknet contract compilation differs from ordinary Cairo compilation because the compiler input can represent a crate, a project, or a single Cairo file. For a crate or project path, the README gives a direct `starknet-compile` command.

cargo run --bin starknet-compile -- /path/to/input/crate /path/to/output.json

When several contracts are defined in the same crate or project, the contract selector is required. The documented selector uses a path-like Rust module syntax, so it should be copied from the project rather than guessed.

cargo run --bin starknet-compile -- /path/to/input/crate /path/to/output.json --contract-path path::to::contract

For a single `.cairo` input, the command changes to `--single-file` and places the input flag before the source path.

cargo run --bin starknet-compile -- --single-file /path/to/input.cairo /path/to/output.json

The output is a Sierra ContractClass JSON file. A later compilation step converts that JSON into a CASM CompiledClass.

cargo run --bin starknet-sierra-compile -- /path/to/input.json /path/to/output.casm

This path is useful for developers who already work with Starknet contracts, but the README does not explain deployment, account configuration, RPC access, or proof submission. Those concerns are outside the commands documented here.

Maintenance, License, and Adoption Limits

The repository is not archived, and its last push was on 2026-10-15. The recent releases listed include `v2.21.0` on 2026-10-09 and `v2.19.6` on 2026-09-27. Those facts indicate recent project activity, but the README does not provide a release compatibility matrix or a migration policy for every Cairo or Sierra change. Upgrading a compiler checkout can therefore involve checking the release notes and validating contract artifacts against the intended runtime.

The project is licensed under `Apache-2.0`. The repository includes a `LICENSE` file, and the README points readers there for the full terms. This is a licensing fact, not legal advice. Organizations should review the actual license and any dependency terms relevant to their distribution model.

Cairo is the relevant alternative for developers who need the Cairo compiler and its Rust implementation. A general-purpose Rust compiler does not replace it because the commands compile Cairo to Sierra, Cairo assembly, and Starknet contract classes. Conversely, a Starknet-specific contract toolchain is not equivalent to the general Cairo source-to-Sierra path. The main adoption limit is scope: this repository provides compiler tools and examples, while deployment and external proof infrastructure are not documented in the README.

Editorial conclusion

Adopt this repository when a project already uses Cairo and needs the compiler binaries from source. Do not choose it merely to execute arbitrary untrusted code or avoid Starknet-specific compilation steps. Verify first that the required Rust toolchain is installed, the checkout contains the relevant binary crate, and the intended Cairo input format matches the command being used.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. starkware-libs/cairo on GitHub