Skip to content
project-llzkPublic

About

LLZK's Rust SDK

Resources

Stars

12 stars

Watchers

8 watching

Forks

Repository files navigation

Rust bindings for LLZK.

Warning

These crates are under active development and things may change unexpectedly.

Rust bindings for LLZK over its C API. The bindings' API is meant to be more user friendly than the raw C API and more idiomatic. Its design is heavily inspired by melior and depends on it for handling the MLIR parts that are not specific to LLZK.

The primary supported use case of these bindings is creating IR and running passes on it. Support for other things, such as writing custom passes, is limited and not as ergonomic as it is in C++.

Usage

Run cargo doc -p llzk to generate the API documentation of the rust API and you can visit LLZK's documentation for more information about the IR itself. For the high-level usage of the bindings you can check the examples in llzk/examples.

Optional features

We include some optional functionality guarded by feature flags. We currently have the following features:

Manual installation

Prerequisites

Install LLVM 23 and note the installation path. While building your project the build scripts will look for LLVM using llvm-config. If you don't have that tool in your PATH or it doesn't point to an LLVM 23 installation set the following environment variables to the path where LLVM is installed and the build scripts will then use $MLIR_SYS_230_PREFIX/bin/llvm-config instead.

export MLIR_SYS_230_PREFIX=/path/to/llvm/23/
export TABLEGEN_230_PREFIX=/path/to/llvm/23/

Building LLZK

Clone the LLZK library and build it:

If you want to run LLZK's tests when building, you also need lit (LLVM's test runner):

pip install lit
git clone https://github.com/project-llzk/llzk-lib.git
cmake -B llzk-lib/out/build -S llzk-lib \
  -DCMAKE_INSTALL_PREFIX=$(pwd)/llzk-lib/out \
  -DCMAKE_PREFIX_PATH="$MLIR_SYS_230_PREFIX"
cmake --build llzk-lib/out/build
cmake --install llzk-lib/out/build

Then set the LLZK_SYS_30_PREFIX environment variable to point to the install location:

export LLZK_SYS_30_PREFIX=/path/to/llzk-lib/out

Adding the crates to your project

In your rust project, add the crates to your Cargo.toml:

[dependencies]
llzk-sys = { git = "https://github.com/project-llzk/llzk-rs" }
llzk = { git = "https://github.com/project-llzk/llzk-rs" }

Bindgen compatibility patch

Until bindgen releases the syn/prettyplease compatibility fix, downstream projects must add this patch to their workspace's root Cargo.toml:

[patch.crates-io]
bindgen = { git = "https://github.com/tamird/rust-bindgen", rev = "86a8a5e774b5c4fcab9f86caa2767549dec2a97e" }

For an existing project, update bindgen and commit the resulting Cargo.lock:

cargo update -p bindgen@0.73.2

Building tips

If you are using homebrew in macos you can access MLIR 23 by installing llvm@23 with homebrew. Setting the following environment variables configures the build system with the correct versions of MLIR and its dependencies. Depending on the version of your default C++ compiler you may need to set CXX and CC to a compiler that supports C++ 20.

export MLIR_SYS_230_PREFIX=$(brew --prefix llvm@23)
export TABLEGEN_230_PREFIX=$(brew --prefix llvm@23)
export LIBCLANG_PATH=$(brew --prefix llvm@23)/lib
export CXX=clang++
export CC=clang
export RUSTFLAGS='-L /opt/homebrew/lib/'

See llzk-sys's README for more details on setting up the build environment.

Nix installation

We also include a nix flake that creates an environment with the right versions of LLVM, MLIR, and LLZK. All dependencies are pinned in flake.lock and set up automatically. If you are already using nix, this may be your preferred method.

You can use this flake for configuring your development environment. For example, to work within a nix developer shell you can use the following command.

nix develop 'github:project-llzk/llzk-rs#llzk-rs'

Another alternative is to use direnv with the following .envrc to automatically enter the developer environment when you enter your project's directory.

if ! has nix_direnv_version || ! nix_direnv_version 3.0.4; then
  source_url "https://raw.githubusercontent.com/nix-community/nix-direnv/3.0.4/direnvrc" "sha256-DzlYZ33mWF/Gs8DDeyjr8mnVmQGx7ASYqA5WlxwvBG4="
fi

use flake 'github:project-llzk/llzk-rs#llzk-rs'

Updating LLZK

Mmanual installation

If you need to update the llzk-lib dependency, pull the latest changes from the llzk-lib repository and rebuild it.

Nix installation

To update the llzk-lib dependency run nix flake update llzk-lib

About

LLZK's Rust SDK

Resources

Stars

12 stars

Watchers

8 watching

Forks

Releases

Packages

Used by

Contributors

Languages