{"id":13748939,"url":"https://github.com/AeneasVerif/charon","last_synced_at":"2025-05-09T11:31:40.892Z","repository":{"id":38823020,"uuid":"419729872","full_name":"AeneasVerif/charon","owner":"AeneasVerif","description":"Interface with the rustc compiler for the purpose of program verification","archived":false,"fork":false,"pushed_at":"2025-05-07T16:05:28.000Z","size":6641,"stargazers_count":138,"open_issues_count":63,"forks_count":19,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-08T20:56:36.173Z","etag":null,"topics":["compiler","formal-methods","formal-verification","program-verification","rust","rust-lang","static-analysis"],"latest_commit_sha":null,"homepage":"https://aeneasverif.github.io/charon","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/AeneasVerif.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-10-21T13:15:47.000Z","updated_at":"2025-05-07T16:05:33.000Z","dependencies_parsed_at":"2023-02-14T15:01:09.689Z","dependency_job_id":"22e57c36-e3dd-4aca-a1ed-4004a7182559","html_url":"https://github.com/AeneasVerif/charon","commit_stats":null,"previous_names":["sonmarcho/charon"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AeneasVerif%2Fcharon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AeneasVerif%2Fcharon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AeneasVerif%2Fcharon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AeneasVerif%2Fcharon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AeneasVerif","download_url":"https://codeload.github.com/AeneasVerif/charon/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253240350,"owners_count":21876593,"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":["compiler","formal-methods","formal-verification","program-verification","rust","rust-lang","static-analysis"],"created_at":"2024-08-03T07:00:52.859Z","updated_at":"2025-05-09T11:31:35.863Z","avatar_url":"https://github.com/AeneasVerif.png","language":"Rust","funding_links":[],"categories":["Rust","Projects","Static Checkers"],"sub_categories":["Verification"],"readme":"\u003cp\u003e\u003cdiv style=\"text-align: center\"\u003e\n\u003cimg src=\"static/Charon.jpg\"\n     alt=\"Landscape with Charon crossing the Styx\" title=\"Landscape with Charon crossing the Styx\"\n     style=\"\"/\u003e\n\u003cfigcaption\u003e\nPatinir, E., 1515-1524, \u003ci\u003eLandscape with Charon crossing the Styx\u003c/i\u003e [Oil on wood].\nMuseo del Prado, Madrid.\n\u003ca href=\"https://en.wikipedia.org/wiki/Landscape_with_Charon_Crossing_the_Styx\"\u003eSource\u003c/a\u003e\n\u003c/figcaption\u003e\n\u003c/div\u003e\u003c/p\u003e\n\n# Charon\nCharon acts as an interface between the rustc compiler and program verification projects. Its\npurpose is to process Rust crates and convert them into files easy to handle by program\nverifiers. It is implemented as a custom driver for the rustc compiler.\n\nCharon is, in Greek mythology, an old man carrying the souls of the deceased accross the\nStyx, a river separating the world of the living from the world of the dead. In the\npresent context, Charon allows us to go from the world of Rust programs to the world of\nformal verification.\n\nWe are **open to contributions**! Please contact us so that we can coordinate ourselves,\nif you are willing to contribute. For this purpose you can join the [Zulip](https://aeneas-verif.zulipchat.com/).\n\n## LLBC\nCharon converts MIR code to ULLBC (Unstructured Low-Level Borrow Calculus) then\nto LLBC. Both ASTs can be output by Charon.\n\nULLBC is a slightly simplified MIR, where we try to remove as much redundancies\nas possible. For instance, we drastically simplify the representation of constants coming\nfrom the Rust compiler.\n\nLLBC is ULLBC where we restructured the control-flow with loops, `if\n... then ... else ...`, etc. instead of gotos. Consequently, we merge MIR\nstatements and terminators into a single LLBC statement type. We also perform\nsome additional modifications, some of which are listed below:\n\n**Remark**: most of the transformations which transform the MIR to ULLBC then LLBC are\nimplemented by means of micro-passes. Depending on the need, we could make them optional\nand control them with flags. If you want to know more about the details, see `translate`\nin `src/driver.rs`, which applies the micro-passes one after the other.\n\n**Remark**: if you want to know the full details of (U)LLBC, have a look at: `types.rs`,\n`values.rs`, `expressions.rs`, `ullbc_ast.rs` and `llbc_ast.rs`.\n\nThe extracted AST is serialized in `.ullbc` and `.llbc` files (using the JSON format).\nWe extract a whole crate in one file.\n\n## Project Structure\n\n- `charon`: the Rust implementation.\n- `charon-ml`: the ML library. Provides utilities to retrieve and manipulate\n  the AST in OCaml (deserialization, printing, etc.).\n- `tests` and `tests-polonius`: test files directories. `tests-polonius` contains\n  code which requires the Polonius borrow checker.\n\n## Installation \u0026 Build\n\nYou first need to install [`rustup`](https://www.rust-lang.org/tools/install).\n\nAs Charon is set up with cargo, rustup will automatically download and install the proper\npackages upon building the project. If you only want to build the Rust project (in\n`./charon`), simply run `make build-charon-rust` in the top directory.\n\nIf you also want to build the ML library (in `./charon-ml`), you will need to\ninstall OCaml and the proper dependencies.\n\nWe suggest you to follow those [instructions](https://ocaml.org/docs/install.html),\nand install OPAM on the way (same instructions).\n\nFor Charon-ML, we use **OCaml 4.13.1**: `opam switch create 4.13.1+options`\n\nThe dependencies can be installed with the following command:\n\n```\nopam install ppx_deriving visitors easy_logging zarith yojson core_unix odoc menhir\n```\n\nYou can then run `make build-charon-ml` to build the ML library, or even simply\n`make` to build the whole project (Rust and OCaml). Finally, you can run the\ntests with `make test`.\n\nAlternatively, you can use Nix and do `nix develop` (or use https://direnv.net/ and `direnv allow`)\nand all dependencies should be made available.\n\n## Documentation\n\nYou can access the Rust documentation\n[online](https://aeneasverif.github.io/charon/charon_lib/index.html).\n\nYou can also run `make` to generate the documentation locally.\nIt will generate a documentation accessible from\n[`doc-rust.html`](./doc-rust.html) (for the Rust project) and\n[`doc-ml.html`](./doc-ml.html) (for the ML library).\n\n## Usage\n\nTo run Charon, you should run the Charon binary from *within* the crate that you\nwant to compile, as if you wanted to build the crate with `cargo build`. The\nCharon executable is located at `bin/charon`.\n\nCharon will build the crate and its dependencies, then extract the AST. Charon\nprovides various options and flags to tweak its behaviour: you can display a\ndetailed documentation with `--help`.\nIn particular, you can print the LLBC generated by Charon with `--print-llbc`.\n\nIf there is a `Charon.toml` file at the root of your project, charon will also take options from it.\nThe file supports the same options at the cli interface, except for the options that relate to\ninput/output like `--print-llbc`. Example `Charon.toml`:\n```toml\n[charon]\nextract_opaque_bodies = true\n[rustc]\nflags = [\"--cfg\", \"abc\"]\n```\n\n**Remark**: because Charon is compiled with Rust nigthly (this is a requirement\nto implement a rustc driver), it will build your crate with Rust nightly. You\ncan find the nightly version pinned for Charon in [`rust-toolchain.template`](rust-toolchain.template).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAeneasVerif%2Fcharon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAeneasVerif%2Fcharon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAeneasVerif%2Fcharon/lists"}