melior: Rust bindings for the MLIR compiler infrastructure

What it is

Melior is the MLIR bindings for Rust, and it aims to provide a simple, safe, and complete API for the multi-level intermediate representation with a reasonably sane ownership model represented by the type system in Rust. The crate is a wrapper of the MLIR C interface.

Those three adjectives, simple, safe and complete, are a specification and also a set of tensions. Simple and safe pull in one direction, and complete pulls in the other. A wrapper that is complete has to expose everything the C interface exposes, including the parts where the C interface is loose with lifetimes and the parts where it hands back references to objects that may be moved or destroyed. A wrapper that is safe has to hide or refuse those. You cannot have all three without either making the wrapper huge with unsafe escape hatches, or making it small and leaving gaps.

The readme is honest about where this project has landed, and it does that in a way that is worth reading before you depend on it. The contribution section says the project is still at the alpha stage, as is the C interface it wraps, and that the API is unstable and can have breaking changes in the future. That is a much better position to be in than a wrapper that claims stability it does not have, because a developer who knows the API will move can plan for it.

The name is a joke and a good one. The C interface is a large and somewhat baroque thing, and a Rust binding to it is a substantial undertaking; the project calls itself the rustic bindings, and the Rust community has a tradition of naming things after either a farm animal or a beverage.

The implementation is Rust, the licence is the permissive Apache 2.0, and the repository is organised as a workspace with two members: the binding crate itself and a macro crate, which is the conventional arrangement for a project that needs to generate a lot of repetitive code.

The published documentation is on the project's own pages, and the version numbers in the manifest show a project on a rapid release cadence, which is consistent with wrapping an interface that itself changes every few months.

The example, and what it reveals

The readme's example builds a function that adds two integers, and it is worth reading closely even if you never write a compiler, because it shows the shape of the whole interface in forty lines.

The first move is the dialect registry. A registry is created, every dialect is registered into it, and then that registry is appended to a context and every available dialect is loaded. The dialects are the extensible vocabularies of the representation: arithmetic operations, function definitions, and so on, each one contributed by somebody and each one with its own operations and types.

Then the context, which owns the dialect registry and the loaded dialects and everything else that lives for the duration of a compilation. The location, which is where an operation is considered to have come from, is created as unknown, meaning no particular source position. The module is created, and a module is the top-level container of the representation.

Then the function. Its name is a string attribute, its type is a function type attribute, and its body is a region containing a block. The block has two arguments, both of the index type, and inside it the arithmetic dialect's integer addition operation takes the two arguments and produces a sum, and a return operation hands the sum back.

And then the assertion that the module verifies, which is the point of the whole exercise. The representation has a verifier, and this is the call that asks the library to check that what you just built is well formed.

What the example teaches is that the binding is close to one to one with the C interface. The concepts are the C interface's concepts, in the C interface's order, with the C interface's builders. The function that creates a function operation takes a context, a name, a type, a region, some attributes, and a location, and the region has to be built before it can be passed in, which is a consequence of the C interface's ownership rules rather than a choice.

There is a notable ergonomic detail in the example: the result of the addition operation is fetched by index, and the block's arguments are fetched by index, and both fetches can fail, which the example unwraps. That is the C interface's shape showing through, because in the C interface an operation's results are a list you index into, and there is no guarantee that a result exists.

The technical notes: borrowing, and one string encoding

The technical notes section is three bullets long, and the first one is the design decision the whole project is about.

The library always uses a shared reference to MLIR objects rather than a mutable one, and the stated reason is to mitigate the intricacy of representing a loose ownership model of the C interface in Rust.

That is the crux. The C interface's ownership model is loose in a specific way: an operation owns its regions, a region owns its blocks, a block owns its operations, and an operation owns its operands and results, but the interface lets you reach a child and hold a pointer to it, and it lets you move an operation from one container to another while a pointer to it exists somewhere. In C that is fine, because the programmer is responsible. In Rust, an exclusive borrow of the parent would prevent the mutation that moves the child, and a shared borrow would let the child be mutated behind the borrower's back, which the type system would be happy with and the program would not.

So the library takes the conservative option: shared borrows everywhere. The consequence is that you cannot mutate an object through a shared reference, which pushes a lot of the mutation into the constructors, where the object is being built and no alias can exist yet. That is exactly what the example shows: every operation is created and appended in one step, and the intermediate values are moved rather than modified.

The second note is that only UTF-8 is supported as a string encoding, and the third is that most of the string conversion between the two languages is cached internally.

The second one is a real restriction, and it is worth understanding why it is the right one. The C interface's string attributes are byte sequences, and the interface does not require them to be valid in any particular encoding. A Rust string is UTF-8 by definition, so a binding that accepted arbitrary bytes would either have to represent them as a byte vector, which loses the string methods, or decode them, which can fail. Restricting to UTF-8 means the Rust side is a genuine string and the conversion cannot fail.

The third note is the interesting one in practice, because the conversion between a Rust string and a C string is not free. Every attribute name, every function name, every location string goes through it. Caching the conversion internally means that a name used a thousand times in a compilation is converted once, which is the difference between a binding that is usable on a large module and one that is not.

The naming rules, and why they are written down

The naming conventions section is four rules long, and it exists because the binding's names are derived mechanically from the C interface's names.

Objects that come across the C interface as a type with a prefix are renamed according to whether they have a destructor. If they do not, the name is the bare thing. If they do, the owned version gets the plain name and the borrowed reference gets the same name with a reference suffix.

The second rule covers the creation functions: the C interface's constructor becomes the type's associated constructor in Rust. That is the conventional Rust spelling, and it means the C documentation and the Rust documentation line up: if you know the C function's name, you know the Rust one's.

The third rule is the more interesting one. The C interface has a family of accessor functions that get one thing from another. In the binding, if the result refers to the receiver, the function is named to say that it is a view of the receiver, with an explicit prefix. Otherwise, it is named as a plain method, and it may take arguments, such as a position index.

The distinction is not cosmetic. A method that returns a view of the receiver has a lifetime tied to the receiver, and the Rust compiler enforces that. A method that returns something owned, or something indexed, has no such tie, and naming it differently is how you tell a reader which kind of method they are looking at before they try to use it.

The fourth rule is that the C interface's name, with its prefix, is what the Rust name is derived from. So the mapping is entirely predictable, and a reader with the C documentation open can find the Rust function without searching.

This is the single most useful thing the readme does for a binding project, and it is worth contrasting with the alternative. A wrapper that renamed things for taste would be nicer to use and impossible to look up. A wrapper that mirrors the C names is slightly awkward and instantly learnable, because the C interface's documentation is a large body of prose that already answers most of the questions a binding user will have.

The safety section

The safety section is the part of the readme that makes this project worth reading, and it has an unusual structure: it states the holes, explains why they exist, and then gives a plan for closing each one.

The first hole is about dialects. Access to operations, types, or attributes that belong to dialects not loaded in a context can lead to runtime errors, or segmentation faults in the worst case.

That is a real hazard and it is inherent to the C interface. Dialects are loaded into a context, and a dialect that is not loaded has no operations registered, so asking for one produces a null handle that the C code then dereferences. The fix plan is to load all dialects by default when a context is created, and to provide unsafe constructors of contexts for the advanced users who want control over the registry. That is a good plan, because the default becomes the safe path and the exception becomes explicit.

The second hole is about invalidation. IR object references returned from functions that move ownership of arguments might get invalidated later, and the reason given is that the library needs to borrow the receiver rather than mutably borrow it in order to return such references. The example given is appending a block to a region.

Think about what that call does: it takes a block by value and moves it into the region, and the block's operations live inside the block, and the block now lives inside the region. A reference to an operation inside that block was obtained before the move, and after the move the memory may be in a different place, and the reference may be dangling. The C interface does not care, because in C a pointer is a pointer. In Rust, the same operation needs either a mutable borrow of the region, which would prevent the move, or a shared borrow, which permits the move and invalidates the reference.

The fix plan is to use a dynamic check, such as a reference-counted cell, for the objects, so that the mutation is detected at run time rather than assumed to be safe.

And the framing is what makes this section good. The readme says the library aims to be completely type safe and then immediately says that some parts of the current API are not. That is a project telling you the truth about its own edges, which is exactly what you need in order to decide how much to trust it in a build step that might crash your compiler.

The packaging, and the dependency you cannot avoid

The install is a package manager command, and then there is the part that makes this different from an ordinary crate.

The compiler infrastructure of version twenty-three has to be installed on your system, and the readme points at the release and says that on Linux and the Mac it can be installed through a package manager, with the command given.

brew install llvm@23

That is the whole dependency story, and it is a significant one. The binding is not self-contained, because the thing it binds is a large C library with its own build, its own version numbering, and its own release cadence. So a Rust program that uses this crate carries a dependency on a particular version of a C library, which is the situation that the ecosystem has been trying to solve for a decade and has not.

The version in the manifest is a zero point twenty-eight, and the language edition is a recent one, and the workspace uses the newest dependency resolver. Those are the numbers of a young project on a fast release cadence, which is exactly what you would expect for a binding to a rapidly moving interface.

The repository layout supports that reading. There is a source directory for the crate, a separate directory for the macro crate, and a tools directory, which is where the code generation lives, since a binding of this size cannot have its repetitive parts written by hand. There is a toolchain file, which pins the exact compiler used for the build so that the generated code and the crate agree. There is a formatting configuration, so the generated code and the hand written code are formatted the same way. And there is a spell checker configuration, which for a project that generates a large number of names pulled from the C interface's documentation is a practical necessity rather than a nicety.

And there is a credit that explains the design. The raw C binding generation depends on a separate project that generates the raw bindings, and the overall design of the safe wrapper is inspired by an existing Rust binding for the same underlying library, which was written for a different language binding library. So the lineage is: a raw binding generator, an existing safe wrapper in another binding framework, and this project, which took the ideas of the second and reimplemented them in Rust's idiom.

The result is a project that is simultaneously a binding, a design document, and an argument that the loose ownership model of a large C interface can be made to sit inside Rust's type system without giving up completeness.

Editorial conclusion

melior fits a Rust developer building a compiler, a dialect, or a pass over the multi-level representation, who wants the ergonomics of Rust without writing the raw interface bindings by hand. It does not fit somebody who needs a stable API today, because the project says plainly that it is at the alpha stage and that breaking changes are expected. Verify first that the version of the compiler infrastructure you have installed matches the version the crate targets, since the crate is a wrapper around a C interface that changes with every release, that you can live with the dependency model of a build-time and a system library, and that the parts of the interface you need are the parts the wrapper has reached, because the C interface is much larger than any binding covers.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. mlir-rs/melior on GitHub
4. Project website
5. README