Repository files navigation

[dependencies]llvm-sys ="221.0.0"

There must be a compatible version of LLVM available. By defaultllvm-syswill look forllvm-config onPATH to find a system-wide copy of LLVM anduse that if it is a compatible version. Custom options for finding LLVMon your system can be specified via environment variables. SeeLLVM compatibility for more information.

See theexamples directory in this repository for API examples. There alsoexist some other projects using these bindings which may beinformative or useful:

• Safe, "Rusty" APIs for using LLVM:
  • Inkwell
  • llvm-ir
• Tari's merthc
• Wilfred's BF compiler
• Jay Phelps wrote aboutbuilding a minimal compiler targetingWebAssembly
  • Lyle extended this for arm64 using clang
• Lyle wrote a small PoC compiler Calculon using LLVM with LALRPOP

Most of the interfaces are not documented in these bindings. Refer to theLLVM documentation for more information, particularlythegenerated API documentation.

If you have your own project using these bindings that you think is worthmentioning here, by all means let me know.

This crate provides a few feature flags that can be important to particularuses. These are mostly useful only at build-time; If you encounter problemsbuilding something that depends on llvm-sys, enabling one or more option may beuseful; for example:

cargo build --features=llvm-sys/prefer-dynamic

Most crates that depend on llvm-sys should not automatically enable any of thesefeatures, because the appropriateness of any given option usually depends on theconfiguration of the system on which the library is being compiled.

• Dynamic/static linking preferencesprefer-dynamic,force-dynamic,prefer-static,force-static. Only one may be specified, indicating howLLVM should be linked. If none are enabled,prefer-static is assumed.(Prior to crate version191, the default linking behavior isforce-static.)

  With dynamic linking, the crate will link against a LLVM shared library(a .dll on Windows, .so on Linux and so forth) which must be available atruntime; static linking instead uses a static library archive (.lib onWindows or .a on most Unix-like systems) that includes all of the librarycode in the final binary (increasing file size but eliminating any dependencyon additional files to run the program).

  If aprefer- option is enabled, the crate will attempt to use the specifiedkind of linking (static or dynamic) but fall back to the other if the firstkind is unavailable. Setting aforce- option will attempt only to do thespecified kind of linking and fail otherwise.

• strict-versioning: causes the build to fail if a version of LLVM exactlymatching the current crate version is not found. If enabled, linking crateversion 150.1.0 against LLVM 16.0 (for example) would fail whereas it isnormally permitted.

  This may be useful if there is known to be an incompatibility between someLLVM versions, causing the build to fail rather than possibly causing errorsat runtime.

• disable-alltargets-init: disable building the functions that initializeLLVM components for all supported targets. These functions need to becompiled from C, so if they are unneeded then turning them off can allowthe build to proceed if a working C compiler is unavailable.

• no-llvm-linking: prevents llvm-sys from instructing the compiler to linkagainst any LLVM libraries. This can be useful if another crate links LLVM insome different way (preventing conflicts) but means the other crate mustensure llvm-sys' library requirements are satisfied.

llvm-sys requires a copy ofllvm-config corresponding to the desired version ofLLVM to build:llvm-config allows it to probe what libraries need to be linkedand what compiler options are required.

Binary distributions of LLVM (including the official release packages) generallydo not include a copy ofllvm-config, making them unsuited to use for buildingprograms withllvm-sys. Known exceptions (thatdo include a copy ofllvm-config)include:

• Official Debian/Ubuntu packages fromapt.llvm.org
• Fedora/Red Hat'sllvm-devel package
• Arch Linux'sllvm package

If a suitable binary package is not available for your platform, compiling fromsource is usually the best option. SeeCompiling LLVM in this documentfor details.

It may be difficult or even impossible to provide a compatible LLVM versionsystem-wide for a given project (consider a program using two libraries thatinternally use different versions of LLVM!) so environment variables can be setto help the build scripts find your copy of the libraries. This is also helpfulif you are unable to provide a system-wide version of LLVM but can stillcompile it yourself.

LLVM_SYS_<version>_PREFIX specifies the install prefix for a compiled andinstalled copy of the libraries, where<version> is the major version ofllvm-sys (for example,LLVM_SYS_221_PREFIX). The llvm-sys build scriptswill look for allvm-config binary in the directory<PREFIX>/bin/ inaddition to searching for a copy on$PATH, and verify that the LLVM versionreported byllvm-config is compatible with the current crate version.

Because the LLVM CAPI stability guarantees are relativelyweak, this crate enforces that the LLVM release in use match the one it was madefor. The crate version is constructed by treating the LLVM version as a realnumber and multiplying by 10, ignoring any fractional part. Thusllvm-sysversion 191 is compatible with LLVM 19.1.x, andllvm-sys 201 would be compatiblewith LLVM 20.1.x.

The build scripts will not enforce this compatibility matrix strictly,permitting compilation against any version of LLVM that is at least as new asthe crate target version. This is safe in most cases because the LLVM C API ismeant to maintain binary compatibility across releases with the exception ofwhen functions are deprecated and later removed. An incompatible LLVM versionwill generally fail to compile with a link-time error, rather than cause runtimeerrors. Where versions are known to break binary compatibility, the build scriptwill prevent compilation.

Depending on your use of the C API, your program may require that only aversion of LLVM exactly matching your crate version be allowed. This can be setwith the cargo feature flagstrict-versioning or by setting the environmentvariableLLVM_SYS_<version>_STRICT_VERSIONING (where<version> is the targetcrate version) to any value.

llvm-sys blocklists some versions of LLVM that are known to bebinary-incompatible. If you're feeling lucky, settingLLVM_SYS_<version>_IGNORE_BLOCKLIST to "YES" will permit the use ofblocklisted library versions (which may cause vexing bugs).

This crate declares that it links tollvm-<MAJOR VERSION>, not justllvm.This makes it possible to declare a crate that depends on multipleversions ofllvm-sys (corresponding to different versions of LLVM) as long asonly one of them is actually used:

llvm-sys-191 = {package ="llvm-sys",version ="191",optional =true }llvm-sys-201 = {package ="llvm-sys",version ="201",optional =true }

This requires that the target LLVM version (llvm-20 for instance) be declaredas the linking target rather than justllvm because Cargo requires that alllinked libraries be unique regardless of what is actually enabled. Note thatalthough Cargo will not prevent you from enabling multiple versions of LLVM atonce as a result, doing so will likely cause errors at link time.

If you need to compile LLVM or manage multiple versions,llvmenv may simplify the process. Considerusing it if you don't have special requirements or previous experience withLLVM!

While thegetting started guide isthe official guide to compiling LLVM, this section will attempt to provideminimum guidance in creating usable libraries. If you encounter problems, referto the official documentation.

Download and unpack a copy of the source for the required version.

wget https://github.com/llvm/llvm-project/archive/refs/tags/llvmorg-20.1.0-rc1.tar.gztar xJf llvmorg-20.1.0-rc1.tar.xz

Note that you do not need to compile Clang or the test suite.

Configure the build usingCMake (you will need a copy of CMakeinstalled).

mkdir -p llvm-3.9.0.src/buildcd llvm-3.9.0.src/buildcmake .. -DCMAKE_INSTALL_PREFIX=$HOME/llvm-3.9.0

Some of the useful options that can be specified at configuration-time(via-D passed to CMake):

• CMAKE_INSTALL_PREFIX sets the location to install everything in the installstep (later). In the above example this is under your home directory.
• CMAKE_BUILD_TYPE specifies the build mode, one of Debug, Release,MinSizeRel or RelWithDebInfo. Unless you plan to debug LLVM itself,Release or MinSizeRel is probably a good choice.
• LLVM_ENABLE_ASSERTIONS enables internal sanity checks, highly recommendedwhen writing and debugging your own program that uses LLVM because it candetect many usage errors that could otherwise result in hard-to-debugcrashes.

Passing-G <generator> to CMake will make it use a different build system, butby default it will select one appropriate to your system. If you haveninja available, it is recommended due to its speed (-G Ninja).

cmake --build. --target install

This will automatically invoke the build system and copy binaries into theprefix specified at configuration-time when done.Some build tools (like Visual Studio on Windows) support all configurationsconcurrently so you also need to specify the build type (which defaults to Debugon Windows), adding an option like--config MinSizeRel to this invocation ofcmake.

After building and installing via CMake, you can compile llvm-sys against it.

cd your/crate/pathLLVM_SYS_39_PREFIX=$HOME/llvm-3.9.0 cargo build

You must use a version of Rust that uses the same compiler as you build LLVMwith, either MSVC or MinGW. Fortunately, a mismatch like this will cause errorsat compile-time when llvm-config provides options which are supported by onlyone of them, so if you're using the other it will cause the build to fail.

Will theoretically work, but hasn't been tested. Let us know if you try.