inkwell: docs built from master, one of twelve LLVM versions documented, and an explicit request not to use master
It's a New Kind of Wrapper for Exposing LLVM (Safely)
At a glance
- What is it?
- A Rust wrapper around the LLVM C API for people writing their own languages, supporting twelve LLVM major versions through Cargo feature flags, with a doubled feature table that the manifest itself warns must be kept in step with a proc macro. Its documentation site is generated from the branch that may contain breaking changes and covers only the newest supported LLVM.
- Who is it for?
- inkwell fits a team writing a compiler or a JIT in Rust that wants more static typing than the C API gives and accepts a wrapper that must be recompiled when LLVM moves. Four things to check.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 6 days ago.
- What is it written in?
- Mainly Rust, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 22, 2026, and from our analysis. They are not legal advice.
Star history
- TheDan64/inkwell3,052 ★ · +33
| Repository | 2026-09-25 | 2026-11-22 |
|---|---|---|
| TheDan64/inkwell | 3k | 3.1k |
33 Stars in the last 58 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The docs are built from master and document one of twelve LLVM versions
The documentation section is three sentences and each one narrows what you can rely on. The site is deployed automatically from the master branch, so it describes code rather than a release. The README then says the docs are not yet complete, and that they only show the latest supported LLVM version because of a documented rustdoc issue, with an issue link for the details. Since the crate supports LLVM 12 through 23, that means eleven of the twelve supported versions have no published API documentation on the site at all. And because the site tracks the branch the project explicitly says may break, the documentation can describe a state of the API that no released version has. The practical advice is to read the docs for concepts and the compiler's own headers for signatures.
The README asks you not to use master
One sentence in the usage section is the most useful thing in the file, and it is a scope statement rather than a feature. The project says it may make breaking changes on master from time to time because it is still before the first major version, in compliance with semantic versioning rules that allow it, and asks readers to prefer a published release whenever possible. The releases support that: the three newest are minor version bumps in the zero series, dated within the last year, with no major version yet. So the crate has been released regularly, and the instruction is not a warning about neglect. It is a warning that the branch is where the next breaking change is developed, and the version you get from a package registry is the one with a compatibility promise attached.
Twelve version features, twenty-four no-linking variants, and a cargo issue behind them
The manifest lists one Cargo feature per supported LLVM major, named after the version, and you enable exactly one:
[dependencies]
inkwell = { version = "0.10.0", features = ["llvm23-1"] }The feature names follow a stated pattern, a lowercase llvm prefix, the major, a hyphen and the minor, so LLVM 18.1 is llvm18-1. Then each of those twelve has a second sibling feature with a suffix meaning do not link the LLVM libraries, which exists for the case where another dependency in the graph is the one installing LLVM. The manifest explains why there is no single global switch for that: enabling it across every version at once makes the package manager try to download and compile all of them, and it links that to a reported package manager issue. Twenty-four features for one wrapper is a lot of surface, and the comment above them is the reason it is not forty-eight.
The version table exists twice, and the manifest says to keep them in step
Immediately above the version feature list there is a comment addressed to contributors: when adding a new LLVM version, update a matching constant in the internal macros crate. That constant is how the proc macro knows which feature names and which underlying bindings exist, so the feature list in the manifest and a list inside a build-time code generator have to agree. Duplication like that is a normal cost of a wrapper that generates its typed interface, and the difference here is that the project wrote the hazard down in the file rather than leaving it to be discovered. The repository listing explains why the duplication exists: there is an internal macros directory, a build script, a separate source directory and a test directory, which is the shape of a crate whose public API is partly generated at build time rather than written out by hand.
typed-pointers is an empty feature that only the oldest LLVM versions turn on
One feature in the manifest has an empty body and exists purely as a marker, and it is switched on by exactly three of the twelve version features: LLVM 12, 13 and 14. The pattern is the pointer typing change LLVM made when opaque pointers arrived. Older LLVM versions have typed pointers and this crate models them, newer ones do not and the model goes away, so the marker records which side of that change a build is on. It is a tidy piece of metadata: an application that wants to know whether the selected LLVM version predates opaque pointers can look for the marker feature rather than parsing the version number. It is also the kind of feature that becomes misleading once the oldest supported version moves past the change, at which point three of the twelve version features would reference a marker nothing reads.
Its own example keeps unsafe twice and explains both
The example section takes an existing just-in-time compilation sample written against the raw bindings and rewrites it in safe code, then footnotes why two unsafe blocks remain. The first reason is a signature problem: there is no way to verify that the function retrieved from the compiled module is being called with the right signature. The second is the ordinary foreign interface reason: calling that function is unsafe because nothing guarantees the code it points at does not do unsafe things internally, which is exactly why calling into C requires the keyword. That is a better explanation than a wrapper usually gives, because it names the two distinct failure modes rather than one. The example also carries lifetime parameters tying a context, a module, a builder and an execution engine together, which is the shape that makes the interface more strongly typed than the C API in the first place.
One alternative crate is named, and the tutorial is the real second example
The README has a section for alternative crates and it lists exactly one, which is unusual restraint for a project of this age. The examples, by contrast, are two: the rewritten just-in-time sample described above, and the set of tutorial programs that come with LLVM itself, which the README says can be found in the examples directory. The listing confirms both, a single file for the first and a directory for the second. That combination is a reasonable answer to the hardest problem a wrapper has, which is that LLVM's own material teaches the C interface and the wrapper's value is only visible when the same program is written twice. A crate for language implementers is also a rare enough category that naming one alternative is probably the whole useful set.
Editorial conclusion
inkwell fits a team writing a compiler or a JIT in Rust that wants more static typing than the C API gives and accepts a wrapper that must be recompiled when LLVM moves. Four things to check. The crate covers twelve LLVM majors through feature flags, so pick one and pin the crate release. The documentation site is generated from a branch the project warns can break, and documents only the newest LLVM, so do not treat it as the reference for your version. If another dependency installs LLVM for you, use the per-version no-linking features rather than a global one, which the manifest explains cannot exist. And the version table exists in two places, a feature list and a constant in the proc macro, with a comment asking that they be kept in step.
Frequently asked questions
What is inkwell?
A Rust wrapper around the LLVM C API, aimed at people writing their own programming languages. It offers a more strongly typed interface so some errors are caught at compile time rather than inside LLVM at runtime, aiming to reproduce LLVM IR's typing in safe Rust. It is published under the Apache 2.0 licence.
Which LLVM versions does inkwell support?
Twelve, from LLVM 12 through LLVM 23, each selected by a Cargo feature flag named after the major and minor version, and you enable exactly one. The three oldest versions additionally enable a typed-pointers marker feature that newer ones do not.
Should I depend on the master branch of inkwell?
The README says breaking changes may land on master from time to time because the crate is still before its first major version, and asks you to prefer a published release whenever possible. The releases are recent minor bumps in the zero series, so a registry release is the version with a compatibility promise.
Is the inkwell documentation complete?
No. The site is deployed automatically from master, the README says the docs are not yet complete, and they show only the latest supported LLVM version because of a documented rustdoc issue. That leaves eleven of the twelve supported versions without published API documentation there.
Does inkwell remove unsafe code from LLVM bindings?
Not entirely. Its just-in-time example still needs unsafe twice, and the footnote explains both: nothing verifies that a retrieved function is called with the right signature, and calling a function obtained from LLVM is unsafe because the code may do unsafe things internally, the same reason calling into C requires the keyword.
What does inkwell require to build?
Rust 1.85 or newer and one LLVM from version 12 through 23. The manifest uses the 2024 edition and carries a build script, an internal procedural macro crate, a typo checker configuration and a formatter configuration.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/thedan64-inkwell)Star history chart for your README
[](https://hysenlabs.com/projects/thedan64-inkwell)Was this useful?