Rust 커널 개발 빠른 시작

Toolchain 선택

이 문서는 Rust로 커널 개발을 시작하는 절차를 설명한다. 가장 간단한 방법은 적합한 Linux 배포판 package를 쓰는 것이며, 배포판이 Rust가 사용하는 LLVM과 Clang 버전을 함께 맞춰 주는 장점이 있다.

다른 방법으로 `kernel.org/pub/tools/llvm/rust/`의 prebuilt stable LLVM+Rust를 사용할 수 있다. 이는 커널이 제공하는 작고 빠른 LLVM toolchain에 Rust for Linux가 지원하는 Rust 버전을 더한 것으로, 최신 LLVM 조합과 버전이 맞는 LLVM 조합 두 세트를 제공한다.

배포판이나 prebuilt 조합을 쓰지 않으면 뒤의 Requirements 절에 따라 `rustup`, Rust standalone installer 또는 직접 빌드로 각 구성요소를 설치한다. 나머지 절은 설정, 빌드와 실제 소스 탐색을 안내한다.

.. 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 are
suitable -- the first section below explains this approach. An advantage of this
approach is that, typically, the distribution will match the LLVM used by Rust
and 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 slim
and fast LLVM toolchains from :ref:`Getting LLVM <getting_llvm>` with versions
of 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 and
how to install them through ``rustup``, the standalone installers from Rust
and/or building them.

The rest of the document explains other aspects on how to get started.

배포판별 설치

Arch Linux, Debian Testing·Unstable, Fedora, Gentoo testing, Nix unstable, openSUSE Slowroll·Tumbleweed와 최신 Ubuntu는 대체로 충분히 새 Rust를 제공한다. 각 배포판의 package manager로 compiler, source, bindgen, rustfmt와 Clippy를 설치한다.

Gentoo에서는 `rust-src rustfmt clippy` USE flag를 사용하며 환경에 따라 `LIBCLANG_PATH`가 필요하다. Nix shell은 `rustc`, `rust-bindgen`, `rustfmt`, `clippy`를 native build input으로 넣고 `RUST_LIB_SRC`를 stable toolchain source 경로로 지정한다.

Ubuntu 25.04에서는 package 설치 뒤 `RUST_LIB_SRC=/usr/src/rustc-$(rustc --version | cut -d' ' -f2)/library`를 설정한다. 자주 쓴다면 전역 환경에 export할 수 있다.

Ubuntu 24.04 LTS와 그 이전은 `rustc-1.80`, `rust-1.80-src`, `bindgen-0.65`, `rustfmt-1.80`, `rust-1.80-clippy`처럼 versioned package를 설치한다. 기본 도구가 되지 않으므로 Make 변수로 각 실행 파일을 명시하거나 Rust 1.80 경로를 `PATH` 앞에 두고 `update-alternatives`로 bindgen을 선택한다.

Versioned Ubuntu package에서도 `RUST_LIB_SRC`를 해당 rustc source 경로로 지정한다. `bindgen-0.65`는 24.04와 24.10에는 있지만 20.04와 22.04에는 없을 수 있으므로 오래된 release에서는 아래 절에 따라 직접 빌드해야 할 수 있다.

Distributions
-------------

Arch Linux
**********

Arch Linux provides recent Rust releases and thus it should generally work out
of the box, e.g.::

        pacman -S rust rust-src rust-bindgen


Debian
******

Debian Testing and Debian Unstable (Sid), outside of the freeze period, provide
recent Rust 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 out
of the box, e.g.::

        dnf install rust rust-src bindgen-cli rustfmt clippy


Gentoo Linux
************

Gentoo Linux (and especially the testing branch) provides recent Rust releases
and thus it should generally work out of 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 (unstable channel) provides recent Rust releases and thus it should
generally work out of the box, 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 thus
they should generally work out of the box, e.g.::

        zypper install rust rust1.79-src rust-bindgen clang


Ubuntu
******

25.04
~~~~~

The latest Ubuntu releases provide recent Rust releases and thus they should
generally 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 Rust
releases, they require some additional configuration to be set, using
the versioned packages, e.g.::

        apt install rustc-1.80 rust-1.80-src bindgen-0.65 rustfmt-1.80 \
                rust-1.80-clippy
        ln -s /usr/lib/rust-1.80/bin/rustfmt /usr/bin/rustfmt-1.80
        ln -s /usr/lib/rust-1.80/bin/clippy-driver /usr/bin/clippy-driver-1.80

None of these packages set their tools as defaults; therefore they should be
specified explicitly, e.g.::

        make LLVM=1 RUSTC=rustc-1.80 RUSTDOC=rustdoc-1.80 RUSTFMT=rustfmt-1.80 \
                CLIPPY_DRIVER=clippy-driver-1.80 BINDGEN=bindgen-0.65

Alternatively, modify the ``PATH`` variable to place the Rust 1.80 binaries
first and set ``bindgen`` as the default, e.g.::

        PATH=/usr/lib/rust-1.80/bin:$PATH
        update-alternatives --install /usr/bin/bindgen bindgen \
                /usr/bin/bindgen-0.65 100
        update-alternatives --set bindgen /usr/bin/bindgen-0.65

``RUST_LIB_SRC`` needs to be set when using the versioned packages, e.g.::

        RUST_LIB_SRC=/usr/src/rustc-$(rustc-1.80 --version | cut -d' ' -f2)/library

For convenience, ``RUST_LIB_SRC`` can be exported to the global environment.

In addition, ``bindgen-0.65`` is available in newer releases (24.04 LTS and
24.10), 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).

빌드에 필요한 구성요소

빌드 요구사항은 `make LLVM=1 rustavailable`로 한 번에 확인한다. 이는 Kconfig가 `RUST_IS_AVAILABLE`을 정할 때와 같은 논리를 실행하고, 사용할 수 없다면 이유도 설명한다.

최근 `rustc`가 필요하다. `rustup` 사용자는 커널 build 디렉터리에서 `rustup override set stable`을 실행하거나 `set --path=<build-dir>`로 범위를 지정한다. Override는 현재 디렉터리와 하위 디렉터리에만 적용되어 기본 toolchain을 바꾸지 않는다. `rustup`을 쓰지 않으면 Rust standalone installer를 받을 수 있다.

빌드 시스템이 `core`를 cross-compile하므로 Rust standard library source가 필요하다. `rustup component add rust-src`로 설치하며 toolchain마다 별도이므로 compiler를 올린 뒤 다시 추가해야 한다. Standalone 설치에서는 compiler 버전에 맞는 `rust-src` archive를 sysroot 아래에 풀고, compiler upgrade 때 기존 source tree를 지운 뒤 다시 설치한다.

`bindgen`은 커널 C 코드를 이해하기 위해 LLVM의 `libclang`을 사용한다. 먼저 배포판 package를 확인하고, 필요하면 LLVM release binary를 받거나 직접 빌드한다. 다른 prebuilt 방법과 package 정보는 `Documentation/kbuild/llvm.rst`에 있다.

C 쪽 binding은 빌드 때 `bindgen`으로 생성한다. `cargo install --locked bindgen-cli`로 source에서 설치할 수 있다. 이 binary는 기본적으로 실행 시 `libclang`을 불러오며, 찾지 못하거나 다른 library를 써야 하면 `LIBCLANG_PATH` 등 `clang-sys`의 linking과 environment variable 설정을 사용한다.

Requirements: Building
----------------------

This section explains how to fetch the tools needed for building.

To easily check whether the requirements are met, the following target
can 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 not
if 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 its
sub-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 will
cross-compile ``core``.

If ``rustup`` is being used, run::

        rustup component add rust-src

The components are installed per toolchain, thus upgrading the Rust compiler
version later on requires re-adding the component.

Otherwise, if a standalone installer is used, the Rust source tree may be
downloaded 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 manually
updating the source tree (this can be done by removing ``$(rustc --print
sysroot)/lib/rustlib/src/rust`` then rerunning the above command).


libclang
********

``libclang`` (part of LLVM) is used by ``bindgen`` to understand the C code
in the kernel, which means LLVM needs to be installed; like when the kernel
is compiled with ``LLVM=1``.

Linux distributions are likely to have a suitable one available, so it is
best 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 ways
to fetch pre-built releases and distribution packages.


bindgen
*******

The bindings to the C side of the kernel are generated at build time using
the ``bindgen`` tool.

Install it, for instance, via (note that this will download and build the tool
from source)::

        cargo install --locked bindgen-cli

``bindgen`` uses the ``clang-sys`` crate to find a suitable ``libclang`` (which
may 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`` than
the 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``'s
documentation at:

        https://github.com/KyleMayes/clang-sys#linking

        https://github.com/KyleMayes/clang-sys#environment-variables

개발용 도구

이 절의 도구는 커널을 단순히 빌드할 때는 필요하지 않고 개발할 때 사용한다. `rustfmt`는 생성된 C binding을 포함한 모든 커널 Rust 코드의 서식을 맞춘다. `rustup` default profile에는 들어 있으며 다른 profile에서는 `rustup component add rustfmt`로 추가한다. Standalone installer에도 포함된다.

Clippy는 Rust 코드에 추가 warning을 제공하는 linter다. Make에 `CLIPPY=1`을 넘겨 실행한다. `rustup` default profile에는 기본 설치되고 다른 profile에서는 `rustup component add clippy`를 사용하며 standalone installer에도 포함된다.

`rustdoc`은 Rust 코드의 HTML 문서를 만들고 문서 속 예제인 doctest도 검사한다. `rusttest` Make target이 이 기능을 사용한다. 모든 rustup profile과 standalone installer에 포함된다.

`rust-analyzer` language server는 여러 편집기에서 syntax highlight, completion, go to definition 등을 제공한다. 커널에 필요한 `rust-project.json`은 `make LLVM=1 rust-analyzer`로 생성한다.

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 see
coding-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 component
can 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 see
general-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 component
can 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 HTML
documentation for Rust code (for details, please see
general-information.rst).

``rustdoc`` is also used to test the examples provided in documented Rust code
(called doctests or documentation tests). The ``rusttest`` Make target uses
this 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 can
be used with many editors to enable syntax highlighting, completion, go to
definition, and other features.

``rust-analyzer`` needs a configuration file, ``rust-project.json``, which
can be generated by the ``rust-analyzer`` Make target::

        make LLVM=1 rust-analyzer

Kconfig에서 Rust와 sample 활성화

`General setup` 메뉴에서 `Rust support` 즉 `CONFIG_RUST`를 켠다. 알맞은 Rust toolchain이 발견되고 다른 요구사항도 충족될 때만 이 항목이 보이며, 활성화하면 Rust에 의존하는 나머지 option이 나타난다.

그 다음 `Kernel hacking -> Sample kernel code -> Rust samples`로 이동해 예제 module을 built-in 또는 loadable module로 선택한다.

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 (see
above), as long as the other requirements are met. In turn, this will make
visible 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.

첫 커널 빌드

현재 가장 잘 지원되는 구성은 완전한 LLVM toolchain으로 커널을 빌드하는 것이다. 명령은 `make LLVM=1`이다. 일부 configuration에서는 GCC도 동작하지만 현재는 매우 실험적이다.

Building
--------

Building a kernel with a complete LLVM toolchain is the best supported setup
at the moment. That is::

        make LLVM=1

Using GCC also works for some configurations, but it is very experimental at
the moment.

소스 탐색과 symbol demangling

더 깊이 살펴보려면 `samples/rust/`의 sample, `rust/` 아래 지원 코드, `Kernel hacking`의 `Rust hacking` 메뉴부터 읽는다.

GDB 또는 Binutils에서 Rust symbol이 demangle되지 않는다면 toolchain이 새 v0 mangling scheme을 지원하지 않는 것이 원인일 수 있다. GDB 10.2 이상과 Binutils 2.36 이상으로 올리거나, 일부 GDB 버전에서는 `CONFIG_DEBUG_INFO`에 포함된 미리 demangle된 이름을 사용한다.

Hacking
-------

To dive deeper, take a look at the source code of the samples
at ``samples/rust/``, the Rust support code under ``rust/`` and
the ``Rust hacking`` menu under ``Kernel hacking``.

If GDB/Binutils is used and Rust symbols are not getting demangled, the reason
is the toolchain does not support Rust's new v0 mangling scheme yet.
There are a few ways out:

- Install a newer release (GDB >= 10.2, Binutils >= 2.36).

- Some versions of GDB (e.g. vanilla GDB 10.1) are able to use
  the pre-demangled names embedded in the debug info (``CONFIG_DEBUG_INFO``).