1d07479b2SMiguel Ojeda.. SPDX-License-Identifier: GPL-2.0 2d07479b2SMiguel Ojeda 3d07479b2SMiguel OjedaQuick Start 4d07479b2SMiguel Ojeda=========== 5d07479b2SMiguel Ojeda 6d07479b2SMiguel OjedaThis document describes how to get started with kernel development in Rust. 7d07479b2SMiguel Ojeda 8b1263411SMiguel OjedaThere are a few ways to install a Rust toolchain needed for kernel development. 9b1263411SMiguel OjedaA simple way is to use the packages from your Linux distribution if they are 10b1263411SMiguel Ojedasuitable -- the first section below explains this approach. An advantage of this 11b1263411SMiguel Ojedaapproach is that, typically, the distribution will match the LLVM used by Rust 12b1263411SMiguel Ojedaand Clang. 13b1263411SMiguel Ojeda 14b1263411SMiguel OjedaAnother way is using the prebuilt stable versions of LLVM+Rust provided on 15b1263411SMiguel Ojeda`kernel.org <https://kernel.org/pub/tools/llvm/rust/>`_. These are the same slim 16b1263411SMiguel Ojedaand fast LLVM toolchains from :ref:`Getting LLVM <getting_llvm>` with versions 17b1263411SMiguel Ojedaof Rust added to them that Rust for Linux supports. Two sets are provided: the 18b1263411SMiguel Ojeda"latest LLVM" and "matching LLVM" (please see the link for more information). 19b1263411SMiguel Ojeda 20b1263411SMiguel OjedaAlternatively, the next two "Requirements" sections explain each component and 21b1263411SMiguel Ojedahow to install them through ``rustup``, the standalone installers from Rust 22b1263411SMiguel Ojedaand/or building them. 23b1263411SMiguel Ojeda 24b1263411SMiguel OjedaThe rest of the document explains other aspects on how to get started. 25b1263411SMiguel Ojeda 26b1263411SMiguel Ojeda 27b1263411SMiguel OjedaDistributions 28b1263411SMiguel Ojeda------------- 29b1263411SMiguel Ojeda 30b1263411SMiguel OjedaArch Linux 31b1263411SMiguel Ojeda********** 32b1263411SMiguel Ojeda 33b1263411SMiguel OjedaArch Linux provides recent Rust releases and thus it should generally work out 34b1263411SMiguel Ojedaof the box, e.g.:: 35b1263411SMiguel Ojeda 36b1263411SMiguel Ojeda pacman -S rust rust-src rust-bindgen 37b1263411SMiguel Ojeda 38b1263411SMiguel Ojeda 39b1263411SMiguel OjedaDebian 40b1263411SMiguel Ojeda****** 41b1263411SMiguel Ojeda 42*f3639304SMiguel OjedaDebian Testing and Debian Unstable (Sid), outside of the freeze period, provide 43*f3639304SMiguel Ojedarecent Rust releases and thus they should generally work out of the box, e.g.:: 44b1263411SMiguel Ojeda 45b1263411SMiguel Ojeda apt install rustc rust-src bindgen rustfmt rust-clippy 46b1263411SMiguel Ojeda 47b1263411SMiguel Ojeda 48b1263411SMiguel OjedaFedora Linux 49b1263411SMiguel Ojeda************ 50b1263411SMiguel Ojeda 51b1263411SMiguel OjedaFedora Linux provides recent Rust releases and thus it should generally work out 52b1263411SMiguel Ojedaof the box, e.g.:: 53b1263411SMiguel Ojeda 54b1263411SMiguel Ojeda dnf install rust rust-src bindgen-cli rustfmt clippy 55b1263411SMiguel Ojeda 56b1263411SMiguel Ojeda 57b1263411SMiguel OjedaGentoo Linux 58b1263411SMiguel Ojeda************ 59b1263411SMiguel Ojeda 60b1263411SMiguel OjedaGentoo Linux (and especially the testing branch) provides recent Rust releases 61b1263411SMiguel Ojedaand thus it should generally work out of the box, e.g.:: 62b1263411SMiguel Ojeda 63b1263411SMiguel Ojeda USE='rust-src rustfmt clippy' emerge dev-lang/rust dev-util/bindgen 64b1263411SMiguel Ojeda 65b1263411SMiguel Ojeda``LIBCLANG_PATH`` may need to be set. 66b1263411SMiguel Ojeda 67b1263411SMiguel Ojeda 68b1263411SMiguel OjedaNix 69b1263411SMiguel Ojeda*** 70b1263411SMiguel Ojeda 71b1263411SMiguel OjedaNix (unstable channel) provides recent Rust releases and thus it should 72b1263411SMiguel Ojedagenerally work out of the box, e.g.:: 73b1263411SMiguel Ojeda 74b1263411SMiguel Ojeda { pkgs ? import <nixpkgs> {} }: 75b1263411SMiguel Ojeda pkgs.mkShell { 76b1263411SMiguel Ojeda nativeBuildInputs = with pkgs; [ rustc rust-bindgen rustfmt clippy ]; 77b1263411SMiguel Ojeda RUST_LIB_SRC = "${pkgs.rust.packages.stable.rustPlatform.rustLibSrc}"; 78b1263411SMiguel Ojeda } 79b1263411SMiguel Ojeda 80b1263411SMiguel Ojeda 81b1263411SMiguel OjedaopenSUSE 82b1263411SMiguel Ojeda******** 83b1263411SMiguel Ojeda 84b1263411SMiguel OjedaopenSUSE Slowroll and openSUSE Tumbleweed provide recent Rust releases and thus 85b1263411SMiguel Ojedathey should generally work out of the box, e.g.:: 86b1263411SMiguel Ojeda 87b1263411SMiguel Ojeda zypper install rust rust1.79-src rust-bindgen clang 88b1263411SMiguel Ojeda 89d07479b2SMiguel Ojeda 90d07479b2SMiguel OjedaRequirements: Building 91d07479b2SMiguel Ojeda---------------------- 92d07479b2SMiguel Ojeda 93d07479b2SMiguel OjedaThis section explains how to fetch the tools needed for building. 94d07479b2SMiguel Ojeda 95d07479b2SMiguel OjedaTo easily check whether the requirements are met, the following target 96d07479b2SMiguel Ojedacan be used:: 97d07479b2SMiguel Ojeda 98d07479b2SMiguel Ojeda make LLVM=1 rustavailable 99d07479b2SMiguel Ojeda 100d07479b2SMiguel OjedaThis triggers the same logic used by Kconfig to determine whether 101d07479b2SMiguel Ojeda``RUST_IS_AVAILABLE`` should be enabled; but it also explains why not 102d07479b2SMiguel Ojedaif that is the case. 103d07479b2SMiguel Ojeda 104d07479b2SMiguel Ojeda 105d07479b2SMiguel Ojedarustc 106d07479b2SMiguel Ojeda***** 107d07479b2SMiguel Ojeda 10863b27f4aSMiguel OjedaA recent version of the Rust compiler is required. 109d07479b2SMiguel Ojeda 110711cbfc7SViresh KumarIf ``rustup`` is being used, enter the kernel build directory (or use 11163b27f4aSMiguel Ojeda``--path=<build-dir>`` argument to the ``set`` sub-command) and run, 11263b27f4aSMiguel Ojedafor instance:: 113d07479b2SMiguel Ojeda 11463b27f4aSMiguel Ojeda rustup override set stable 115d07479b2SMiguel Ojeda 11663b27f4aSMiguel OjedaThis will configure your working directory to use the given version of 117711cbfc7SViresh Kumar``rustc`` without affecting your default toolchain. 118711cbfc7SViresh Kumar 119711cbfc7SViresh KumarNote that the override applies to the current working directory (and its 120711cbfc7SViresh Kumarsub-directories). 121711cbfc7SViresh Kumar 122711cbfc7SViresh KumarIf you are not using ``rustup``, fetch a standalone installer from: 123d07479b2SMiguel Ojeda 1246883b29cSMiguel Ojeda https://forge.rust-lang.org/infra/other-installation-methods.html#standalone 125d07479b2SMiguel Ojeda 126d07479b2SMiguel Ojeda 127d07479b2SMiguel OjedaRust standard library source 128d07479b2SMiguel Ojeda**************************** 129d07479b2SMiguel Ojeda 130d07479b2SMiguel OjedaThe Rust standard library source is required because the build system will 131d07479b2SMiguel Ojedacross-compile ``core`` and ``alloc``. 132d07479b2SMiguel Ojeda 133d07479b2SMiguel OjedaIf ``rustup`` is being used, run:: 134d07479b2SMiguel Ojeda 135d07479b2SMiguel Ojeda rustup component add rust-src 136d07479b2SMiguel Ojeda 137d07479b2SMiguel OjedaThe components are installed per toolchain, thus upgrading the Rust compiler 138d07479b2SMiguel Ojedaversion later on requires re-adding the component. 139d07479b2SMiguel Ojeda 1408cb40124STrevor GrossOtherwise, if a standalone installer is used, the Rust source tree may be 1418cb40124STrevor Grossdownloaded into the toolchain's installation folder:: 142d07479b2SMiguel Ojeda 14363b27f4aSMiguel Ojeda curl -L "https://static.rust-lang.org/dist/rust-src-$(rustc --version | cut -d' ' -f2).tar.gz" | 1448cb40124STrevor Gross tar -xzf - -C "$(rustc --print sysroot)/lib" \ 14563b27f4aSMiguel Ojeda "rust-src-$(rustc --version | cut -d' ' -f2)/rust-src/lib/" \ 1468cb40124STrevor Gross --strip-components=3 147d07479b2SMiguel Ojeda 148d07479b2SMiguel OjedaIn this case, upgrading the Rust compiler version later on requires manually 1498cb40124STrevor Grossupdating the source tree (this can be done by removing ``$(rustc --print 1508cb40124STrevor Grosssysroot)/lib/rustlib/src/rust`` then rerunning the above command). 151d07479b2SMiguel Ojeda 152d07479b2SMiguel Ojeda 153d07479b2SMiguel Ojedalibclang 154d07479b2SMiguel Ojeda******** 155d07479b2SMiguel Ojeda 156d07479b2SMiguel Ojeda``libclang`` (part of LLVM) is used by ``bindgen`` to understand the C code 157d07479b2SMiguel Ojedain the kernel, which means LLVM needs to be installed; like when the kernel 1587583ce66SMiguel Ojedais compiled with ``LLVM=1``. 159d07479b2SMiguel Ojeda 160d07479b2SMiguel OjedaLinux distributions are likely to have a suitable one available, so it is 161d07479b2SMiguel Ojedabest to check that first. 162d07479b2SMiguel Ojeda 163d07479b2SMiguel OjedaThere are also some binaries for several systems and architectures uploaded at: 164d07479b2SMiguel Ojeda 165d07479b2SMiguel Ojeda https://releases.llvm.org/download.html 166d07479b2SMiguel Ojeda 167d07479b2SMiguel OjedaOtherwise, building LLVM takes quite a while, but it is not a complex process: 168d07479b2SMiguel Ojeda 169d07479b2SMiguel Ojeda https://llvm.org/docs/GettingStarted.html#getting-the-source-code-and-building-llvm 170d07479b2SMiguel Ojeda 171d07479b2SMiguel OjedaPlease see Documentation/kbuild/llvm.rst for more information and further ways 172d07479b2SMiguel Ojedato fetch pre-built releases and distribution packages. 173d07479b2SMiguel Ojeda 174d07479b2SMiguel Ojeda 175d07479b2SMiguel Ojedabindgen 176d07479b2SMiguel Ojeda******* 177d07479b2SMiguel Ojeda 178d07479b2SMiguel OjedaThe bindings to the C side of the kernel are generated at build time using 179c844fa64SMiguel Ojedathe ``bindgen`` tool. 180d07479b2SMiguel Ojeda 181c844fa64SMiguel OjedaInstall it, for instance, via (note that this will download and build the tool 182c844fa64SMiguel Ojedafrom source):: 183d07479b2SMiguel Ojeda 184c844fa64SMiguel Ojeda cargo install --locked bindgen-cli 185d07479b2SMiguel Ojeda 186d49082faSMiguel Ojeda``bindgen`` uses the ``clang-sys`` crate to find a suitable ``libclang`` (which 187d49082faSMiguel Ojedamay be linked statically, dynamically or loaded at runtime). By default, the 188d49082faSMiguel Ojeda``cargo`` command above will produce a ``bindgen`` binary that will load 189d49082faSMiguel Ojeda``libclang`` at runtime. If it is not found (or a different ``libclang`` than 190d49082faSMiguel Ojedathe one found should be used), the process can be tweaked, e.g. by using the 191d49082faSMiguel Ojeda``LIBCLANG_PATH`` environment variable. For details, please see ``clang-sys``'s 192d49082faSMiguel Ojedadocumentation at: 193eae90172SMiguel Ojeda 194d49082faSMiguel Ojeda https://github.com/KyleMayes/clang-sys#linking 195eae90172SMiguel Ojeda 196eae90172SMiguel Ojeda https://github.com/KyleMayes/clang-sys#environment-variables 197eae90172SMiguel Ojeda 198d07479b2SMiguel Ojeda 199d07479b2SMiguel OjedaRequirements: Developing 200d07479b2SMiguel Ojeda------------------------ 201d07479b2SMiguel Ojeda 202d07479b2SMiguel OjedaThis section explains how to fetch the tools needed for developing. That is, 203d07479b2SMiguel Ojedathey are not needed when just building the kernel. 204d07479b2SMiguel Ojeda 205d07479b2SMiguel Ojeda 206d07479b2SMiguel Ojedarustfmt 207d07479b2SMiguel Ojeda******* 208d07479b2SMiguel Ojeda 209d07479b2SMiguel OjedaThe ``rustfmt`` tool is used to automatically format all the Rust kernel code, 210d07479b2SMiguel Ojedaincluding the generated C bindings (for details, please see 211d07479b2SMiguel Ojedacoding-guidelines.rst). 212d07479b2SMiguel Ojeda 213d07479b2SMiguel OjedaIf ``rustup`` is being used, its ``default`` profile already installs the tool, 214d07479b2SMiguel Ojedathus nothing needs to be done. If another profile is being used, the component 215d07479b2SMiguel Ojedacan be installed manually:: 216d07479b2SMiguel Ojeda 217d07479b2SMiguel Ojeda rustup component add rustfmt 218d07479b2SMiguel Ojeda 219d07479b2SMiguel OjedaThe standalone installers also come with ``rustfmt``. 220d07479b2SMiguel Ojeda 221d07479b2SMiguel Ojeda 222d07479b2SMiguel Ojedaclippy 223d07479b2SMiguel Ojeda****** 224d07479b2SMiguel Ojeda 225d07479b2SMiguel Ojeda``clippy`` is a Rust linter. Running it provides extra warnings for Rust code. 226d07479b2SMiguel OjedaIt can be run by passing ``CLIPPY=1`` to ``make`` (for details, please see 227d07479b2SMiguel Ojedageneral-information.rst). 228d07479b2SMiguel Ojeda 229d07479b2SMiguel OjedaIf ``rustup`` is being used, its ``default`` profile already installs the tool, 230d07479b2SMiguel Ojedathus nothing needs to be done. If another profile is being used, the component 231d07479b2SMiguel Ojedacan be installed manually:: 232d07479b2SMiguel Ojeda 233d07479b2SMiguel Ojeda rustup component add clippy 234d07479b2SMiguel Ojeda 235d07479b2SMiguel OjedaThe standalone installers also come with ``clippy``. 236d07479b2SMiguel Ojeda 237d07479b2SMiguel Ojeda 238d07479b2SMiguel Ojedarustdoc 239d07479b2SMiguel Ojeda******* 240d07479b2SMiguel Ojeda 241d07479b2SMiguel Ojeda``rustdoc`` is the documentation tool for Rust. It generates pretty HTML 242d07479b2SMiguel Ojedadocumentation for Rust code (for details, please see 243d07479b2SMiguel Ojedageneral-information.rst). 244d07479b2SMiguel Ojeda 245d07479b2SMiguel Ojeda``rustdoc`` is also used to test the examples provided in documented Rust code 246d07479b2SMiguel Ojeda(called doctests or documentation tests). The ``rusttest`` Make target uses 247d07479b2SMiguel Ojedathis feature. 248d07479b2SMiguel Ojeda 249d07479b2SMiguel OjedaIf ``rustup`` is being used, all the profiles already install the tool, 250d07479b2SMiguel Ojedathus nothing needs to be done. 251d07479b2SMiguel Ojeda 252d07479b2SMiguel OjedaThe standalone installers also come with ``rustdoc``. 253d07479b2SMiguel Ojeda 254d07479b2SMiguel Ojeda 255d07479b2SMiguel Ojedarust-analyzer 256d07479b2SMiguel Ojeda************* 257d07479b2SMiguel Ojeda 258d07479b2SMiguel OjedaThe `rust-analyzer <https://rust-analyzer.github.io/>`_ language server can 259d07479b2SMiguel Ojedabe used with many editors to enable syntax highlighting, completion, go to 260d07479b2SMiguel Ojedadefinition, and other features. 261d07479b2SMiguel Ojeda 262d07479b2SMiguel Ojeda``rust-analyzer`` needs a configuration file, ``rust-project.json``, which 263b603c6ccSGuillaume Plourdecan be generated by the ``rust-analyzer`` Make target:: 264b603c6ccSGuillaume Plourde 265b603c6ccSGuillaume Plourde make LLVM=1 rust-analyzer 266d07479b2SMiguel Ojeda 267d07479b2SMiguel Ojeda 268d07479b2SMiguel OjedaConfiguration 269d07479b2SMiguel Ojeda------------- 270d07479b2SMiguel Ojeda 271d07479b2SMiguel Ojeda``Rust support`` (``CONFIG_RUST``) needs to be enabled in the ``General setup`` 272d07479b2SMiguel Ojedamenu. The option is only shown if a suitable Rust toolchain is found (see 273d07479b2SMiguel Ojedaabove), as long as the other requirements are met. In turn, this will make 274d07479b2SMiguel Ojedavisible the rest of options that depend on Rust. 275d07479b2SMiguel Ojeda 276d07479b2SMiguel OjedaAfterwards, go to:: 277d07479b2SMiguel Ojeda 278d07479b2SMiguel Ojeda Kernel hacking 279d07479b2SMiguel Ojeda -> Sample kernel code 280d07479b2SMiguel Ojeda -> Rust samples 281d07479b2SMiguel Ojeda 282d07479b2SMiguel OjedaAnd enable some sample modules either as built-in or as loadable. 283d07479b2SMiguel Ojeda 284d07479b2SMiguel Ojeda 285d07479b2SMiguel OjedaBuilding 286d07479b2SMiguel Ojeda-------- 287d07479b2SMiguel Ojeda 288d07479b2SMiguel OjedaBuilding a kernel with a complete LLVM toolchain is the best supported setup 289d07479b2SMiguel Ojedaat the moment. That is:: 290d07479b2SMiguel Ojeda 291d07479b2SMiguel Ojeda make LLVM=1 292d07479b2SMiguel Ojeda 293d07479b2SMiguel OjedaUsing GCC also works for some configurations, but it is very experimental at 294d07479b2SMiguel Ojedathe moment. 295d07479b2SMiguel Ojeda 296d07479b2SMiguel Ojeda 297d07479b2SMiguel OjedaHacking 298d07479b2SMiguel Ojeda------- 299d07479b2SMiguel Ojeda 300d07479b2SMiguel OjedaTo dive deeper, take a look at the source code of the samples 301d07479b2SMiguel Ojedaat ``samples/rust/``, the Rust support code under ``rust/`` and 302d07479b2SMiguel Ojedathe ``Rust hacking`` menu under ``Kernel hacking``. 303d07479b2SMiguel Ojeda 304d07479b2SMiguel OjedaIf GDB/Binutils is used and Rust symbols are not getting demangled, the reason 305d07479b2SMiguel Ojedais the toolchain does not support Rust's new v0 mangling scheme yet. 306d07479b2SMiguel OjedaThere are a few ways out: 307d07479b2SMiguel Ojeda 308d07479b2SMiguel Ojeda- Install a newer release (GDB >= 10.2, Binutils >= 2.36). 309d07479b2SMiguel Ojeda 310d07479b2SMiguel Ojeda- Some versions of GDB (e.g. vanilla GDB 10.1) are able to use 311d07479b2SMiguel Ojeda the pre-demangled names embedded in the debug info (``CONFIG_DEBUG_INFO``). 312