src/autodiff/installation.md

# Installation

Most users can enable `std::autodiff` on their latest nightly toolchain by installing the `enzyme` component with rustup, if they are using one of these platforms:

- **Linux**: with `x86_64-unknown-linux-gnu` or `aarch64-unknown-linux-gnu`
- **macOS**: with `aarch64-apple-darwin` or `x86_64-apple-darwin`
- **Windows**: with `x86_64-llvm-mingw` or `aarch64-llvm-mingw`

As a rustc/enzyme/autodiff contributor, or if you need any other platform, you can build rustc including autodiff from source.
Please open an issue if you want help enabling automatic builds for your preferred target.

## Installation guide

If you want to use `std::autodiff` on Linux, macOS, or Windows and don't plan to contribute PR's to the project, then we recommend to just use your existing nightly installation and download the missing component.
Please run:

```console
rustup +nightly component add enzyme
```

Older rustup versions are not aware of this component, so if you run into issues try updating rustup itself:
```console
rustup self update
rustup +nightly component add enzyme
```

## Installation guide for Nix

On [Nix], you can declare a nightly Rust toolchain with the Enzyme component using the [oxalica rust-overlay].

For example:

```nix
rust-bin.selectLatestNightlyWith (toolchain: toolchain.default.override {
  extensions = [ "enzyme" ];
})
```

Alternatively, you can create a [toolchain file] that declares the Enzyme component such as

```toml
[toolchain]
channel = "nightly-2026-06-23"
components = [ "enzyme" ]
```

and consume it in the overlay

```nix
rust-bin.fromRustupToolchainFile ./rust-toolchain.toml
```

## Build instructions

First you need to clone and configure the Rust repository.
Based on your preferences, you might also want to `--enable-clang` or `--enable-lld`.
```console
git clone git@github.com:rust-lang/rust
cd rust
./configure --release-channel=nightly --enable-llvm-enzyme --enable-llvm-link-shared --enable-llvm-assertions --enable-ninja --enable-option-checking --disable-docs --set llvm.download-ci-llvm=false
```

Afterwards you can build rustc using:
```console
./x build --stage 1 library
```

Afterwards rustc toolchain link will allow you to use it through cargo:
```console
rustup toolchain link enzyme build/host/stage1
rustup toolchain install nightly # enables -Z unstable-options
```

You can then run our test cases:

```console
./x test --stage 1 tests/codegen-llvm/autodiff
./x test --stage 1 tests/pretty/autodiff
./x test --stage 1 tests/ui/autodiff
./x test --stage 1 tests/run-make/autodiff
./x test --stage 1 tests/ui/feature-gates/feature-gate-autodiff.rs
```

Autodiff is still experimental, so if you want to use it in your own projects, you will need to add `lto="fat"` to your Cargo.toml
and use `RUSTFLAGS="-Zautodiff=Enable" cargo +enzyme` instead of `cargo` or `cargo +nightly`.

## Compiler Explorer and dist builds

Our compiler explorer instance can be updated to a newer rustc in a similar way.
First, prepare a docker instance.
```console
docker run -it ubuntu:22.04
export CC=clang CXX=clang++
apt update
apt install wget vim python3 git curl libssl-dev pkg-config lld ninja-build cmake clang build-essential
```
Then build rustc in a slightly altered way:
```console
git clone https://github.com/rust-lang/rust
cd rust
./configure --release-channel=nightly --enable-llvm-enzyme --enable-llvm-link-shared --enable-llvm-assertions --enable-ninja --enable-option-checking --disable-docs --set llvm.download-ci-llvm=false
./x dist
```
We then copy the tarball to our host.
The dockerid is the newest entry under `docker ps -a`.
```console
docker cp <dockerid>:/rust/build/dist/rust-nightly-x86_64-unknown-linux-gnu.tar.gz rust-nightly-x86_64-unknown-linux-gnu.tar.gz
```
Afterwards we can create a new (pre-release) tag on the EnzymeAD/rust repository and make a PR against the EnzymeAD/enzyme-explorer repository to update the tag.
Remember to ping `tgymnich` on the PR to run his update script.
Note: We should archive EnzymeAD/rust and update the instructions here.
The explorer should soon be able to get the rustc toolchain from the official rust servers.


## Build instruction for Enzyme itself

Following the Rust build instruction above will build LLVMEnzyme, LLDEnzyme, and ClangEnzyme along with the Rust compiler.
We recommend that approach, if you just want to use any of them and have no experience with cmake.
However, if you prefer to just build Enzyme without Rust, then these instructions might help.

```console
git clone git@github.com:llvm/llvm-project
cd llvm-project
mkdir build
cd build
cmake -G Ninja ../llvm -DLLVM_TARGETS_TO_BUILD="host" -DLLVM_ENABLE_ASSERTIONS=ON -DLLVM_ENABLE_PROJECTS="clang;lld" -DLLVM_ENABLE_RUNTIMES="openmp" -DLLVM_ENABLE_PLUGINS=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=.
ninja
ninja install
```
This gives you a working LLVM build, now we can continue with building Enzyme.
Leave the `llvm-project` folder, and execute the following commands:
```console
git clone git@github.com:EnzymeAD/Enzyme
cd Enzyme/enzyme
mkdir build
cd build
cmake .. -G Ninja -DLLVM_DIR=<YourLocalPath>/llvm-project/build/lib/cmake/llvm/ -DLLVM_EXTERNAL_LIT=<YourLocalPath>/llvm-project/llvm/utils/lit/lit.py -DCMAKE_BUILD_TYPE=Release -DCMAKE_EXPORT_COMPILE_COMMANDS=YES -DBUILD_SHARED_LIBS=ON
ninja
```
This will build Enzyme, and you can find it in `Enzyme/enzyme/build/lib/<LLD/Clang/LLVM/lib>Enzyme.so`.
(Endings might differ based on your OS).

[`Repo`]: https://github.com/rust-lang/rust/
[Nix]: https://nixos.org/
[oxalica rust-overlay]: https://github.com/oxalica/rust-overlay
[toolchain file]: https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file