1Cranelift Code Generator 2======================== 3 4**A [Bytecode Alliance][BA] project** 5 6[Website](https://cranelift.dev/) 7 8Cranelift is a low-level retargetable code generator. It translates a 9[target-independent intermediate representation](docs/ir.md) 10into executable machine code. 11 12[BA]: https://bytecodealliance.org/ 13[](https://github.com/bytecodealliance/wasmtime/actions) 14[](https://bytecodealliance.zulipchat.com/#narrow/stream/217117-cranelift/topic/general) 15 16[](https://docs.rs/cranelift) 17 18For more information, see [the documentation](docs/index.md). 19 20For an example of how to use the JIT, see the [JIT Demo], which 21implements a toy language. 22 23[JIT Demo]: https://github.com/bytecodealliance/cranelift-jit-demo 24 25For an example of how to use Cranelift to run WebAssembly code, see 26[Wasmtime], which implements a standalone, embeddable, VM using Cranelift. 27 28[Wasmtime]: https://github.com/bytecodealliance/wasmtime 29 30For various examples of how to use Cranelift to accomplish common compiler 31tasks, see the [Cranelift Examples] repository maintained by @simvux. 32 33[Cranelift Examples]: https://github.com/simvux/cranelift-examples 34 35Status 36------ 37 38Cranelift currently supports enough functionality to run a wide variety 39of programs, including all the functionality needed to execute 40WebAssembly (MVP and various extensions like SIMD), although it needs to be 41used within an external WebAssembly embedding such as Wasmtime to be part of a 42complete WebAssembly implementation. It is also usable as a backend for 43non-WebAssembly use cases: for example, there is an effort to build a [Rust 44compiler backend] using Cranelift. 45 46Cranelift is production-ready, and is used in production in several places, all 47within the context of Wasmtime. It is carefully fuzzed as part of Wasmtime with 48differential comparison against V8 and the executable Wasm spec, and the 49register allocator is separately fuzzed with symbolic verification. There is an 50active effort to formally verify Cranelift's instruction-selection backends. We 51take security seriously and have a [security policy] as a part of Bytecode 52Alliance. 53 54Cranelift has four backends: x86-64, aarch64 (aka ARM64), s390x (aka IBM 55Z) and riscv64. All backends fully support enough functionality for Wasm MVP, and 56x86-64 and aarch64 fully support SIMD as well. On x86-64, Cranelift supports 57both the System V AMD64 ABI calling convention used on many platforms and the 58Windows x64 calling convention. On aarch64, Cranelift supports the standard 59Linux calling convention and also has specific support for macOS (i.e., M1 / 60Apple Silicon). 61 62Cranelift's code quality is within range of competitiveness to browser JIT 63engines' optimizing tiers. A [recent paper] includes third-party benchmarks of 64Cranelift, driven by Wasmtime, against V8 and an LLVM-based Wasm engine, WAVM 65(Fig 22). The speed of Cranelift's generated code is ~2% slower than that of 66V8 (TurboFan), and ~14% slower than WAVM (LLVM). Its compilation speed, in the 67same paper, is measured as approximately an order of magnitude faster than WAVM 68(LLVM). We continue to work to improve both measures. 69 70[Rust compiler backend]: https://github.com/rust-lang/rustc_codegen_cranelift 71[security policy]: https://bytecodealliance.org/security 72[recent paper]: https://arxiv.org/abs/2011.13127 73 74The core codegen crates have minimal dependencies and are carefully written to 75handle malicious or arbitrary compiler input: in particular, they do not use 76callstack recursion. 77 78Cranelift performs some basic mitigations for Spectre attacks on heap bounds 79checks, table bounds checks, and indirect branch bounds checks; see 80[#1032] for more. 81 82[#1032]: https://github.com/bytecodealliance/wasmtime/issues/1032 83 84Cranelift's APIs are not yet considered stable, though we do follow 85semantic-versioning (semver) with minor-version patch releases. 86 87Cranelift generally requires the latest stable Rust to build as a policy, and 88is tested as such, but we can incorporate fixes for compilation with older Rust 89versions on a best-effort basis. 90 91Contributing 92------------ 93 94If you're interested in contributing to Cranelift: thank you! We have a 95[contributing guide] which will help you getting involved in the Cranelift 96project. 97 98[contributing guide]: https://bytecodealliance.github.io/wasmtime/contributing.html 99 100Planned uses 101------------ 102 103Cranelift is designed to be a code generator for WebAssembly, but it is 104general enough to be useful elsewhere too. The initial planned uses that 105affected its design were: 106 107- [Wasmtime non-Web wasm engine](https://github.com/bytecodealliance/wasmtime). 108- [Debug build backend for the Rust compiler](rustc.md). 109- WebAssembly compiler for the SpiderMonkey engine in Firefox 110 (currently not planned anymore; SpiderMonkey team may re-assess in 111 the future). 112- Backend for the IonMonkey JavaScript JIT compiler in Firefox 113 (currently not planned anymore; SpiderMonkey team may re-assess in 114 the future). 115 116Building Cranelift 117------------------ 118 119Cranelift uses a [conventional Cargo build 120process](https://doc.rust-lang.org/cargo/guide/working-on-an-existing-project.html). 121 122Cranelift consists of a collection of crates, and uses a [Cargo 123Workspace](https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html), 124so for some cargo commands, such as `cargo test`, the `--all` is needed 125to tell cargo to visit all of the crates. 126 127`test-all.sh` at the top level is a script which runs all the cargo 128tests and also performs code format, lint, and documentation checks. 129 130<details> 131<summary>Log configuration</summary> 132 133Cranelift uses the `log` crate to log messages at various levels. It doesn't 134specify any maximal logging level, so embedders can choose what it should be; 135however, this can have an impact of Cranelift's code size. You can use `log` 136features to reduce the maximum logging level. For instance if you want to limit 137the level of logging to `warn` messages and above in release mode: 138 139``` 140[dependency.log] 141... 142features = ["release_max_level_warn"] 143``` 144</details> 145 146Editor Support 147-------------- 148 149Editor support for working with Cranelift IR (clif) files: 150 151 - Vim: https://github.com/bytecodealliance/cranelift.vim 152
){kind=link}
){kind=link}
){kind=link}
){kind=link}