{"id":13804215,"url":"https://github.com/lambdaclass/cairo_native","last_synced_at":"2025-05-15T16:07:52.707Z","repository":{"id":119071694,"uuid":"609222523","full_name":"lambdaclass/cairo_native","owner":"lambdaclass","description":"A compiler to convert Cairo's intermediate representation \"Sierra\" code to MLIR.","archived":false,"fork":false,"pushed_at":"2025-05-13T15:48:19.000Z","size":36595,"stargazers_count":126,"open_issues_count":75,"forks_count":47,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-05-13T15:50:43.310Z","etag":null,"topics":["cairo","mlir","rust"],"latest_commit_sha":null,"homepage":"https://lambdaclass.github.io/cairo_native/cairo_native","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lambdaclass.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-03-03T16:24:22.000Z","updated_at":"2025-05-13T14:33:22.000Z","dependencies_parsed_at":"2023-12-20T12:33:15.547Z","dependency_job_id":"f313b469-e99a-4094-8a08-c6a211790109","html_url":"https://github.com/lambdaclass/cairo_native","commit_stats":null,"previous_names":["lambdaclass/cairo_native"],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdaclass%2Fcairo_native","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdaclass%2Fcairo_native/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdaclass%2Fcairo_native/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdaclass%2Fcairo_native/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lambdaclass","download_url":"https://codeload.github.com/lambdaclass/cairo_native/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254374475,"owners_count":22060611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cairo","mlir","rust"],"created_at":"2024-08-04T01:00:43.849Z","updated_at":"2025-05-15T16:07:52.700Z","avatar_url":"https://github.com/lambdaclass.png","language":"Rust","funding_links":[],"categories":["Additional developer resources","Layer 2"],"sub_categories":["Starknet"],"readme":"\u003cdiv align=\"center\"\u003e\n\n### ⚡ Cairo Native ⚡\n\nA compiler to convert Cairo's intermediate representation \"Sierra\" code \u003cbr\u003e\nto machine code via MLIR and LLVM.\n\n[Report Bug](https://github.com/lambdaclass/cairo_native/issues/new) · [Request Feature](https://github.com/lambdaclass/cairo_native/issues/new)\n\n[![Telegram Chat][tg-badge]][tg-url]\n[![rust](https://github.com/lambdaclass/cairo_native/actions/workflows/ci.yml/badge.svg)](https://github.com/lambdaclass/cairo_native/actions/workflows/ci.yml)\n[![codecov](https://img.shields.io/codecov/c/github/lambdaclass/cairo_native)](https://codecov.io/gh/lambdaclass/cairo_native)\n[![license](https://img.shields.io/github/license/lambdaclass/cairo_native)](/LICENSE)\n[![pr-welcome]](#-contributing)\n[![Crates.io Version](https://img.shields.io/crates/v/cairo_native)](https://crates.io/crates/cairo-native)\n\n\n[tg-badge]: https://img.shields.io/endpoint?url=https%3A%2F%2Ftg.sumanjay.workers.dev%2FLambdaStarkNet%2F\u0026logo=telegram\u0026label=chat\u0026color=neon\n[tg-url]: https://t.me/LambdaStarkNet\n[pr-welcome]: https://img.shields.io/static/v1?color=orange\u0026label=PRs\u0026style=flat\u0026message=welcome\n\n\u003c/div\u003e\n\n- [Getting Started](#getting-started)\n- [Included Tools](#included-tools)\n  - [Scripts](#scripts)\n  - [cairo-native-compile](#cairo-native-compile)\n  - [cairo-native-dump](#cairo-native-dump)\n  - [cairo-native-run](#cairo-native-run)\n  - [cairo-native-test](#cairo-native-test)\n  - [cairo-native-stress](#cairo-native-stress)\n  - [scarb-native-dump](#scarb-native-dump)\n  - [scarb-native-test](#scarb-native-test)\n- [Benchmarking](#benchmarking)\n\nFor in-depth documentation, see the [developer documentation][].\n\n## Disclaimer\n🚧 Cairo Native is still being built therefore API breaking changes might happen\noften so use it at your own risk. 🚧\n\nFor versions under `1.0` `cargo` doesn't comply with\n[semver](https://semver.org/), so we advise to pin the version you\nuse. This can be done by adding `cairo-native = \"0.5.0-rc.5\"` to your Cargo.toml\n\n## Getting Started\n\n### Dependencies\n- Linux or macOS (aarch64 included) only for now\n- LLVM 19 with MLIR: On debian you can use [apt.llvm.org](https://apt.llvm.org/),\n  on macOS you can use brew\n- Rust 1.78.0 or later, since we make use of the u128\n  [abi change](https://blog.rust-lang.org/2024/03/30/i128-layout-update.html).\n- Git\n\n### Setup\n\u003e This step applies to all operating systems.\n\nRun the following make target to install the dependencies (**both Linux and macOS**):\n\n```bash\nmake deps\n```\n\n#### Linux\nSince Linux distributions change widely, you need to install LLVM 19 via your\npackage manager, compile it or check if the current release has a Linux binary.\n\nIf you are on Debian/Ubuntu, check out the repository https://apt.llvm.org/\nThen you can install with:\n\n```bash\nsudo apt-get install llvm-19 llvm-19-dev llvm-19-runtime clang-19 clang-tools-19 lld-19 libpolly-19-dev libmlir-19-dev mlir-19-tools\n```\n\nIf you decide to build from source, here are some indications:\n\n\u003cdetails\u003e\u003csummary\u003eInstall LLVM from source instructions\u003c/summary\u003e\n\n```bash\n# Go to https://github.com/llvm/llvm-project/releases\n# Download the latest LLVM 19 release:\n# The blob to download is called llvm-project-19.x.x.src.tar.xz\n\n# For example\nwget https://github.com/llvm/llvm-project/releases/download/llvmorg-19.1.7/llvm-project-19.1.7.src.tar.xz\ntar xf llvm-project-19.1.5.src.tar.xz\n\ncd llvm-project-19.1.5.src.tar\nmkdir build\ncd build\n\n# The following cmake command configures the build to be installed to /opt/llvm-19\ncmake -G Ninja ../llvm \\\n   -DLLVM_ENABLE_PROJECTS=\"mlir;clang;clang-tools-extra;lld;polly\" \\\n   -DLLVM_BUILD_EXAMPLES=OFF \\\n   -DLLVM_TARGETS_TO_BUILD=\"Native\" \\\n   -DCMAKE_INSTALL_PREFIX=/opt/llvm-19 \\\n   -DCMAKE_BUILD_TYPE=RelWithDebInfo \\\n   -DLLVM_PARALLEL_LINK_JOBS=4 \\\n   -DLLVM_ENABLE_BINDINGS=OFF \\\n   -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DLLVM_ENABLE_LLD=ON \\\n   -DLLVM_ENABLE_ASSERTIONS=OFF\n\nninja install\n```\n\n\u003c/details\u003e\n\nSetup a environment variable called `MLIR_SYS_190_PREFIX`, `LLVM_SYS_191_PREFIX`\nand `TABLEGEN_190_PREFIX` pointing to the llvm directory:\n\n```bash\n# For Debian/Ubuntu using the repository, the path will be /usr/lib/llvm-19\nexport MLIR_SYS_190_PREFIX=/usr/lib/llvm-19\nexport LLVM_SYS_191_PREFIX=/usr/lib/llvm-19\nexport TABLEGEN_190_PREFIX=/usr/lib/llvm-19\n```\n\nAlternatively, if installed from Debian/Ubuntu repository, then you can use\n`env.sh` to automatically setup the environment variables.\n\n```bash\nsource env.sh\n```\n\n#### MacOS\nThe makefile `deps` target (which you should have ran before) installs LLVM 19\nwith brew for you, afterwards you need to execute the `env.sh` script to setup\nthe needed environment variables.\n\n```bash\nsource env.sh\n```\n\n### Make targets:\nRunning `make` by itself will check whether the required LLVM installation and\ncorelib is found, and then list available targets.\n\n```bash\n% make\nLLVM is correctly set at /opt/homebrew/opt/llvm.\n./scripts/check-corelib-version.sh 2.12.0-dev.0\nUsage:\n    deps:         Installs the necesary dependencies.\n    build:        Builds the cairo-native library and binaries in release mode.\n    build-native: Builds cairo-native with the target-cpu=native rust flag.\n    build-dev:    Builds cairo-native under a development-optimized profile.\n    check:        Checks format and lints.\n    test:         Runs all tests.\n    proptest:     Runs property tests.\n    coverage:     Runs all tests and computes test coverage.\n    doc:          Builds documentation.\n    doc-open:     Builds and opens documentation in browser.\n    bench:        Runs the hyperfine benchmark script.\n    bench-ci:     Runs the criterion benchmarks for CI.\n    install:      Invokes cargo to install the cairo-native tools.\n    clean:        Cleans the built artifacts.\n    stress-test   Runs a command which runs stress tests.\n    stress-plot   Plots the results of the stress test command.\n    stress-clean  Clean the cache of AOT compiled code of the stress test command.\n```\n\n## Included Tools\nAside from the compilation and execution engine library, Cairo Native includes\na few command-line tools to aid development, and some useful scripts.\n\nThese are:\n- The contents of the `/scripts/` folder\n- `cairo-native-compile`\n- `cairo-native-dump`\n- `cairo-native-run`\n- `cairo-native-test`\n- `cairo-native-stress`\n- `scarb-native-dump`\n- `scarb-native-test`\n\n### `cairo-native-compile`\n```bash\nCompiles a Cairo project outputting the generated MLIR and the shared library.\nExits with 1 if the compilation or run fails, otherwise 0.\n\nUsage: cairo-native-compile [OPTIONS] \u003cPATH\u003e [OUTPUT_MLIR] [OUTPUT_LIBRARY]\n\nArguments:\n  \u003cPATH\u003e            The Cairo project path to compile and run its tests\n  [OUTPUT_MLIR]     The output path for the mlir, if none is passed, out.mlir will be the default\n  [OUTPUT_LIBRARY]  If a path is passed, a dynamic library will be compiled and saved at that path\n\nOptions:\n  -s, --single-file            Whether path is a single file\n      --allow-warnings         Allows the compilation to succeed with warnings\n  -r, --replace-ids            Replaces sierra ids with human-readable ones\n  -O, --opt-level \u003cOPT_LEVEL\u003e  Optimization level, Valid: 0, 1, 2, 3. Values higher than 3 are considered as 3 [default: 0]\n  -h, --help                   Print help\n  -V, --version                Print version\n```\n\n###  `cairo-native-dump`\n```bash\nUsage: cairo-native-dump [OPTIONS] \u003cINPUT\u003e\n\nArguments:\n  \u003cINPUT\u003e\n\nOptions:\n  -o, --output \u003cOUTPUT\u003e  [default: -]\n      --starknet         Compile a starknet contract\n  -h, --help             Print help\n```\n\n### `cairo-native-run`\nThis tool allows to run programs using the JIT engine, like the `cairo-run`\ntool, the parameters can only be felt values.\n\nExample: `echo '1' | cairo-native-run 'program.cairo' 'program::program::main' --inputs - --outputs -`\n\n```bash\nExits with 1 if the compilation or run fails, otherwise 0.\n\nUsage: cairo-native-run [OPTIONS] \u003cPATH\u003e\n\nArguments:\n  \u003cPATH\u003e  The Cairo project path to compile and run its tests\n\nOptions:\n  -s, --single-file                    Whether path is a single file\n      --allow-warnings                 Allows the compilation to succeed with warnings\n      --available-gas \u003cAVAILABLE_GAS\u003e  In cases where gas is available, the amount of provided gas\n      --run-mode \u003cRUN_MODE\u003e            Run with JIT or AOT (compiled) [default: jit] [possible values: aot, jit]\n  -O, --opt-level \u003cOPT_LEVEL\u003e          Optimization level, Valid: 0, 1, 2, 3. Values higher than 3 are considered as 3 [default: 0]\n  -h, --help                           Print help\n  -V, --version                        Print version\n```\n\n### `cairo-native-test`\nThis tool mimics the `cairo-test`\n[tool](https://github.com/starkware-libs/cairo/tree/main/crates/cairo-lang-test-runner)\nand is identical to it in interface, the only feature it doesn't have is the profiler.\n\n```bash\nCompiles a Cairo project and runs all the functions marked as `#[test]`.\nExits with 1 if the compilation or run fails, otherwise 0.\n\nUsage: cairo-native-test [OPTIONS] \u003cPATH\u003e\n\nArguments:\n  \u003cPATH\u003e  The Cairo project path to compile and run its tests\n\nOptions:\n  -s, --single-file            Whether path is a single file\n      --allow-warnings         Allows the compilation to succeed with warnings\n  -f, --filter \u003cFILTER\u003e        The filter for the tests, running only tests containing the filter string [default: ]\n      --include-ignored        Should we run ignored tests as well\n      --ignored                Should we run only the ignored tests\n      --starknet               Should we add the starknet plugin to run the tests\n      --run-mode \u003cRUN_MODE\u003e    Run with JIT or AOT (compiled) [default: jit] [possible values: aot, jit]\n  -O, --opt-level \u003cOPT_LEVEL\u003e  Optimization level, Valid: 0, 1, 2, 3. Values higher than 3 are considered as 3 [default: 0]\n  -h, --help                   Print help\n  -V, --version                Print version\n```\n\nFor single files, you can use the `-s, --single-file` option.\n\nFor a project, it needs to have a `cairo_project.toml` specifying the\n`crate_roots`. You can find an example under the `cairo-tests/` folder, which\nis a cairo project that works with this tool.\n\n```bash\ncairo-native-test -s myfile.cairo\n\ncairo-native-test ./cairo-tests/\n```\n\nThis will run all the tests (functions marked with the `#[test]` attribute).\n\n### `cairo-native-stress`\nThis tool runs a stress test on Cairo Native.\n\n```bash\nA stress tester for Cairo Native\n\nIt compiles Sierra programs with Cairo Native, caches, and executes them with AOT runner. The compiled dynamic libraries are stored in `AOT_CACHE_DIR` relative to the current working directory.\n\nUsage: cairo-native-stress [OPTIONS] \u003cROUNDS\u003e\n\nArguments:\n  \u003cROUNDS\u003e\n          Amount of rounds to execute\n\nOptions:\n  -o, --output \u003cOUTPUT\u003e\n          Output file for JSON formatted logs\n\n  -h, --help\n          Print help (see a summary with '-h')\n```\n\nTo quickly run a stress test and save logs as json, run:\n```bash\nmake stress-test\n```\n\nThis takes a lot of time to finish (it will probably crash first), you can kill\nthe program at any time.\n\nTo plot the results, run:\n```bash\nmake stress-plot\n```\n\nTo clear the cache directory, run:\n```bash\nmake stress-clean\n```\n\n### `scarb-native-dump`\nThis tool mimics the `scarb build` [command](https://github.com/software-mansion/scarb/tree/main/extensions/scarb-cairo-test).\nYou can download it on our [releases](https://github.com/lambdaclass/cairo_native/releases) page.\n\nThis tool should be run at the directory where a `Scarb.toml` file is and it will\nbehave like `scarb build`, leaving the MLIR files under the `target/` folder\nbesides the generated JSON sierra files.\n\n### `scarb-native-test`\nThis tool mimics the `scarb test` [command](https://github.com/software-mansion/scarb/tree/main/extensions/scarb-cairo-test).\nYou can download it on our [releases](https://github.com/lambdaclass/cairo_native/releases) page.\n\n```bash\nCompiles all packages from a Scarb project matching `packages_filter` and\nruns all functions marked with `#[test]`. Exits with 1 if the compilation\nor run fails, otherwise 0.\n\nUsage: scarb-native-test [OPTIONS]\n\nOptions:\n  -p, --package \u003cSPEC\u003e         Packages to run this command on, can be a concrete package name (`foobar`) or a prefix glob (`foo*`) [env: SCARB_PACKAGES_FILTER=] [default: *]\n  -w, --workspace              Run for all packages in the workspace\n  -f, --filter \u003cFILTER\u003e        Run only tests whose name contain FILTER [default: ]\n      --include-ignored        Run ignored and not ignored tests\n      --ignored                Run only ignored tests\n      --run-mode \u003cRUN_MODE\u003e    Run with JIT or AOT (compiled) [default: jit] [possible values: aot, jit]\n  -O, --opt-level \u003cOPT_LEVEL\u003e  Optimization level, Valid: 0, 1, 2, 3. Values higher than 3 are considered as 3 [default: 0]\n  -h, --help                   Print help\n  -V, --version                Print version\n```\n\n## Benchmarking\n\n### Requirements\n- [hyperfine](https://github.com/sharkdp/hyperfine): `cargo install hyperfine`\n- [cairo 2.12.0-dev.0](https://github.com/starkware-libs/cairo)\n- Cairo Corelibs\n- LLVM 19 with MLIR\n\nYou need to setup some environment variables:\n\n```bash\n$MLIR_SYS_190_PREFIX=/path/to/llvm19  # Required for non-standard LLVM install locations.\n$LLVM_SYS_191_PREFIX=/path/to/llvm19  # Required for non-standard LLVM install locations.\n$TABLEGEN_190_PREFIX=/path/to/llvm19  # Required for non-standard LLVM install locations.\n```\n\nYou can then run the `bench` makefile target:\n\n```bash\nmake bench\n```\n\nThe `bench` target will run the `./scripts/bench-hyperfine.sh` script.\nThis script runs hyperfine commands to compare the execution time of programs in the `./programs/benches/` folder.\nEach program is compiled and executed via the execution engine with the `cairo-native-run` command and via the cairo-vm with the `cairo-run` command provided by the `cairo` codebase.\nThe `cairo-run` command should be available in the `$PATH` and ideally compiled with `cargo build --release`.\nIf you want the benchmarks to run using a specific build, or the `cairo-run` commands conflicts with something (e.g. the cairo-svg package binaries in macos) then the command to run `cairo-run` with a full path can be specified with the `$CAIRO_RUN` environment variable.\n\n[developer documentation]: https://lambdaclass.github.io/cairo_native/cairo_native/docs/index.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flambdaclass%2Fcairo_native","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flambdaclass%2Fcairo_native","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flambdaclass%2Fcairo_native/lists"}