Merge tag 'kbuild-v6.1' of git://git.kernel.org/pub/scm/linux/kernel/git/masahiroy...

[linux-block.git] / Documentation / kbuild / makefiles.rst

diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst
index 60134ddf3db1076cbdcd9426704b217ce475ff0b..6b7368d1f51639c016e4be5f4c3c4f51b0f29991 100644 (file)
--- a/Documentation/kbuild/makefiles.rst
+++ b/Documentation/kbuild/makefiles.rst
@@ -29,8 +29,9 @@ This document describes the Linux kernel Makefiles.
           --- 4.1 Simple Host Program
           --- 4.2 Composite Host Programs
           --- 4.3 Using C++ for host programs
-          --- 4.4 Controlling compiler options for host programs
-          --- 4.5 When host programs are actually built
+          --- 4.4 Using Rust for host programs
+          --- 4.5 Controlling compiler options for host programs
+          --- 4.6 When host programs are actually built
 
        === 5 Userspace Program support
           --- 5.1 Simple Userspace Program
@@ -824,7 +825,24 @@ Both possibilities are described in the following.
                qconf-cxxobjs := qconf.o
                qconf-objs    := check.o
 
-4.4 Controlling compiler options for host programs
+4.4 Using Rust for host programs
+--------------------------------
+
+       Kbuild offers support for host programs written in Rust. However,
+       since a Rust toolchain is not mandatory for kernel compilation,
+       it may only be used in scenarios where Rust is required to be
+       available (e.g. when  ``CONFIG_RUST`` is enabled).
+
+       Example::
+
+               hostprogs     := target
+               target-rust   := y
+
+       Kbuild will compile ``target`` using ``target.rs`` as the crate root,
+       located in the same directory as the ``Makefile``. The crate may
+       consist of several source files (see ``samples/rust/hostprogs``).
+
+4.5 Controlling compiler options for host programs
 --------------------------------------------------
 
        When compiling host programs, it is possible to set specific flags.
@@ -856,7 +874,7 @@ Both possibilities are described in the following.
        When linking qconf, it will be passed the extra option
        "-L$(QTDIR)/lib".
 
-4.5 When host programs are actually built
+4.6 When host programs are actually built
 -----------------------------------------
 
        Kbuild will only build host-programs when they are referenced
@@ -1169,6 +1187,17 @@ When kbuild executes, the following steps are followed (roughly):
        The first example utilises the trick that a config option expands
        to 'y' when selected.
 
+    KBUILD_RUSTFLAGS
+       $(RUSTC) compiler flags
+
+       Default value - see top level Makefile
+       Append or modify as required per architecture.
+
+       Often, the KBUILD_RUSTFLAGS variable depends on the configuration.
+
+       Note that target specification file generation (for ``--target``)
+       is handled in ``scripts/generate_rust_target.rs``.
+
     KBUILD_AFLAGS_KERNEL
        Assembler options specific for built-in
 
@@ -1196,6 +1225,19 @@ When kbuild executes, the following steps are followed (roughly):
        are used for $(CC).
        From commandline CFLAGS_MODULE shall be used (see kbuild.rst).
 
+    KBUILD_RUSTFLAGS_KERNEL
+       $(RUSTC) options specific for built-in
+
+       $(KBUILD_RUSTFLAGS_KERNEL) contains extra Rust compiler flags used to
+       compile resident kernel code.
+
+    KBUILD_RUSTFLAGS_MODULE
+       Options for $(RUSTC) when building modules
+
+       $(KBUILD_RUSTFLAGS_MODULE) is used to add arch-specific options that
+       are used for $(RUSTC).
+       From commandline RUSTFLAGS_MODULE shall be used (see kbuild.rst).
+
     KBUILD_LDFLAGS_MODULE
        Options for $(LD) when linking modules