From patchwork Mon Nov 23 04:53:57 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Masahiro Yamada X-Patchwork-Id: 11924369 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-17.0 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,INCLUDES_CR_TRAILER,INCLUDES_PATCH,MAILING_LIST_MULTI, SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 0D22BC2D0E4 for ; Mon, 23 Nov 2020 04:55:40 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id B1FC7208B8 for ; Mon, 23 Nov 2020 04:55:39 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (2048-bit key) header.d=nifty.com header.i=@nifty.com header.b="PxmMBS8t" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727056AbgKWEzT (ORCPT ); Sun, 22 Nov 2020 23:55:19 -0500 Received: from conuserg-08.nifty.com ([210.131.2.75]:27300 "EHLO conuserg-08.nifty.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1725831AbgKWEzT (ORCPT ); Sun, 22 Nov 2020 23:55:19 -0500 Received: from grover.flets-west.jp (softbank126090211135.bbtec.net [126.90.211.135]) (authenticated) by conuserg-08.nifty.com with ESMTP id 0AN4sGHd016676; Mon, 23 Nov 2020 13:54:16 +0900 DKIM-Filter: OpenDKIM Filter v2.10.3 conuserg-08.nifty.com 0AN4sGHd016676 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nifty.com; s=dec2015msa; t=1606107257; bh=/o5wTvKOLZQLtQV9dPLOE9QXEXpoApG//zQm3uD9KRU=; h=From:To:Cc:Subject:Date:From; b=PxmMBS8tngOoTqQDbyGX9XiC/WpTr/hotBhOknWjj2HpKnns7915HCM8+lITRFnW8 fOSXycBYwvRwTIqy0D+PjyPg1ADqNzPL5qVLPiE8GG5Hb4eY24mKbaZfUzzzJ1FqH3 F2Pm0CbREAu3pSTGPPORPU/rvmX6CnPh1I+yoh4v/qtlp8VICn407Oq2RUjwFIq0H9 U4tTVuQtnBgVah5ddX3RQBybmphpOPciTPt3Z+46PF9Lxi8mrQx+FX2V3IjwT59XUX gDKPpatCsauQEoPM1SAf2bqnCIV2PZhIIybV7UvM5/6YTp9PGl/517iBnhgnaCKxO3 x7sgmljLQZhxQ== X-Nifty-SrcIP: [126.90.211.135] From: Masahiro Yamada To: linux-kbuild@vger.kernel.org Cc: Randy Dunlap , Masahiro Yamada , Jonathan Corbet , Michal Marek , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 1/7] kbuild: doc: update the description about kbuild Makefiles Date: Mon, 23 Nov 2020 13:53:57 +0900 Message-Id: <20201123045403.63402-1-masahiroy@kernel.org> X-Mailer: git-send-email 2.25.1 MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-kbuild@vger.kernel.org This line was written in 2003. Now we have much more Makefiles. The number of Makefiles is not important. The point is we have a Makefile in (almost) every directory. Signed-off-by: Masahiro Yamada --- Documentation/kbuild/makefiles.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst index 0d5dd5413af0..a7b874097a91 100644 --- a/Documentation/kbuild/makefiles.rst +++ b/Documentation/kbuild/makefiles.rst @@ -71,7 +71,7 @@ The Makefiles have five parts:: .config the kernel configuration file. arch/$(ARCH)/Makefile the arch Makefile. scripts/Makefile.* common rules etc. for all kbuild Makefiles. - kbuild Makefiles there are about 500 of these. + kbuild Makefiles exist in every subdirectory The top Makefile reads the .config file, which comes from the kernel configuration process. From patchwork Mon Nov 23 04:53:58 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Masahiro Yamada X-Patchwork-Id: 11924371 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-17.0 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,INCLUDES_CR_TRAILER,INCLUDES_PATCH,MAILING_LIST_MULTI, SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 70284C6379F for ; Mon, 23 Nov 2020 04:55:41 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 2C964208B8 for ; Mon, 23 Nov 2020 04:55:41 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (2048-bit key) header.d=nifty.com header.i=@nifty.com header.b="UL3I2wxd" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727728AbgKWEzW (ORCPT ); Sun, 22 Nov 2020 23:55:22 -0500 Received: from conuserg-08.nifty.com ([210.131.2.75]:27323 "EHLO conuserg-08.nifty.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726932AbgKWEzW (ORCPT ); Sun, 22 Nov 2020 23:55:22 -0500 Received: from grover.flets-west.jp (softbank126090211135.bbtec.net [126.90.211.135]) (authenticated) by conuserg-08.nifty.com with ESMTP id 0AN4sGHe016676; Mon, 23 Nov 2020 13:54:17 +0900 DKIM-Filter: OpenDKIM Filter v2.10.3 conuserg-08.nifty.com 0AN4sGHe016676 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nifty.com; s=dec2015msa; t=1606107258; bh=gmymTY8KhGb9eBSOX2oCnJvdA/j6bzHY2nSbUJ/4dvg=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=UL3I2wxdEkRRKrCrQ7vO4TljoOMiqb3xqC0VBAXnMNNDhAL05nTQCf6xiIbNc5bwo nZMn5ZsLBPnWeDUWxQ7MXqm+iD3RP3g4xN9pa+9wwGVgeu7Sc5wPlYlUNq3T1yXdgI iWsKByqb3BnGQkyxDWo5kKiKbp1oCrh7CISP0idhTCn58CNuVSiDGuR/6Jc6WOOPhz m0nh1RK3Rk6XRxwo7GkpMPG8Y2BEa2gBU8sJ1Lr4RSKG8gmL7nu2KW35POkpT0sPZV wBpAE6CHgkp9L3xxGOHeTq+9SLsjn9C2GGLAKE2+Qst9O0aV4NqVyZMWKqRJ+7aIL+ aQ357dRQBKk/Q== X-Nifty-SrcIP: [126.90.211.135] From: Masahiro Yamada To: linux-kbuild@vger.kernel.org Cc: Randy Dunlap , Masahiro Yamada , Jonathan Corbet , Michal Marek , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 2/7] kbuild: doc: replace arch/$(ARCH)/ with arch/$(SRCARCH)/ Date: Mon, 23 Nov 2020 13:53:58 +0900 Message-Id: <20201123045403.63402-2-masahiroy@kernel.org> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20201123045403.63402-1-masahiroy@kernel.org> References: <20201123045403.63402-1-masahiroy@kernel.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-kbuild@vger.kernel.org Precisely speaking, the arch directory is specified by $(SRCARCH), not $(ARCH). In old days, $(ARCH) actually matched to the arch directory because 32-bit and 64-bit were supported as separate architectures. Most architectures (except arm/arm64) were unified like follows: arch/i386, arch/x86_64 -> arch/x86 arch/sh, arch/sh64 -> arch/sh arch/sparc, arch/sparc64 -> arch/sparc To not break the user interface, commit 6752ed90da03 ("Kbuild: allow arch/xxx to use a different source path") introduced SRCARCH to point to the arch directory, still allowing to pass in the former ARCH=i386 or ARCH=x86_64. Update the documents for preciseness, and add the explanation of SRCARCH. Signed-off-by: Masahiro Yamada Reviewed-by: Randy Dunlap --- Documentation/kbuild/makefiles.rst | 61 +++++++++++++++++------------- Documentation/kbuild/modules.rst | 2 +- 2 files changed, 35 insertions(+), 28 deletions(-) diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst index a7b874097a91..2a5232b321af 100644 --- a/Documentation/kbuild/makefiles.rst +++ b/Documentation/kbuild/makefiles.rst @@ -67,11 +67,11 @@ This document describes the Linux kernel Makefiles. The Makefiles have five parts:: - Makefile the top Makefile. - .config the kernel configuration file. - arch/$(ARCH)/Makefile the arch Makefile. - scripts/Makefile.* common rules etc. for all kbuild Makefiles. - kbuild Makefiles exist in every subdirectory + Makefile the top Makefile. + .config the kernel configuration file. + arch/$(SRCARCH)/Makefile the arch Makefile. + scripts/Makefile.* common rules etc. for all kbuild Makefiles. + kbuild Makefiles exist in every subdirectory The top Makefile reads the .config file, which comes from the kernel configuration process. @@ -82,7 +82,7 @@ It builds these goals by recursively descending into the subdirectories of the kernel source tree. The list of subdirectories which are visited depends upon the kernel configuration. The top Makefile textually includes an arch Makefile -with the name arch/$(ARCH)/Makefile. The arch Makefile supplies +with the name arch/$(SRCARCH)/Makefile. The arch Makefile supplies architecture-specific information to the top Makefile. Each subdirectory has a kbuild Makefile which carries out the commands @@ -933,7 +933,7 @@ When "make clean" is executed, make will descend down in arch/x86/boot, and clean as usual. The Makefile located in arch/x86/boot/ may use the subdir- trick to descend further down. -Note 1: arch/$(ARCH)/Makefile cannot use "subdir-", because that file is +Note 1: arch/$(SRCARCH)/Makefile cannot use "subdir-", because that file is included in the top level makefile, and the kbuild infrastructure is not operational at that point. @@ -946,9 +946,9 @@ be visited during "make clean". The top level Makefile sets up the environment and does the preparation, before starting to descend down in the individual directories. The top level makefile contains the generic part, whereas -arch/$(ARCH)/Makefile contains what is required to set up kbuild +arch/$(SRCARCH)/Makefile contains what is required to set up kbuild for said architecture. -To do so, arch/$(ARCH)/Makefile sets up a number of variables and defines +To do so, arch/$(SRCARCH)/Makefile sets up a number of variables and defines a few targets. When kbuild executes, the following steps are followed (roughly): @@ -956,14 +956,14 @@ When kbuild executes, the following steps are followed (roughly): 1) Configuration of the kernel => produce .config 2) Store kernel version in include/linux/version.h 3) Updating all other prerequisites to the target prepare: - - Additional prerequisites are specified in arch/$(ARCH)/Makefile + - Additional prerequisites are specified in arch/$(SRCARCH)/Makefile 4) Recursively descend down in all directories listed in init-* core* drivers-* net-* libs-* and build all targets. - - The values of the above variables are expanded in arch/$(ARCH)/Makefile. + - The values of the above variables are expanded in arch/$(SRCARCH)/Makefile. 5) All object files are then linked and the resulting file vmlinux is located at the root of the obj tree. The very first objects linked are listed in head-y, assigned by - arch/$(ARCH)/Makefile. + arch/$(SRCARCH)/Makefile. 6) Finally, the architecture-specific part does any required post processing and builds the final bootimage. - This includes building boot records @@ -1169,7 +1169,7 @@ When kbuild executes, the following steps are followed (roughly): $(core-y), $(libs-y), $(drivers-y) and $(net-y). The top level Makefile defines values for all generic directories, - and arch/$(ARCH)/Makefile only adds architecture-specific + and arch/$(SRCARCH)/Makefile only adds architecture-specific directories. Example:: @@ -1189,15 +1189,15 @@ When kbuild executes, the following steps are followed (roughly): The actual goals are not standardized across architectures. It is common to locate any additional processing in a boot/ - directory below arch/$(ARCH)/. + directory below arch/$(SRCARCH)/. Kbuild does not provide any smart way to support building a - target specified in boot/. Therefore arch/$(ARCH)/Makefile shall + target specified in boot/. Therefore arch/$(SRCARCH)/Makefile shall call make manually to build a target in boot/. The recommended approach is to include shortcuts in - arch/$(ARCH)/Makefile, and use the full path when calling down - into the arch/$(ARCH)/boot/Makefile. + arch/$(SRCARCH)/Makefile, and use the full path when calling down + into the arch/$(SRCARCH)/boot/Makefile. Example:: @@ -1217,7 +1217,7 @@ When kbuild executes, the following steps are followed (roughly): #arch/x86/Makefile define archhelp - echo '* bzImage - Image (arch/$(ARCH)/boot/bzImage)' + echo '* bzImage - Compressed kernel image (arch/x86/boot/bzImage)' endif When make is executed without arguments, the first goal encountered @@ -1332,7 +1332,7 @@ When kbuild executes, the following steps are followed (roughly): objcopy Copy binary. Uses OBJCOPYFLAGS usually specified in - arch/$(ARCH)/Makefile. + arch/$(SRCARCH)/Makefile. OBJCOPYFLAGS_$@ may be used to set additional options. gzip @@ -1395,7 +1395,7 @@ When kbuild executes, the following steps are followed (roughly): -------------------------------- When the vmlinux image is built, the linker script - arch/$(ARCH)/kernel/vmlinux.lds is used. + arch/$(SRCARCH)/kernel/vmlinux.lds is used. The script is a preprocessed variant of the file vmlinux.lds.S located in the same directory. kbuild knows .lds files and includes a rule `*lds.S` -> `*lds`. @@ -1405,9 +1405,6 @@ When kbuild executes, the following steps are followed (roughly): #arch/x86/kernel/Makefile extra-y := vmlinux.lds - #Makefile - export CPPFLAGS_vmlinux.lds += -P -C -U$(ARCH) - The assignment to extra-y is used to tell kbuild to build the target vmlinux.lds. The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the @@ -1481,7 +1478,7 @@ See subsequent chapter for the syntax of the Kbuild file. If an architecture uses a verbatim copy of a header from include/asm-generic then this is listed in the file - arch/$(ARCH)/include/asm/Kbuild like this: + arch/$(SRCARCH)/include/asm/Kbuild like this: Example:: @@ -1492,7 +1489,7 @@ See subsequent chapter for the syntax of the Kbuild file. During the prepare phase of the build a wrapper include file is generated in the directory:: - arch/$(ARCH)/include/generated/asm + arch/$(SRCARCH)/include/generated/asm When a header is exported where the architecture uses the generic header a similar wrapper is generated as part @@ -1527,8 +1524,8 @@ See subsequent chapter for the syntax of the Kbuild file. to define the minimum set of ASM headers that all architectures must have. This works like optional generic-y. If a mandatory header is missing - in arch/$(ARCH)/include/(uapi/)/asm, Kbuild will automatically generate - a wrapper of the asm-generic one. + in arch/$(SRCARCH)/include/(uapi/)/asm, Kbuild will automatically + generate a wrapper of the asm-generic one. 9 Kbuild Variables ================== @@ -1564,6 +1561,16 @@ The top Makefile exports the following variables: make ARCH=m68k ... + SRCARCH + This variable speficifies the directory in arch/ to build. + + ARCH and SRCARCH may not necessarily match. A couple of arch + directories are biarch, that is, a single arch/*/ directory supports + both 32-bit and 64-bit. + + For example, you can pass in ARCH=i386, ARCH=x86_64, or ARCH=x86. + For all of them, SRCARCH=x86 because arch/x86/ supports both i386 and + x86_64. INSTALL_PATH This variable defines a place for the arch Makefiles to install diff --git a/Documentation/kbuild/modules.rst b/Documentation/kbuild/modules.rst index 85ccc878895e..a1f3eb7a43e2 100644 --- a/Documentation/kbuild/modules.rst +++ b/Documentation/kbuild/modules.rst @@ -332,7 +332,7 @@ according to the following rule: There are two notable exceptions to this rule: larger subsystems have their own directory under include/, such as include/scsi; and architecture specific headers are located - under arch/$(ARCH)/include/. + under arch/$(SRCARCH)/include/. 4.1 Kernel Includes ------------------- From patchwork Mon Nov 23 04:53:59 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Masahiro Yamada X-Patchwork-Id: 11924381 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-17.0 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,INCLUDES_CR_TRAILER,INCLUDES_PATCH,MAILING_LIST_MULTI, SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 8265EC64E90 for ; Mon, 23 Nov 2020 04:55:42 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 4E7672137B for ; Mon, 23 Nov 2020 04:55:42 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (2048-bit key) header.d=nifty.com header.i=@nifty.com header.b="qBm/pVvO" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727495AbgKWEzU (ORCPT ); Sun, 22 Nov 2020 23:55:20 -0500 Received: from conuserg-08.nifty.com ([210.131.2.75]:27299 "EHLO conuserg-08.nifty.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726610AbgKWEzT (ORCPT ); Sun, 22 Nov 2020 23:55:19 -0500 Received: from grover.flets-west.jp (softbank126090211135.bbtec.net [126.90.211.135]) (authenticated) by conuserg-08.nifty.com with ESMTP id 0AN4sGHf016676; Mon, 23 Nov 2020 13:54:18 +0900 DKIM-Filter: OpenDKIM Filter v2.10.3 conuserg-08.nifty.com 0AN4sGHf016676 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nifty.com; s=dec2015msa; t=1606107258; bh=XopIql2aS2anUu0DpQO6pJHOB2zl3/ZfY8m2DYF31N0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=qBm/pVvO3ug65CHyGgyYKB4nxldUvCx7ElduqOF2wemd/7dTd3P4khC86izWdPPFD lFFA5wKxa/vlMNJVdXA0g/SfEOCdZSqZjRZSV7DOuFwMLCsU1hJ3L4llM18RPWiOgo VwRrkU6IM15k6zw/YyjxGsPh6Uz6cGFxf3CzYqjdv5lPAUuQiClbtgsBLhj/TLHia/ knF4KYnSIpRR64PZN4MQXyUR6VGJRjSZkD1iXYpWhrjHZU4Pjs0d7DdpM6cAOLtEm7 zf0oRSJGeWOS7gZiMVPS28v7/yhQIe64buq1kl9StpyUGJiRZX06FbAHxpmec0G9Sj zC3Qj+Rd6F9oQ== X-Nifty-SrcIP: [126.90.211.135] From: Masahiro Yamada To: linux-kbuild@vger.kernel.org Cc: Randy Dunlap , Masahiro Yamada , Jonathan Corbet , Michal Marek , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 3/7] kbuild: doc: fix 'List directories to visit when descending' section Date: Mon, 23 Nov 2020 13:53:59 +0900 Message-Id: <20201123045403.63402-3-masahiroy@kernel.org> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20201123045403.63402-1-masahiroy@kernel.org> References: <20201123045403.63402-1-masahiroy@kernel.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-kbuild@vger.kernel.org Fix state information: - Fix the section number in the reference from 6.4 to 7.4. - Remove init-y and net-y. They were removed by commit 23febe375d94 ("kbuild: merge init-y into core-y") and commit 95fb6317b3ab ("kbuild: merge net-y and virt-y into drivers-y"), respectively. - Update the example because arch/sparc64/Makefile does not exit. Signed-off-by: Masahiro Yamada --- Documentation/kbuild/makefiles.rst | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst index 2a5232b321af..e1aac82ddb9c 100644 --- a/Documentation/kbuild/makefiles.rst +++ b/Documentation/kbuild/makefiles.rst @@ -278,7 +278,7 @@ more details, with real examples. actually recognize that there is a lib.a being built, the directory shall be listed in libs-y. - See also "6.4 List directories to visit when descending". + See also "7.4 List directories to visit when descending". Use of lib-y is normally restricted to `lib/` and `arch/*/lib`. @@ -1154,7 +1154,7 @@ When kbuild executes, the following steps are followed (roughly): machinery is all architecture-independent. - head-y, init-y, core-y, libs-y, drivers-y, net-y + head-y, core-y, libs-y, drivers-y $(head-y) lists objects to be linked first in vmlinux. $(libs-y) lists directories where a lib.a archive can be located. @@ -1162,11 +1162,9 @@ When kbuild executes, the following steps are followed (roughly): The rest list directories where a built-in.a object file can be located. - $(init-y) objects will be located after $(head-y). - Then the rest follows in this order: - $(core-y), $(libs-y), $(drivers-y) and $(net-y). + $(core-y), $(libs-y), $(drivers-y) The top level Makefile defines values for all generic directories, and arch/$(SRCARCH)/Makefile only adds architecture-specific @@ -1174,11 +1172,14 @@ When kbuild executes, the following steps are followed (roughly): Example:: - #arch/sparc64/Makefile - core-y += arch/sparc64/kernel/ - libs-y += arch/sparc64/prom/ arch/sparc64/lib/ - drivers-$(CONFIG_OPROFILE) += arch/sparc64/oprofile/ + # arch/sparc/Makefile + core-y += arch/sparc/ + + libs-y += arch/sparc/prom/ + libs-y += arch/sparc/lib/ + drivers-$(CONFIG_PM) += arch/sparc/power/ + drivers-$(CONFIG_OPROFILE) += arch/sparc/oprofile/ 7.5 Architecture-specific boot images ------------------------------------- From patchwork Mon Nov 23 04:54:00 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Masahiro Yamada X-Patchwork-Id: 11924377 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-17.0 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,INCLUDES_CR_TRAILER,INCLUDES_PATCH,MAILING_LIST_MULTI, SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id D0D0FC63777 for ; Mon, 23 Nov 2020 04:55:42 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 946672137B for ; Mon, 23 Nov 2020 04:55:42 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (2048-bit key) header.d=nifty.com header.i=@nifty.com header.b="B/BBS4Gk" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1725831AbgKWEzU (ORCPT ); Sun, 22 Nov 2020 23:55:20 -0500 Received: from conuserg-08.nifty.com ([210.131.2.75]:27319 "EHLO conuserg-08.nifty.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726921AbgKWEzU (ORCPT ); Sun, 22 Nov 2020 23:55:20 -0500 Received: from grover.flets-west.jp (softbank126090211135.bbtec.net [126.90.211.135]) (authenticated) by conuserg-08.nifty.com with ESMTP id 0AN4sGHg016676; Mon, 23 Nov 2020 13:54:19 +0900 DKIM-Filter: OpenDKIM Filter v2.10.3 conuserg-08.nifty.com 0AN4sGHg016676 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nifty.com; s=dec2015msa; t=1606107259; bh=hZXL0HiC/uzxZZ/LHmFB9ixB0sa5rqHBVbcuV8f3PV0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=B/BBS4GkdrmaXqa+sQimtgsT3vmCLnnWe7KT3gA7GVrym+8+jwmb5tROdzSiDDMxb CeiYvXjlMAESwhWMr++sUDsC+XR2LJ1ANWeH0WmFuscTat1sJGkudbRUTGbM7Wx6uo yRNDnMQVxW1uw7dk762TfvGg4Xwh4ZeM7y0ujV5K0LVhe0lz5bHFo7JydpoyNw1Jk1 L/cltu9lRDS5JBMSw/FMBPYfKuY/N5aCmlIj6eQZfNUp3l4gpX+WGmm7dKWd3Sllmo VrdQF0lCZZqNFQNh18uMJR1JQTckzgQlmFmqPAwJWE4rUz2R5eDLXe7iW5HK+S+fUw BlZKuSUFeQBlA== X-Nifty-SrcIP: [126.90.211.135] From: Masahiro Yamada To: linux-kbuild@vger.kernel.org Cc: Randy Dunlap , Masahiro Yamada , Jonathan Corbet , Michal Marek , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 4/7] kbuild: doc: merge 'Special Rules' and 'Custom kbuild commands' sections Date: Mon, 23 Nov 2020 13:54:00 +0900 Message-Id: <20201123045403.63402-4-masahiroy@kernel.org> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20201123045403.63402-1-masahiroy@kernel.org> References: <20201123045403.63402-1-masahiroy@kernel.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-kbuild@vger.kernel.org The two sections "3.10 Special Rules" and "7.8 Custom kbuild commands" are related because you must understand both of them when you write custom rules. Actually I do not understand the policy about what to go into "3 The kbuild files" and what into "7 Architecture Makefile". This commit reworks the custom rule explanation as follows: - Merged "7.8 Custom kbuild commands" into "3.10 Special Rules". - Reword "Special Rules" to "Custom Rules" for consistency. - Update the example for kecho because the blackfin Makefile does not exist any more. - Replace the example for cmd_ with a simpler one. Signed-off-by: Masahiro Yamada --- Documentation/kbuild/makefiles.rst | 88 ++++++++++++++---------------- 1 file changed, 40 insertions(+), 48 deletions(-) diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst index e1aac82ddb9c..f5a983709df7 100644 --- a/Documentation/kbuild/makefiles.rst +++ b/Documentation/kbuild/makefiles.rst @@ -18,7 +18,7 @@ This document describes the Linux kernel Makefiles. --- 3.7 Compilation flags --- 3.8 --- 3.9 Dependency tracking - --- 3.10 Special Rules + --- 3.10 Custom Rules --- 3.11 $(CC) support functions --- 3.12 $(LD) support functions --- 3.13 Script Invocation @@ -46,7 +46,7 @@ This document describes the Linux kernel Makefiles. --- 7.5 Architecture-specific boot images --- 7.6 Building non-kbuild targets --- 7.7 Commands useful for building a boot image - --- 7.8 Custom kbuild commands + --- 7.8 --- 7.9 Preprocessing linker scripts --- 7.10 Generic header files --- 7.11 Post-link pass @@ -422,21 +422,21 @@ more details, with real examples. Thus, if you change an option to $(CC) all affected files will be re-compiled. -3.10 Special Rules +3.10 Custom Rules ------------------ - Special rules are used when the kbuild infrastructure does + Custom rules are used when the kbuild infrastructure does not provide the required support. A typical example is header files generated during the build process. Another example are the architecture-specific Makefiles which - need special rules to prepare boot images etc. + need custom rules to prepare boot images etc. - Special rules are written as normal Make rules. + Custom rules are written as normal Make rules. Kbuild is not executing in the directory where the Makefile is - located, so all special rules shall provide a relative + located, so all custom rules shall use a relative path to prerequisite files and target files. - Two variables are used when defining special rules: + Two variables are used when defining custom rules: $(src) $(src) is a relative path which points to the directory @@ -454,7 +454,7 @@ more details, with real examples. $(obj)/53c8xx_d.h: $(src)/53c7,8xx.scr $(src)/script_asm.pl $(CPP) -DCHIP=810 - < $< | ... $(src)/script_asm.pl - This is a special rule, following the normal syntax + This is a custom rule, following the normal syntax required by make. The target file depends on two prerequisite files. References @@ -471,11 +471,33 @@ more details, with real examples. Example:: - #arch/blackfin/boot/Makefile - $(obj)/vmImage: $(obj)/vmlinux.gz - $(call if_changed,uimage) - @$(kecho) 'Kernel: $@ is ready' + # arch/arm/Makefile + $(BOOT_TARGETS): vmlinux + $(Q)$(MAKE) $(build)=$(boot) MACHINE=$(MACHINE) $(boot)/$@ + @$(kecho) ' Kernel: $(boot)/$@ is ready' + When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthand + of a command is normally displayed. + To enable this behaviour for custom commands kbuild requires + two variables to be set:: + + quiet_cmd_ - what shall be echoed + cmd_ - the command to execute + + Example:: + + # lib/Makefile + quiet_cmd_crc32 = GEN $@ + cmd_crc32 = $< > $@ + + $(obj)/crc32table.h: $(obj)/gen_crc32table + $(call cmd,crc32) + + When updating the $(obj)/crc32table.h target, the line: + + GEN lib/crc32table.h + + will be displayed with "make KBUILD_VERBOSE=0". 3.11 $(CC) support functions ---------------------------- @@ -744,7 +766,7 @@ Both possibilities are described in the following. as a prerequisite. This is possible in two ways: - (1) List the prerequisite explicitly in a special rule. + (1) List the prerequisite explicitly in a custom rule. Example:: @@ -755,11 +777,11 @@ Both possibilities are described in the following. The target $(obj)/devlist.h will not be built before $(obj)/gen-devlist is updated. Note that references to - the host programs in special rules must be prefixed with $(obj). + the host programs in custom rules must be prefixed with $(obj). (2) Use always-y - When there is no suitable special rule, and the host program + When there is no suitable custom rule, and the host program shall be built when a makefile is entered, the always-y variable shall be used. @@ -1281,8 +1303,8 @@ When kbuild executes, the following steps are followed (roughly): otherwise the command line check will fail, and the target will always be built. Assignments to $(targets) are without $(obj)/ prefix. - if_changed may be used in conjunction with custom commands as - defined in 7.8 "Custom kbuild commands". + if_changed may be used in conjunction with custom rules as + defined in "3.10 Custom Rules". Note: It is a typical mistake to forget the FORCE prerequisite. Another common pitfall is that whitespace is sometimes @@ -1362,36 +1384,6 @@ When kbuild executes, the following steps are followed (roughly): targets += $(dtb-y) DTC_FLAGS ?= -p 1024 -7.8 Custom kbuild commands --------------------------- - - When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthand - of a command is normally displayed. - To enable this behaviour for custom commands kbuild requires - two variables to be set:: - - quiet_cmd_ - what shall be echoed - cmd_ - the command to execute - - Example:: - - # - quiet_cmd_image = BUILD $@ - cmd_image = $(obj)/tools/build $(BUILDFLAGS) \ - $(obj)/vmlinux.bin > $@ - - targets += bzImage - $(obj)/bzImage: $(obj)/vmlinux.bin $(obj)/tools/build FORCE - $(call if_changed,image) - @echo 'Kernel: $@ is ready' - - When updating the $(obj)/bzImage target, the line: - - BUILD arch/x86/boot/bzImage - - will be displayed with "make KBUILD_VERBOSE=0". - - 7.9 Preprocessing linker scripts -------------------------------- From patchwork Mon Nov 23 04:54:01 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Masahiro Yamada X-Patchwork-Id: 11924379 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-17.0 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,INCLUDES_CR_TRAILER,INCLUDES_PATCH,MAILING_LIST_MULTI, SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 45B38C71156 for ; Mon, 23 Nov 2020 04:55:43 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 05FF6208B8 for ; Mon, 23 Nov 2020 04:55:43 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (2048-bit key) header.d=nifty.com header.i=@nifty.com header.b="UTyJutcu" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727856AbgKWEzd (ORCPT ); Sun, 22 Nov 2020 23:55:33 -0500 Received: from conuserg-08.nifty.com ([210.131.2.75]:27317 "EHLO conuserg-08.nifty.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726885AbgKWEzT (ORCPT ); Sun, 22 Nov 2020 23:55:19 -0500 Received: from grover.flets-west.jp (softbank126090211135.bbtec.net [126.90.211.135]) (authenticated) by conuserg-08.nifty.com with ESMTP id 0AN4sGHh016676; Mon, 23 Nov 2020 13:54:20 +0900 DKIM-Filter: OpenDKIM Filter v2.10.3 conuserg-08.nifty.com 0AN4sGHh016676 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nifty.com; s=dec2015msa; t=1606107260; bh=UaokmMy66noPBcllqXh/sjDOT6CGTkZW3p03cwQ7oPE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=UTyJutcuEhCq7ktGgTSJJWNN4w5yvfmuMF946o9s4IidT48CZMmWZvuSY7GSevRZm lMWeIAaEo7pirj+cCxVO25BkgYg34bxUwzQUabGbdadM8LMskcJ4O5Oa63WBk7mvuR 6gzynMBJwQqKIaPcX6+fpsfRaCa3DiPCGpN/OnA4ih1xk4fhLVoQWVuJPPCKYThOjE E6sELHdj3oDD7whhI8R2nx6SXRwv67GI7LHDN0XW2IS+QPIXbFmW48HHmNqDcELK41 0i+FuzWs46cgFkPHhvcQOmGjSj9eIBNw7elatlxv/qt/y2qizqqSkUitWAt87BN4om 2GKFVAUXwXx3g== X-Nifty-SrcIP: [126.90.211.135] From: Masahiro Yamada To: linux-kbuild@vger.kernel.org Cc: Randy Dunlap , Masahiro Yamada , Jonathan Corbet , Michal Marek , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 5/7] kbuild: doc: split if_changed explanation to a separate section Date: Mon, 23 Nov 2020 13:54:01 +0900 Message-Id: <20201123045403.63402-5-masahiroy@kernel.org> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20201123045403.63402-1-masahiroy@kernel.org> References: <20201123045403.63402-1-masahiroy@kernel.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-kbuild@vger.kernel.org The if_changed macro is currently explained in the section "Commands useful for building a boot image", but the use of if_changed is not limited to the boot image. It is often used together with custom rules. Let's split it as a separate section, and insert it after the "Custom Rules" section. I slightly reworded the explanation, re-numbered to fill the section, and also fixed the broken indentation of the Note: part. Signed-off-by: Masahiro Yamada --- Documentation/kbuild/makefiles.rst | 94 +++++++++++++++++------------- 1 file changed, 52 insertions(+), 42 deletions(-) diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst index f5a983709df7..49afcb1d3695 100644 --- a/Documentation/kbuild/makefiles.rst +++ b/Documentation/kbuild/makefiles.rst @@ -16,9 +16,9 @@ This document describes the Linux kernel Makefiles. --- 3.5 Library file goals - lib-y --- 3.6 Descending down in directories --- 3.7 Compilation flags - --- 3.8 - --- 3.9 Dependency tracking - --- 3.10 Custom Rules + --- 3.8 Dependency tracking + --- 3.9 Custom Rules + --- 3.10 Command change detection --- 3.11 $(CC) support functions --- 3.12 $(LD) support functions --- 3.13 Script Invocation @@ -410,7 +410,7 @@ more details, with real examples. AFLAGS_iwmmxt.o := -Wa,-mcpu=iwmmxt -3.9 Dependency tracking +3.8 Dependency tracking ----------------------- Kbuild tracks dependencies on the following: @@ -422,8 +422,8 @@ more details, with real examples. Thus, if you change an option to $(CC) all affected files will be re-compiled. -3.10 Custom Rules ------------------- +3.9 Custom Rules +---------------- Custom rules are used when the kbuild infrastructure does not provide the required support. A typical example is @@ -499,6 +499,52 @@ more details, with real examples. will be displayed with "make KBUILD_VERBOSE=0". +3.10 Command change detection +----------------------------- + + When the rule is evaluated, timestamps are compared between the target + and its prerequisite files. GNU Make updates the target when any of the + prerequisites is newer than that. + + The target should be rebuilt also when the command line has changed + since the last invocation. This is not supported by Make itself, so + Kbuild achieves this by a kind of meta-programming. + + if_changed is the macro used for this purpose, in the following form:: + + quiet_cmt_ = ... + cmd_ = ... + + : FORCE + $(call if_changed,) + + Any target that utilizes if_changed must be listed in $(targets), + otherwise the command line check will fail, and the target will + always be built. + + If the target is already listed in the recognized syntax such as + obj-y/m, lib-y/m, extra-y/m, hostprogs, userprogs, Kbuild automatically + add it to $(targets). Otherwise, the target must be explicitly added + to $(targets). + + Assignments to $(targets) are without $(obj)/ prefix. if_changed may be + used in conjunction with custom rules as defined in "3.9 Custom Rules". + + Note: It is a typical mistake to forget the FORCE prerequisite. + Another common pitfall is that whitespace is sometimes significant; for + instance, the below will fail (note the extra space after the comma):: + + target: source(s) FORCE + + **WRONG!** $(call if_changed, objcopy) + + Note: + if_changed should not be used more than once per target. + It stores the executed command in a corresponding .cmd + file and multiple calls would result in overwrites and + unwanted results when the target is up to date and only the + tests on changed commands trigger execution of commands. + 3.11 $(CC) support functions ---------------------------- @@ -1287,42 +1333,6 @@ When kbuild executes, the following steps are followed (roughly): Kbuild provides a few macros that are useful when building a boot image. - if_changed - if_changed is the infrastructure used for the following commands. - - Usage:: - - target: source(s) FORCE - $(call if_changed,ld/objcopy/gzip/...) - - When the rule is evaluated, it is checked to see if any files - need an update, or the command line has changed since the last - invocation. The latter will force a rebuild if any options - to the executable have changed. - Any target that utilises if_changed must be listed in $(targets), - otherwise the command line check will fail, and the target will - always be built. - Assignments to $(targets) are without $(obj)/ prefix. - if_changed may be used in conjunction with custom rules as - defined in "3.10 Custom Rules". - - Note: It is a typical mistake to forget the FORCE prerequisite. - Another common pitfall is that whitespace is sometimes - significant; for instance, the below will fail (note the extra space - after the comma):: - - target: source(s) FORCE - - **WRONG!** $(call if_changed, ld/objcopy/gzip/...) - - Note: - if_changed should not be used more than once per target. - It stores the executed command in a corresponding .cmd - - file and multiple calls would result in overwrites and - unwanted results when the target is up to date and only the - tests on changed commands trigger execution of commands. - ld Link target. Often, LDFLAGS_$@ is used to set specific options to ld. From patchwork Mon Nov 23 04:54:02 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Masahiro Yamada X-Patchwork-Id: 11924375 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-22.0 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,INCLUDES_CR_TRAILER,INCLUDES_PATCH,MAILING_LIST_MULTI, MENTIONS_GIT_HOSTING,SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 14479C64E7D for ; Mon, 23 Nov 2020 04:55:42 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id DBA04212CC for ; Mon, 23 Nov 2020 04:55:41 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (2048-bit key) header.d=nifty.com header.i=@nifty.com header.b="a57e5Kt9" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727813AbgKWEza (ORCPT ); Sun, 22 Nov 2020 23:55:30 -0500 Received: from conuserg-08.nifty.com ([210.131.2.75]:27327 "EHLO conuserg-08.nifty.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726958AbgKWEzV (ORCPT ); Sun, 22 Nov 2020 23:55:21 -0500 Received: from grover.flets-west.jp (softbank126090211135.bbtec.net [126.90.211.135]) (authenticated) by conuserg-08.nifty.com with ESMTP id 0AN4sGHi016676; Mon, 23 Nov 2020 13:54:20 +0900 DKIM-Filter: OpenDKIM Filter v2.10.3 conuserg-08.nifty.com 0AN4sGHi016676 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nifty.com; s=dec2015msa; t=1606107261; bh=8NgvnHhJy/QixGNY6u3RlD/wM4+7Ln+DlMo5AkRm9tw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=a57e5Kt9YcqObZXzoElxuvSmeViii5TgEmGhybHx79QvV6CG/4VNpc6XbNgWftNPP h7NyUttrr/JXsKIqR2jX5TBQGFeZF17wK4ZPjRy5UBtYgdMw7lWbYZqEXSYSM5gRZ5 pb3zCFZEovAOJtAdNvLXHcx79zzf13C9+hTHdeX3U9QuhWJNSpW70eOq52vjKrQaZ0 5Jdg8rNOF7kKdKcuWHo/A7Cn7E99sRsiPImj+m4KmfLb4V68SmKvl+JvSGTdS0Eqdd Ku7xdtj6MCXJAS8gQZvIASyr1gOY3EmIDON2SDQraUXAKP1f1ayahONtnNIUzMwjFo xMDU/B0qHKuaQ== X-Nifty-SrcIP: [126.90.211.135] From: Masahiro Yamada To: linux-kbuild@vger.kernel.org Cc: Randy Dunlap , Masahiro Yamada , Jonathan Corbet , Michal Marek , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 6/7] kbuild: doc: clarify the difference between extra-y and always-y Date: Mon, 23 Nov 2020 13:54:02 +0900 Message-Id: <20201123045403.63402-6-masahiroy@kernel.org> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20201123045403.63402-1-masahiroy@kernel.org> References: <20201123045403.63402-1-masahiroy@kernel.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-kbuild@vger.kernel.org The difference between extra-y and always-y is obscure. Basically, Kbuild builds targets listed in extra-y and always-y in visited Makefiles without relying on any dependency. The difference is that extra-y is used to list the targets needed for vmlinux whereas always-y is used to list the targets that must be always built irrespective of final targets. Kbuild skips extra-y when it is building only modules (i.e. 'make modules'). This is the long-standing behavior since extra-y was introduced in 2003, and it is explained in that commit log [1]. For clarification, this is the extra-y vs always-y table: extra-y always-y 'make' o o 'make vmlinux' o o 'make modules' x o Kbuild skips extra-y also when building external modules since obviously it never builds vmlinux. Unfortunately, extra-y is wrongly used in many places of upstream code, and even in external modules. Using extra-y in external module Makefiles is wrong. What you should use is probably always-y or 'targets'. The current documentation for extra-y is misleading. I rewrote it, and moved it to the section 3.7. always-y is not documented anywhere. I added. [1]: https://git.kernel.org/pub/scm/linux/kernel/git/history/history.git/commit/?id=f94e5fd7e5d09a56a60670a9bb211a791654bba8 Signed-off-by: Masahiro Yamada Reviewed-by: Randy Dunlap --- Documentation/kbuild/makefiles.rst | 110 +++++++++++++++++++---------- 1 file changed, 71 insertions(+), 39 deletions(-) diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst index 49afcb1d3695..159e470f2616 100644 --- a/Documentation/kbuild/makefiles.rst +++ b/Documentation/kbuild/makefiles.rst @@ -15,13 +15,15 @@ This document describes the Linux kernel Makefiles. --- 3.4 Objects which export symbols --- 3.5 Library file goals - lib-y --- 3.6 Descending down in directories - --- 3.7 Compilation flags - --- 3.8 Dependency tracking - --- 3.9 Custom Rules - --- 3.10 Command change detection - --- 3.11 $(CC) support functions - --- 3.12 $(LD) support functions - --- 3.13 Script Invocation + --- 3.7 Non-builtin vmlinux targets - extra-y + --- 3.8 Always built goals - always- + --- 3.9 Compilation flags + --- 3.10 Dependency tracking + --- 3.11 Custom Rules + --- 3.12 Command change detection + --- 3.13 $(CC) support functions + --- 3.14 $(LD) support functions + --- 3.15 Script Invocation === 4 Host Program support --- 4.1 Simple Host Program @@ -321,7 +323,60 @@ more details, with real examples. names. This allows kbuild to totally skip the directory if the corresponding `CONFIG_` option is neither 'y' nor 'm'. -3.7 Compilation flags +3.7 Non-builtin vmlinux targets - extra-y +----------------------------------------- + + extra-y specifies targets which are needed for building vmlinux, + but not combined into built-in.a. + + Examples are: + + 1) head objects + + Some objects must be placed at the head of vmlinux. They are + directly linked to vmlinux without going through built-in.a + A typical use-case is an object that contains the entry point. + + arch/$(SRCARCH)/Makefile should specify such objects as head-y. + + Discussion: + Given that we can control the section order in our linker script, + why do we need head-y? + + 2) vmlinux linker script + + The linker script for vmlinux is located at + arch/$(SRCARCH)/kernel/vmlinux.lds + + Example:: + + # arch/x86/kernel/Makefile + extra-y := head_$(BITS).o + extra-y += head$(BITS).o + extra-y += ebda.o + extra-y += platform-quirks.o + extra-y += vmlinux.lds + + $(extra-y) should only contain targets needed for vmlinux. + + Kbuild skips extra-y when vmlinux is apparently not a final goal. + (e.g. 'make modules', or building external modules) + + If you intend to build targets unconditionally, always-y (explained + in the next section) is the correct syntax to use. + +3.8 Always built goals - always-y +--------------------------------- + + always-y specifies targets which are literally always built when + Kbuild visited the Makefile. + + Example:: + # ./Kbuild + offsets-file := include/generated/asm-offsets.h + always-y += $(offsets-file) + +3.9 Compilation flags --------------------- ccflags-y, asflags-y and ldflags-y @@ -410,8 +465,8 @@ more details, with real examples. AFLAGS_iwmmxt.o := -Wa,-mcpu=iwmmxt -3.8 Dependency tracking ------------------------ +3.10 Dependency tracking +------------------------ Kbuild tracks dependencies on the following: @@ -422,8 +477,8 @@ more details, with real examples. Thus, if you change an option to $(CC) all affected files will be re-compiled. -3.9 Custom Rules ----------------- +3.11 Custom Rules +----------------- Custom rules are used when the kbuild infrastructure does not provide the required support. A typical example is @@ -499,7 +554,7 @@ more details, with real examples. will be displayed with "make KBUILD_VERBOSE=0". -3.10 Command change detection +3.12 Command change detection ----------------------------- When the rule is evaluated, timestamps are compared between the target @@ -545,7 +600,7 @@ more details, with real examples. unwanted results when the target is up to date and only the tests on changed commands trigger execution of commands. -3.11 $(CC) support functions +3.13 $(CC) support functions ---------------------------- The kernel may be built with several different versions of @@ -660,7 +715,7 @@ more details, with real examples. endif endif -3.12 $(LD) support functions +3.14 $(LD) support functions ---------------------------- ld-option @@ -674,7 +729,7 @@ more details, with real examples. #Makefile LDFLAGS_vmlinux += $(call ld-option, -X) -3.13 Script invocation +3.15 Script invocation ---------------------- Make rules may invoke scripts to build the kernel. The rules shall @@ -1304,29 +1359,6 @@ When kbuild executes, the following steps are followed (roughly): When "make" is executed without arguments, bzImage will be built. -7.6 Building non-kbuild targets -------------------------------- - - extra-y - extra-y specifies additional targets created in the current - directory, in addition to any targets specified by `obj-*`. - - Listing all targets in extra-y is required for two purposes: - - 1) Enable kbuild to check changes in command lines - - - When $(call if_changed,xxx) is used - - 2) kbuild knows what files to delete during "make clean" - - Example:: - - #arch/x86/kernel/Makefile - extra-y := head.o init_task.o - - In this example, extra-y is used to list object files that - shall be built, but shall not be linked as part of built-in.a. - 7.7 Commands useful for building a boot image --------------------------------------------- From patchwork Mon Nov 23 04:54:03 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Masahiro Yamada X-Patchwork-Id: 11924373 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-17.0 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,INCLUDES_CR_TRAILER,INCLUDES_PATCH,MAILING_LIST_MULTI, SPF_HELO_NONE,SPF_PASS,USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 3CE48C64E8A for ; Mon, 23 Nov 2020 04:55:42 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 08B662145D for ; Mon, 23 Nov 2020 04:55:42 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (2048-bit key) header.d=nifty.com header.i=@nifty.com header.b="PV2/7AQ0" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727530AbgKWEzV (ORCPT ); Sun, 22 Nov 2020 23:55:21 -0500 Received: from conuserg-08.nifty.com ([210.131.2.75]:27311 "EHLO conuserg-08.nifty.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726861AbgKWEzT (ORCPT ); Sun, 22 Nov 2020 23:55:19 -0500 Received: from grover.flets-west.jp (softbank126090211135.bbtec.net [126.90.211.135]) (authenticated) by conuserg-08.nifty.com with ESMTP id 0AN4sGHj016676; Mon, 23 Nov 2020 13:54:21 +0900 DKIM-Filter: OpenDKIM Filter v2.10.3 conuserg-08.nifty.com 0AN4sGHj016676 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nifty.com; s=dec2015msa; t=1606107261; bh=OiWvzr+PPEES1+WiZtvnEdTynTSS1JuRWBS71ZMozL0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=PV2/7AQ0QWcMI4GeBHWkFmhLprNvWXA7F0X+mazSUI/NL/HRSztRTK8hY5wV6Evmh 9fuAhyVgxyoJ2NaqYA8BEziqNaWwwVaoKRpsMnSTjw82RFu4QAyAT0ZxwVKWvVCXmE yoWM+Z6tQ2DIb0j/JGHKjAX0KTgRDdARgMI0wJ0gis8GmplVHksz2DwHqaMepKA5Me IM5CC+R5trZADC2JQgjAXfZ2wNqvfWRYPYOfVl52aGQzttp+fLd/4WBGjjDw4QfyHR CnLuj8UbJxUTYY46Pjn/cmWY1jO4B7rY7wvMcSTPRjI8kl/chQIqZ8HZ+aywhrL+sK lSoJvGzSOUocA== X-Nifty-SrcIP: [126.90.211.135] From: Masahiro Yamada To: linux-kbuild@vger.kernel.org Cc: Randy Dunlap , Masahiro Yamada , Jonathan Corbet , Michal Marek , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 7/7] kbuild: doc: document subdir-y syntax Date: Mon, 23 Nov 2020 13:54:03 +0900 Message-Id: <20201123045403.63402-7-masahiroy@kernel.org> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20201123045403.63402-1-masahiroy@kernel.org> References: <20201123045403.63402-1-masahiroy@kernel.org> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-kbuild@vger.kernel.org There is no explanation about subdir-y. Let's document it. Signed-off-by: Masahiro Yamada Reviewed-by: Randy Dunlap --- Documentation/kbuild/makefiles.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst index 159e470f2616..6332b9ca7942 100644 --- a/Documentation/kbuild/makefiles.rst +++ b/Documentation/kbuild/makefiles.rst @@ -319,6 +319,20 @@ more details, with real examples. that directory specifies obj-y, those objects will be left orphan. It is very likely a bug of the Makefile or of dependencies in Kconfig. + Kbuild also supports dedicated syntax, subdir-y and subdir-m, for + descending into subdirectories. It is a good fit when you know they + do not contain kernel-space objects at all. A typical usage is to let + Kbuild descend into subdirectories to build tools. + + Examples:: + + subdir-$(CONFIG_GCC_PLUGINS) += gcc-plugins + subdir-$(CONFIG_MODVERSIONS) += genksyms + subdir-$(CONFIG_SECURITY_SELINUX) += selinux + + Unlike obj-y/m, subdir-y/m does not need the trailing slash since this + syntax is always used for directories. + It is good practice to use a `CONFIG_` variable when assigning directory names. This allows kbuild to totally skip the directory if the corresponding `CONFIG_` option is neither 'y' nor 'm'.