|
| 1 | +# Extension: kernel-rust |
| 2 | + |
| 3 | +The Linux kernel has been gaining Rust support since version 6.1, with more |
| 4 | +subsystems and drivers being written in Rust alongside traditional C code. |
| 5 | +In the near future, practically useful drivers and subsystems for Armbian users |
| 6 | +are expected to require or benefit from Rust kernel support. Enabling |
| 7 | +`CONFIG_RUST` in the kernel build unlocks this capability. |
| 8 | + |
| 9 | +Without this extension, Armbian kernels are built without Rust support — |
| 10 | +the toolchain is not installed and `CONFIG_RUST` does not appear in |
| 11 | +menuconfig. This extension installs a pinned Rust toolchain via `rustup`, |
| 12 | +enables `CONFIG_RUST` automatically, and configures all required build |
| 13 | +parameters so that Rust kernel modules can be compiled alongside C code. |
| 14 | +The toolchain versions and other aspects of the build can be adjusted via |
| 15 | +[parameters](#parameters) passed to the build system. |
| 16 | + |
| 17 | +## Why rustup instead of distro packages |
| 18 | + |
| 19 | +Distribution-provided Rust packages currently cannot fully satisfy all the |
| 20 | +requirements for enabling Rust in a recent kernel. Mixing some components |
| 21 | +from the distro with others from external sources is fragile and not |
| 22 | +worthwhile. For this reason the extension downloads a complete, version-pinned |
| 23 | +toolchain via `rustup` independently of the host distro. |
| 24 | + |
| 25 | +When the base distro used by the Armbian build system provides packages |
| 26 | +sufficient to build the Rust environment for the latest kernels entirely from |
| 27 | +distro sources, Armbian will likely switch to using them. |
| 28 | + |
| 29 | +## Quick start |
| 30 | + |
| 31 | +```bash |
| 32 | +./compile.sh BOARD=<board> BRANCH=<branch> ENABLE_EXTENSIONS="kernel-rust" |
| 33 | +``` |
| 34 | + |
| 35 | +To open menuconfig with Rust options visible: |
| 36 | + |
| 37 | +```bash |
| 38 | +./compile.sh kernel-config BOARD=<board> BRANCH=<branch> ENABLE_EXTENSIONS="kernel-rust" |
| 39 | +``` |
| 40 | + |
| 41 | +To enable permanently from a userconfig file: |
| 42 | + |
| 43 | +```bash |
| 44 | +enable_extension "kernel-rust" |
| 45 | +``` |
| 46 | + |
| 47 | +## Requirements |
| 48 | + |
| 49 | +- **Kernel version**: 6.12 or newer (requires rustc ≥ 1.78). |
| 50 | +- **Host package**: `libclang-dev` — installed automatically by the extension. |
| 51 | +- **Build host architecture**: x86_64, aarch64, or riscv64. |
| 52 | +- Internet access on first use (downloads rustup-init and toolchain components). |
| 53 | + |
| 54 | +## Parameters |
| 55 | + |
| 56 | +| Variable | Default | Description | |
| 57 | +|---|---|---| |
| 58 | +| **`RUST_VERSION`** | `1.85.0` | rustc version installed via rustup. | |
| 59 | +| **`BINDGEN_VERSION`** | `0.71.1` | `bindgen-cli` version installed via cargo. | |
| 60 | +| **`RUST_KERNEL_SAMPLES`** | `no` | Set to `yes` to build sample Rust kernel modules (`rust_minimal`, `rust_print`, `rust_driver_faux`) as loadable modules. Useful for smoke-testing the toolchain. | |
| 61 | +| **`RUST_EXTRA_COMPONENTS`** | _(empty array)_ | Additional rustup components to install (e.g. `clippy`, `llvm-tools`). | |
| 62 | +| **`RUST_EXTRA_CARGO_CRATES`** | _(empty array)_ | Additional cargo crates to install. Supports `name` or `name@version` syntax. | |
| 63 | + |
| 64 | +## Toolchain cache |
| 65 | + |
| 66 | +The toolchain is installed once into `${SRC}/cache/tools/rustup/` and reused |
| 67 | +across builds. The cache is content-addressed by a hash of: |
| 68 | + |
| 69 | +- `RUST_VERSION` |
| 70 | +- `BINDGEN_VERSION` |
| 71 | +- build host architecture |
| 72 | +- `RUST_EXTRA_COMPONENTS` |
| 73 | +- `RUST_EXTRA_CARGO_CRATES` |
| 74 | + |
| 75 | +Changing any of these values invalidates the cache and triggers a full reinstall |
| 76 | +on the next build. The marker file is `.marker-<hash>` inside the cache directory. |
| 77 | + |
| 78 | +## Extensibility |
| 79 | + |
| 80 | +Other extensions can request additional toolchain components or crates before |
| 81 | +the toolchain is installed: |
| 82 | + |
| 83 | +```bash |
| 84 | +# In your extension file: |
| 85 | +RUST_EXTRA_COMPONENTS+=("clippy" "llvm-tools") |
| 86 | +RUST_EXTRA_CARGO_CRATES+=("mdbook" "cargo-deb@2.11.0") |
| 87 | +``` |
| 88 | + |
| 89 | +## Kernel artifact versioning |
| 90 | + |
| 91 | +The extension adds a short hash of `RUST_VERSION|BINDGEN_VERSION` to the kernel |
| 92 | +artifact version string (key `_R`, e.g. `rust1a2b`). This ensures that changing |
| 93 | +toolchain versions triggers a kernel rebuild even if the kernel source is |
| 94 | +unchanged. |
| 95 | + |
| 96 | +## Implementation notes |
| 97 | + |
| 98 | +### env -i isolation |
| 99 | + |
| 100 | +The kernel build runs under `env -i`, which clears the entire environment. |
| 101 | +The extension passes Rust tool paths directly as make parameters |
| 102 | +(`RUSTC=`, `RUSTFMT=`, `BINDGEN=`) and sets `RUST_LIB_SRC` via the make |
| 103 | +environment array. Direct paths into the toolchain sysroot are used instead |
| 104 | +of rustup proxy binaries, so `RUSTUP_HOME` does not need to be in the |
| 105 | +cleared environment. |
| 106 | + |
| 107 | +### ccache and Rust |
| 108 | + |
| 109 | +ccache does not support rustc (upstream won't-fix since 2019). The kernel |
| 110 | +build system has no `RUSTC_WRAPPER` mechanism, so Rust compilation is not |
| 111 | +cached by ccache. Only C/assembly compilation benefits from ccache when this |
| 112 | +extension is active. |
| 113 | + |
| 114 | +## References |
| 115 | + |
| 116 | +- [Rust in the Linux kernel — quick start](https://docs.kernel.org/rust/quick-start.html) |
| 117 | +- [Rust for Linux — version policy](https://rust-for-linux.com/rust-version-policy) |
| 118 | +- [rustup installation](https://rust-lang.github.io/rustup/installation/index.html) |
0 commit comments