From 45a7371d5be21c174be201b8cde0e91b0357c606 Mon Sep 17 00:00:00 2001 From: Jesse Taube Date: Fri, 4 Aug 2023 23:44:45 -0400 Subject: docs: kbuild: Document search jump feature Menuconfig has a feature where you can "press the key in the (#) prefix to jump directly to that location. You will be returned to the current search results after exiting this new menu." This feature is poorly documented, so add it to the kconfig.rst documentation. Signed-off-by: Jesse Taube Acked-by: Randy Dunlap Signed-off-by: Masahiro Yamada --- Documentation/kbuild/kconfig.rst | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'Documentation/kbuild') diff --git a/Documentation/kbuild/kconfig.rst b/Documentation/kbuild/kconfig.rst index 5967c79c3baa..463914a7fdec 100644 --- a/Documentation/kbuild/kconfig.rst +++ b/Documentation/kbuild/kconfig.rst @@ -210,6 +210,10 @@ Searching in menuconfig: first (and in alphabetical order), then come all other symbols, sorted in alphabetical order. + In this menu, pressing the key in the (#) prefix will jump + directly to that location. You will be returned to the current + search results after exiting this new menu. + ---------------------------------------------------------------------- User interface options for 'menuconfig' @@ -262,6 +266,10 @@ Searching in nconfig: F8 (SymSearch) searches the configuration symbols for the given string or regular expression (regex). + In the SymSearch, pressing the key in the (#) prefix will + jump directly to that location. You will be returned to the + current search results after exiting this new menu. + NCONFIG_MODE ------------ This mode shows all sub-menus in one large tree. -- cgit From a3c6bfba4429123533e9ae96ee50ba45ff8a63f2 Mon Sep 17 00:00:00 2001 From: Nick Desaulniers Date: Fri, 25 Aug 2023 10:38:01 -0700 Subject: Documentation/llvm: refresh docs Recent fixes for an embargoed hardware security vulnerability failed to link with ld.lld (LLVM's linker). [0] To be fair, our documentation mentions ``CC=clang`` foremost with ``LLVM=1`` being buried "below the fold." We want to encourage the use of ``LLVM=1`` rather than just ``CC=clang``. Make that suggestion "above the fold" and "front and center" in our docs. While here, the following additional changes were made: - remove the bit about CROSS_COMPILE setting --target=, that's no longer true. - Add ARCH=loongarch to the list of maintained targets (though we're still working on getting defconfig building cleanly at the moment; we're pretty close). - Bump ARCH=powerpc from CC=clang to LLVM=1 status. - Promote ARCH=riscv from being Maintained to being Supported. Android is working towards supporting RISC-V, and we have excellent support from multiple companies in this regard. - Note that the toolchain distribution on kernel.org has been built with profile data from kernel builds. - Note how to use ccache with clang. Link: https://github.com/ClangBuiltLinux/linux/issues/1907 [0] Reviewed-by: Nathan Chancellor Signed-off-by: Nick Desaulniers Signed-off-by: Masahiro Yamada --- Documentation/kbuild/llvm.rst | 124 +++++++++++++++++++++++++++--------------- 1 file changed, 80 insertions(+), 44 deletions(-) (limited to 'Documentation/kbuild') diff --git a/Documentation/kbuild/llvm.rst b/Documentation/kbuild/llvm.rst index c3851fe1900d..b1d97fafddcf 100644 --- a/Documentation/kbuild/llvm.rst +++ b/Documentation/kbuild/llvm.rst @@ -25,50 +25,38 @@ objects `_. Clang is a front-end to LLVM that supports C and the GNU C extensions required by the kernel, and is pronounced "klang," not "see-lang." -Clang ------ - -The compiler used can be swapped out via ``CC=`` command line argument to ``make``. -``CC=`` should be set when selecting a config and during a build. :: - - make CC=clang defconfig - - make CC=clang +Building with LLVM +------------------ -Cross Compiling ---------------- +Invoke ``make`` via:: -A single Clang compiler binary will typically contain all supported backends, -which can help simplify cross compiling. :: - - make ARCH=arm64 CC=clang CROSS_COMPILE=aarch64-linux-gnu- + make LLVM=1 -``CROSS_COMPILE`` is not used to prefix the Clang compiler binary, instead -``CROSS_COMPILE`` is used to set a command line flag: ``--target=``. For -example: :: +to compile for the host target. For cross compiling:: - clang --target=aarch64-linux-gnu foo.c + make LLVM=1 ARCH=arm64 -LLVM Utilities --------------- +The LLVM= argument +------------------ -LLVM has substitutes for GNU binutils utilities. They can be enabled individually. -The full list of supported make variables:: +LLVM has substitutes for GNU binutils utilities. They can be enabled +individually. The full list of supported make variables:: make CC=clang LD=ld.lld AR=llvm-ar NM=llvm-nm STRIP=llvm-strip \ OBJCOPY=llvm-objcopy OBJDUMP=llvm-objdump READELF=llvm-readelf \ HOSTCC=clang HOSTCXX=clang++ HOSTAR=llvm-ar HOSTLD=ld.lld -To simplify the above command, Kbuild supports the ``LLVM`` variable:: - - make LLVM=1 +``LLVM=1`` expands to the above. If your LLVM tools are not available in your PATH, you can supply their location using the LLVM variable with a trailing slash:: make LLVM=/path/to/llvm/ -which will use ``/path/to/llvm/clang``, ``/path/to/llvm/ld.lld``, etc. +which will use ``/path/to/llvm/clang``, ``/path/to/llvm/ld.lld``, etc. The +following may also be used:: + + PATH=/path/to/llvm:$PATH make LLVM=1 If your LLVM tools have a version suffix and you want to test with that explicit version rather than the unsuffixed executables like ``LLVM=1``, you @@ -78,31 +66,72 @@ can pass the suffix using the ``LLVM`` variable:: which will use ``clang-14``, ``ld.lld-14``, etc. +To support combinations of out of tree paths with version suffixes, we +recommend:: + + PATH=/path/to/llvm/:$PATH make LLVM=-14 + ``LLVM=0`` is not the same as omitting ``LLVM`` altogether, it will behave like -``LLVM=1``. If you only wish to use certain LLVM utilities, use their respective -make variables. +``LLVM=1``. If you only wish to use certain LLVM utilities, use their +respective make variables. + +The same value used for ``LLVM=`` should be set for each invocation of ``make`` +if configuring and building via distinct commands. ``LLVM=`` should also be set +as an environment variable when running scripts that will eventually run +``make``. -The integrated assembler is enabled by default. You can pass ``LLVM_IAS=0`` to -disable it. +Cross Compiling +--------------- -Omitting CROSS_COMPILE +A single Clang compiler binary (and corresponding LLVM utilities) will +typically contain all supported back ends, which can help simplify cross +compiling especially when ``LLVM=1`` is used. If you use only LLVM tools, +``CROSS_COMPILE`` or target-triple-prefixes become unnecessary. Example:: + + make LLVM=1 ARCH=arm64 + +As an example of mixing LLVM and GNU utilities, for a target like ``ARCH=s390`` +which does not yet have ``ld.lld`` or ``llvm-objcopy`` support, you could +invoke ``make`` via:: + + make LLVM=1 ARCH=s390 LD=s390x-linux-gnu-ld.bfd \ + OBJCOPY=s390x-linux-gnu-objcopy + +This example will invoke ``s390x-linux-gnu-ld.bfd`` as the linker and +``s390x-linux-gnu-objcopy``, so ensure those are reachable in your ``$PATH``. + +``CROSS_COMPILE`` is not used to prefix the Clang compiler binary (or +corresponding LLVM utilities) as is the case for GNU utilities when ``LLVM=1`` +is not set. + +The LLVM_IAS= argument ---------------------- -As explained above, ``CROSS_COMPILE`` is used to set ``--target=``. +Clang can assemble assembler code. You can pass ``LLVM_IAS=0`` to disable this +behavior and have Clang invoke the corresponding non-integrated assembler +instead. Example:: + + make LLVM=1 LLVM_IAS=0 + +``CROSS_COMPILE`` is necessary when cross compiling and ``LLVM_IAS=0`` +is used in order to set ``--prefix=`` for the compiler to find the +corresponding non-integrated assembler (typically, you don't want to use the +system assembler when targeting another architecture). Example:: -If ``CROSS_COMPILE`` is not specified, the ``--target=`` is inferred -from ``ARCH``. + make LLVM=1 ARCH=arm LLVM_IAS=0 CROSS_COMPILE=arm-linux-gnueabi- -That means if you use only LLVM tools, ``CROSS_COMPILE`` becomes unnecessary. -For example, to cross-compile the arm64 kernel:: +Ccache +------ - make ARCH=arm64 LLVM=1 +``ccache`` can be used with ``clang`` to improve subsequent builds, (though +KBUILD_BUILD_TIMESTAMP_ should be set to a deterministic value between builds +in order to avoid 100% cache misses, see Reproducible_builds_ for more info): -If ``LLVM_IAS=0`` is specified, ``CROSS_COMPILE`` is also used to derive -``--prefix=`` to search for the GNU assembler and linker. :: + KBUILD_BUILD_TIMESTAMP='' make LLVM=1 CC="ccache clang" - make ARCH=arm64 LLVM=1 LLVM_IAS=0 CROSS_COMPILE=aarch64-linux-gnu- +.. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp +.. _Reproducible_builds: reproducible-builds.html#timestamps Supported Architectures ----------------------- @@ -135,14 +164,17 @@ yet. Bug reports are always welcome at the issue tracker below! * - hexagon - Maintained - ``LLVM=1`` + * - loongarch + - Maintained + - ``LLVM=1`` * - mips - Maintained - ``LLVM=1`` * - powerpc - Maintained - - ``CC=clang`` + - ``LLVM=1`` * - riscv - - Maintained + - Supported - ``LLVM=1`` * - s390 - Maintained @@ -171,7 +203,11 @@ Getting Help Getting LLVM ------------- -We provide prebuilt stable versions of LLVM on `kernel.org `_. +We provide prebuilt stable versions of LLVM on `kernel.org +`_. These have been optimized with profile +data for building Linux kernels, which should improve kernel build times +relative to other distributions of LLVM. + Below are links that may be useful for building LLVM from source or procuring it through a distribution's package manager. -- cgit From 7cd343008b967423b06af8f6d3236749c67d12e8 Mon Sep 17 00:00:00 2001 From: Sergey Senozhatsky Date: Wed, 30 Aug 2023 09:49:36 +0900 Subject: kconfig: add warn-unknown-symbols sanity check Introduce KCONFIG_WARN_UNKNOWN_SYMBOLS environment variable, which makes Kconfig warn about unknown config symbols. This is especially useful for continuous kernel uprevs when some symbols can be either removed or renamed between kernel releases (which can go unnoticed otherwise). By default KCONFIG_WARN_UNKNOWN_SYMBOLS generates warnings, which are non-terminal. There is an additional environment variable KCONFIG_WERROR that overrides this behaviour and turns warnings into errors. Signed-off-by: Sergey Senozhatsky Signed-off-by: Masahiro Yamada --- Documentation/kbuild/kconfig.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'Documentation/kbuild') diff --git a/Documentation/kbuild/kconfig.rst b/Documentation/kbuild/kconfig.rst index 463914a7fdec..b8327e89ea51 100644 --- a/Documentation/kbuild/kconfig.rst +++ b/Documentation/kbuild/kconfig.rst @@ -54,6 +54,15 @@ KCONFIG_OVERWRITECONFIG If you set KCONFIG_OVERWRITECONFIG in the environment, Kconfig will not break symlinks when .config is a symlink to somewhere else. +KCONFIG_WARN_UNKNOWN_SYMBOLS +---------------------------- +This environment variable makes Kconfig warn about all unrecognized +symbols in the config input. + +KCONFIG_WERROR +-------------- +If set, Kconfig treats warnings as errors. + `CONFIG_` --------- If you set `CONFIG_` in the environment, Kconfig will prefix all symbols -- cgit