Something went wrong. Try again.
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Something went wrong. Try again.
11 kB · 354 lines
at master
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355.. SPDX-License-Identifier: GPL-2.0
Quick Start===========
This document describes how to get started with kernel development in Rust.
There are a few ways to install a Rust toolchain needed for kernel development.A simple way is to use the packages from your Linux distribution if they aresuitable -- the first section below explains this approach. An advantage of thisapproach is that, typically, the distribution will match the LLVM used by Rustand Clang.
Another way is using the prebuilt stable versions of LLVM+Rust provided on`kernel.org <https://kernel.org/pub/tools/llvm/rust/>`_. These are the same slimand fast LLVM toolchains from :ref:`Getting LLVM <getting_llvm>` with versionsof Rust added to them that Rust for Linux supports. Two sets are provided: the"latest LLVM" and "matching LLVM" (please see the link for more information).
Alternatively, the next two "Requirements" sections explain each component andhow to install them through ``rustup``, the standalone installers from Rustand/or building them.
The rest of the document explains other aspects on how to get started.
Distributions-------------
Arch Linux**********
Arch Linux provides recent Rust releases and thus it should generally work outof the box, e.g.::
pacman -S rust rust-src rust-bindgen
Debian******
Debian 13 (Trixie), as well as Testing and Debian Unstable (Sid) provide recentRust releases and thus they should generally work out of the box, e.g.::
apt install rustc rust-src bindgen rustfmt rust-clippy
Fedora Linux************
Fedora Linux provides recent Rust releases and thus it should generally work outof the box, e.g.::
dnf install rust rust-src bindgen-cli rustfmt clippy
Gentoo Linux************
Gentoo Linux provides recent Rust releases and thus it should generally work outof the box, e.g.::
USE='rust-src rustfmt clippy' emerge dev-lang/rust dev-util/bindgen
``LIBCLANG_PATH`` may need to be set.
Nix***
Nix provides recent Rust releases and thus it should generally work out of thebox, e.g.::
{ pkgs ? import <nixpkgs> {} }: pkgs.mkShell { nativeBuildInputs = with pkgs; [ rustc rust-bindgen rustfmt clippy ]; RUST_LIB_SRC = "${pkgs.rust.packages.stable.rustPlatform.rustLibSrc}"; }
openSUSE********
openSUSE Slowroll and openSUSE Tumbleweed provide recent Rust releases and thusthey should generally work out of the box, e.g.::
zypper install rust rust-src rust-bindgen clang
Ubuntu******
Ubuntu 25.10 and 26.04 LTS provide recent Rust releases and thus they shouldgenerally work out of the box, e.g.::
apt install rustc rust-src bindgen rustfmt rust-clippy
In addition, ``RUST_LIB_SRC`` needs to be set, e.g.::
RUST_LIB_SRC=/usr/src/rustc-$(rustc --version | cut -d' ' -f2)/library
For convenience, ``RUST_LIB_SRC`` can be exported to the global environment.
24.04 LTS and older~~~~~~~~~~~~~~~~~~~
Though Ubuntu 24.04 LTS and older versions still provide recent Rustreleases, they require some additional configuration to be set, usingthe versioned packages, e.g.::
apt install rustc-1.85 rust-1.85-src bindgen-0.71 rustfmt-1.85 \ rust-1.85-clippy ln -s /usr/lib/rust-1.85/bin/rustfmt /usr/bin/rustfmt-1.85 ln -s /usr/lib/rust-1.85/bin/clippy-driver /usr/bin/clippy-driver-1.85
None of these packages set their tools as defaults; therefore they should bespecified explicitly, e.g.::
make LLVM=1 RUSTC=rustc-1.85 RUSTDOC=rustdoc-1.85 RUSTFMT=rustfmt-1.85 \ CLIPPY_DRIVER=clippy-driver-1.85 BINDGEN=bindgen-0.71
Alternatively, modify the ``PATH`` variable to place the Rust 1.85 binariesfirst and set ``bindgen`` as the default, e.g.::
PATH=/usr/lib/rust-1.85/bin:$PATH update-alternatives --install /usr/bin/bindgen bindgen \ /usr/bin/bindgen-0.71 100 update-alternatives --set bindgen /usr/bin/bindgen-0.71
``RUST_LIB_SRC`` may need to be set when using the versioned packages, e.g.::
RUST_LIB_SRC=/usr/src/rustc-$(rustc-1.85 --version | cut -d' ' -f2)/library
For convenience, ``RUST_LIB_SRC`` can be exported to the global environment.
In addition, ``bindgen-0.71`` is available in newer releases (24.04 LTS),but it may not be available in older ones (20.04 LTS and 22.04 LTS),thus ``bindgen`` may need to be built manually (please see below).
Requirements: Building----------------------
This section explains how to fetch the tools needed for building.
To easily check whether the requirements are met, the following targetcan be used::
make LLVM=1 rustavailable
This triggers the same logic used by Kconfig to determine whether``RUST_IS_AVAILABLE`` should be enabled; but it also explains why notif that is the case.
rustc*****
A recent version of the Rust compiler is required.
If ``rustup`` is being used, enter the kernel build directory (or use``--path=<build-dir>`` argument to the ``set`` sub-command) and run,for instance::
rustup override set stable
This will configure your working directory to use the given version of``rustc`` without affecting your default toolchain.
Note that the override applies to the current working directory (and itssub-directories).
If you are not using ``rustup``, fetch a standalone installer from:
https://forge.rust-lang.org/infra/other-installation-methods.html#standalone
Rust standard library source****************************
The Rust standard library source is required because the build system willcross-compile ``core``.
If ``rustup`` is being used, run::
rustup component add rust-src
The components are installed per toolchain, thus upgrading the Rust compilerversion later on requires re-adding the component.
Otherwise, if a standalone installer is used, the Rust source tree may bedownloaded into the toolchain's installation folder::
curl -L "https://static.rust-lang.org/dist/rust-src-$(rustc --version | cut -d' ' -f2).tar.gz" | tar -xzf - -C "$(rustc --print sysroot)/lib" \ "rust-src-$(rustc --version | cut -d' ' -f2)/rust-src/lib/" \ --strip-components=3
In this case, upgrading the Rust compiler version later on requires manuallyupdating the source tree (this can be done by removing ``$(rustc --printsysroot)/lib/rustlib/src/rust`` then rerunning the above command).
libclang********
``libclang`` (part of LLVM) is used by ``bindgen`` to understand the C codein the kernel, which means LLVM needs to be installed; like when the kernelis compiled with ``LLVM=1``.
Linux distributions are likely to have a suitable one available, so it isbest to check that first.
There are also some binaries for several systems and architectures uploaded at:
https://releases.llvm.org/download.html
Otherwise, building LLVM takes quite a while, but it is not a complex process:
https://llvm.org/docs/GettingStarted.html#getting-the-source-code-and-building-llvm
Please see Documentation/kbuild/llvm.rst for more information and further waysto fetch pre-built releases and distribution packages.
bindgen*******
The bindings to the C side of the kernel are generated at build time usingthe ``bindgen`` tool.
Install it, for instance, via (note that this will download and build the toolfrom source)::
cargo install --locked bindgen-cli
``bindgen`` uses the ``clang-sys`` crate to find a suitable ``libclang`` (whichmay be linked statically, dynamically or loaded at runtime). By default, the``cargo`` command above will produce a ``bindgen`` binary that will load``libclang`` at runtime. If it is not found (or a different ``libclang`` thanthe one found should be used), the process can be tweaked, e.g. by using the``LIBCLANG_PATH`` environment variable. For details, please see ``clang-sys``'sdocumentation at:
https://github.com/KyleMayes/clang-sys#linking
https://github.com/KyleMayes/clang-sys#environment-variables
Requirements: Developing------------------------
This section explains how to fetch the tools needed for developing. That is,they are not needed when just building the kernel.
rustfmt*******
The ``rustfmt`` tool is used to automatically format all the Rust kernel code,including the generated C bindings (for details, please seecoding-guidelines.rst).
If ``rustup`` is being used, its ``default`` profile already installs the tool,thus nothing needs to be done. If another profile is being used, the componentcan be installed manually::
rustup component add rustfmt
The standalone installers also come with ``rustfmt``.
clippy******
``clippy`` is a Rust linter. Running it provides extra warnings for Rust code.It can be run by passing ``CLIPPY=1`` to ``make`` (for details, please seegeneral-information.rst).
If ``rustup`` is being used, its ``default`` profile already installs the tool,thus nothing needs to be done. If another profile is being used, the componentcan be installed manually::
rustup component add clippy
The standalone installers also come with ``clippy``.
rustdoc*******
``rustdoc`` is the documentation tool for Rust. It generates pretty HTMLdocumentation for Rust code (for details, please seegeneral-information.rst).
``rustdoc`` is also used to test the examples provided in documented Rust code(called doctests or documentation tests). The ``rusttest`` Make target usesthis feature.
If ``rustup`` is being used, all the profiles already install the tool,thus nothing needs to be done.
The standalone installers also come with ``rustdoc``.
rust-analyzer*************
The `rust-analyzer <https://rust-analyzer.github.io/>`_ language server canbe used with many editors to enable syntax highlighting, completion, go todefinition, and other features.
``rust-analyzer`` needs a configuration file, ``rust-project.json``, whichcan be generated by the ``rust-analyzer`` Make target::
make LLVM=1 rust-analyzer
Configuration-------------
``Rust support`` (``CONFIG_RUST``) needs to be enabled in the ``General setup``menu. The option is only shown if a suitable Rust toolchain is found (seeabove), as long as the other requirements are met. In turn, this will makevisible the rest of options that depend on Rust.
Afterwards, go to::
Kernel hacking -> Sample kernel code -> Rust samples
And enable some sample modules either as built-in or as loadable.
Building--------
Building a kernel with a complete LLVM toolchain is the best supported setupat the moment. That is::
make LLVM=1
Using GCC also works for some configurations, but it is very experimental atthe moment.
Hacking-------
To dive deeper, take a look at the source code of the samplesat ``samples/rust/``, the Rust support code under ``rust/`` andthe ``Rust hacking`` menu under ``Kernel hacking``.