Commit | Line | Data |
---|---|---|
cd238eff | 1 | ====================== |
1da177e4 | 2 | Linux Kernel Makefiles |
cd238eff | 3 | ====================== |
1da177e4 LT |
4 | |
5 | This document describes the Linux kernel Makefiles. | |
6 | ||
1a4c1c9d JN |
7 | Overview |
8 | ======== | |
1da177e4 | 9 | |
cd238eff | 10 | The Makefiles have five parts:: |
1da177e4 | 11 | |
8c4d9b14 MY |
12 | Makefile the top Makefile. |
13 | .config the kernel configuration file. | |
14 | arch/$(SRCARCH)/Makefile the arch Makefile. | |
15 | scripts/Makefile.* common rules etc. for all kbuild Makefiles. | |
16 | kbuild Makefiles exist in every subdirectory | |
1da177e4 LT |
17 | |
18 | The top Makefile reads the .config file, which comes from the kernel | |
19 | configuration process. | |
20 | ||
21 | The top Makefile is responsible for building two major products: vmlinux | |
22 | (the resident kernel image) and modules (any module files). | |
23 | It builds these goals by recursively descending into the subdirectories of | |
24 | the kernel source tree. | |
9f1fe2bb | 25 | |
1da177e4 LT |
26 | The list of subdirectories which are visited depends upon the kernel |
27 | configuration. The top Makefile textually includes an arch Makefile | |
8c4d9b14 | 28 | with the name arch/$(SRCARCH)/Makefile. The arch Makefile supplies |
1da177e4 LT |
29 | architecture-specific information to the top Makefile. |
30 | ||
31 | Each subdirectory has a kbuild Makefile which carries out the commands | |
32 | passed down from above. The kbuild Makefile uses information from the | |
39e6e9cf | 33 | .config file to construct various file lists used by kbuild to build |
1da177e4 LT |
34 | any built-in or modular targets. |
35 | ||
36 | scripts/Makefile.* contains all the definitions/rules etc. that | |
37 | are used to build the kernel based on the kbuild makefiles. | |
38 | ||
1a4c1c9d JN |
39 | Who does what |
40 | ============= | |
1da177e4 LT |
41 | |
42 | People have four different relationships with the kernel Makefiles. | |
43 | ||
44 | *Users* are people who build kernels. These people type commands such as | |
2f0e2a39 | 45 | ``make menuconfig`` or ``make``. They usually do not read or edit |
1da177e4 LT |
46 | any kernel Makefiles (or any other source files). |
47 | ||
48 | *Normal developers* are people who work on features such as device | |
49 | drivers, file systems, and network protocols. These people need to | |
a07f6033 | 50 | maintain the kbuild Makefiles for the subsystem they are |
1da177e4 LT |
51 | working on. In order to do this effectively, they need some overall |
52 | knowledge about the kernel Makefiles, plus detailed knowledge about the | |
53 | public interface for kbuild. | |
54 | ||
55 | *Arch developers* are people who work on an entire architecture, such | |
94483490 | 56 | as sparc or x86. Arch developers need to know about the arch Makefile |
1da177e4 LT |
57 | as well as kbuild Makefiles. |
58 | ||
59 | *Kbuild developers* are people who work on the kernel build system itself. | |
60 | These people need to know about all aspects of the kernel Makefiles. | |
61 | ||
62 | This document is aimed towards normal developers and arch developers. | |
63 | ||
64 | ||
1a4c1c9d JN |
65 | The kbuild files |
66 | ================ | |
1da177e4 LT |
67 | |
68 | Most Makefiles within the kernel are kbuild Makefiles that use the | |
a07f6033 | 69 | kbuild infrastructure. This chapter introduces the syntax used in the |
1da177e4 | 70 | kbuild makefiles. |
9f1fe2bb | 71 | |
2f0e2a39 JN |
72 | The preferred name for the kbuild files are ``Makefile`` but ``Kbuild`` can |
73 | be used and if both a ``Makefile`` and a ``Kbuild`` file exists, then the ``Kbuild`` | |
172c3ae3 | 74 | file will be used. |
1da177e4 | 75 | |
1a4c1c9d | 76 | Section `Goal definitions`_ is a quick intro; further chapters provide |
1da177e4 LT |
77 | more details, with real examples. |
78 | ||
1a4c1c9d JN |
79 | Goal definitions |
80 | ---------------- | |
1da177e4 | 81 | |
9f1fe2bb JN |
82 | Goal definitions are the main part (heart) of the kbuild Makefile. |
83 | These lines define the files to be built, any special compilation | |
84 | options, and any subdirectories to be entered recursively. | |
1da177e4 | 85 | |
9f1fe2bb | 86 | The most simple kbuild makefile contains one line: |
1da177e4 | 87 | |
9f1fe2bb | 88 | Example:: |
cd238eff | 89 | |
9f1fe2bb | 90 | obj-y += foo.o |
1da177e4 | 91 | |
9f1fe2bb JN |
92 | This tells kbuild that there is one object in that directory, named |
93 | foo.o. foo.o will be built from foo.c or foo.S. | |
1da177e4 | 94 | |
9f1fe2bb JN |
95 | If foo.o shall be built as a module, the variable obj-m is used. |
96 | Therefore the following pattern is often used: | |
1da177e4 | 97 | |
9f1fe2bb | 98 | Example:: |
cd238eff | 99 | |
9f1fe2bb | 100 | obj-$(CONFIG_FOO) += foo.o |
1da177e4 | 101 | |
9f1fe2bb JN |
102 | $(CONFIG_FOO) evaluates to either y (for built-in) or m (for module). |
103 | If CONFIG_FOO is neither y nor m, then the file will not be compiled | |
104 | nor linked. | |
1da177e4 | 105 | |
1a4c1c9d JN |
106 | Built-in object goals - obj-y |
107 | ----------------------------- | |
1da177e4 | 108 | |
9f1fe2bb JN |
109 | The kbuild Makefile specifies object files for vmlinux |
110 | in the $(obj-y) lists. These lists depend on the kernel | |
111 | configuration. | |
1da177e4 | 112 | |
9f1fe2bb | 113 | Kbuild compiles all the $(obj-y) files. It then calls |
2f0e2a39 | 114 | ``$(AR) rcSTP`` to merge these files into one built-in.a file. |
9f1fe2bb JN |
115 | This is a thin archive without a symbol table. It will be later |
116 | linked into vmlinux by scripts/link-vmlinux.sh | |
1da177e4 | 117 | |
9f1fe2bb JN |
118 | The order of files in $(obj-y) is significant. Duplicates in |
119 | the lists are allowed: the first instance will be linked into | |
120 | built-in.a and succeeding instances will be ignored. | |
1da177e4 | 121 | |
9f1fe2bb JN |
122 | Link order is significant, because certain functions |
123 | (module_init() / __initcall) will be called during boot in the | |
124 | order they appear. So keep in mind that changing the link | |
125 | order may e.g. change the order in which your SCSI | |
126 | controllers are detected, and thus your disks are renumbered. | |
1da177e4 | 127 | |
9f1fe2bb | 128 | Example:: |
cd238eff | 129 | |
9f1fe2bb JN |
130 | #drivers/isdn/i4l/Makefile |
131 | # Makefile for the kernel ISDN subsystem and device drivers. | |
132 | # Each configuration option enables a list of files. | |
133 | obj-$(CONFIG_ISDN_I4L) += isdn.o | |
134 | obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o | |
1da177e4 | 135 | |
1a4c1c9d JN |
136 | Loadable module goals - obj-m |
137 | ----------------------------- | |
1da177e4 | 138 | |
9f1fe2bb JN |
139 | $(obj-m) specifies object files which are built as loadable |
140 | kernel modules. | |
1da177e4 | 141 | |
9f1fe2bb JN |
142 | A module may be built from one source file or several source |
143 | files. In the case of one source file, the kbuild makefile | |
144 | simply adds the file to $(obj-m). | |
1da177e4 | 145 | |
9f1fe2bb | 146 | Example:: |
cd238eff | 147 | |
9f1fe2bb JN |
148 | #drivers/isdn/i4l/Makefile |
149 | obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o | |
1da177e4 | 150 | |
2f0e2a39 | 151 | Note: In this example $(CONFIG_ISDN_PPP_BSDCOMP) evaluates to "m" |
1da177e4 | 152 | |
9f1fe2bb JN |
153 | If a kernel module is built from several source files, you specify |
154 | that you want to build a module in the same way as above; however, | |
155 | kbuild needs to know which object files you want to build your | |
156 | module from, so you have to tell it by setting a $(<module_name>-y) | |
157 | variable. | |
1da177e4 | 158 | |
9f1fe2bb | 159 | Example:: |
cd238eff | 160 | |
9f1fe2bb JN |
161 | #drivers/isdn/i4l/Makefile |
162 | obj-$(CONFIG_ISDN_I4L) += isdn.o | |
163 | isdn-y := isdn_net_lib.o isdn_v110.o isdn_common.o | |
1da177e4 | 164 | |
9f1fe2bb JN |
165 | In this example, the module name will be isdn.o. Kbuild will |
166 | compile the objects listed in $(isdn-y) and then run | |
2f0e2a39 | 167 | ``$(LD) -r`` on the list of these files to generate isdn.o. |
1da177e4 | 168 | |
9f1fe2bb | 169 | Due to kbuild recognizing $(<module_name>-y) for composite objects, |
2f0e2a39 | 170 | you can use the value of a ``CONFIG_`` symbol to optionally include an |
9f1fe2bb | 171 | object file as part of a composite object. |
1da177e4 | 172 | |
9f1fe2bb | 173 | Example:: |
cd238eff | 174 | |
9f1fe2bb JN |
175 | #fs/ext2/Makefile |
176 | obj-$(CONFIG_EXT2_FS) += ext2.o | |
177 | ext2-y := balloc.o dir.o file.o ialloc.o inode.o ioctl.o \ | |
178 | namei.o super.o symlink.o | |
179 | ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o xattr_user.o \ | |
180 | xattr_trusted.o | |
4f827280 | 181 | |
9f1fe2bb JN |
182 | In this example, xattr.o, xattr_user.o and xattr_trusted.o are only |
183 | part of the composite object ext2.o if $(CONFIG_EXT2_FS_XATTR) | |
2f0e2a39 | 184 | evaluates to "y". |
1da177e4 | 185 | |
9f1fe2bb JN |
186 | Note: Of course, when you are building objects into the kernel, |
187 | the syntax above will also work. So, if you have CONFIG_EXT2_FS=y, | |
188 | kbuild will build an ext2.o file for you out of the individual | |
189 | parts and then link this into built-in.a, as you would expect. | |
1da177e4 | 190 | |
1a4c1c9d JN |
191 | Library file goals - lib-y |
192 | -------------------------- | |
1da177e4 | 193 | |
9f1fe2bb JN |
194 | Objects listed with obj-* are used for modules, or |
195 | combined in a built-in.a for that specific directory. | |
196 | There is also the possibility to list objects that will | |
197 | be included in a library, lib.a. | |
198 | All objects listed with lib-y are combined in a single | |
199 | library for that directory. | |
200 | Objects that are listed in obj-y and additionally listed in | |
201 | lib-y will not be included in the library, since they will | |
202 | be accessible anyway. | |
203 | For consistency, objects listed in lib-m will be included in lib.a. | |
1da177e4 | 204 | |
9f1fe2bb JN |
205 | Note that the same kbuild makefile may list files to be built-in |
206 | and to be part of a library. Therefore the same directory | |
207 | may contain both a built-in.a and a lib.a file. | |
1da177e4 | 208 | |
9f1fe2bb | 209 | Example:: |
cd238eff | 210 | |
9f1fe2bb JN |
211 | #arch/x86/lib/Makefile |
212 | lib-y := delay.o | |
1da177e4 | 213 | |
9f1fe2bb JN |
214 | This will create a library lib.a based on delay.o. For kbuild to |
215 | actually recognize that there is a lib.a being built, the directory | |
216 | shall be listed in libs-y. | |
cd238eff | 217 | |
9f1fe2bb | 218 | See also `List directories to visit when descending`_. |
39e6e9cf | 219 | |
2f0e2a39 | 220 | Use of lib-y is normally restricted to ``lib/`` and ``arch/*/lib``. |
1da177e4 | 221 | |
1a4c1c9d JN |
222 | Descending down in directories |
223 | ------------------------------ | |
1da177e4 | 224 | |
9f1fe2bb JN |
225 | A Makefile is only responsible for building objects in its own |
226 | directory. Files in subdirectories should be taken care of by | |
227 | Makefiles in these subdirs. The build system will automatically | |
228 | invoke make recursively in subdirectories, provided you let it know of | |
229 | them. | |
1da177e4 | 230 | |
9f1fe2bb JN |
231 | To do so, obj-y and obj-m are used. |
232 | ext2 lives in a separate directory, and the Makefile present in fs/ | |
233 | tells kbuild to descend down using the following assignment. | |
1da177e4 | 234 | |
9f1fe2bb | 235 | Example:: |
cd238eff | 236 | |
9f1fe2bb JN |
237 | #fs/Makefile |
238 | obj-$(CONFIG_EXT2_FS) += ext2/ | |
1da177e4 | 239 | |
2f0e2a39 | 240 | If CONFIG_EXT2_FS is set to either "y" (built-in) or "m" (modular) |
9f1fe2bb JN |
241 | the corresponding obj- variable will be set, and kbuild will descend |
242 | down in the ext2 directory. | |
28f94a44 | 243 | |
9f1fe2bb JN |
244 | Kbuild uses this information not only to decide that it needs to visit |
245 | the directory, but also to decide whether or not to link objects from | |
246 | the directory into vmlinux. | |
28f94a44 | 247 | |
2f0e2a39 | 248 | When Kbuild descends into the directory with "y", all built-in objects |
9f1fe2bb JN |
249 | from that directory are combined into the built-in.a, which will be |
250 | eventually linked into vmlinux. | |
28f94a44 | 251 | |
2f0e2a39 | 252 | When Kbuild descends into the directory with "m", in contrast, nothing |
9f1fe2bb JN |
253 | from that directory will be linked into vmlinux. If the Makefile in |
254 | that directory specifies obj-y, those objects will be left orphan. | |
255 | It is very likely a bug of the Makefile or of dependencies in Kconfig. | |
1da177e4 | 256 | |
9f1fe2bb JN |
257 | Kbuild also supports dedicated syntax, subdir-y and subdir-m, for |
258 | descending into subdirectories. It is a good fit when you know they | |
259 | do not contain kernel-space objects at all. A typical usage is to let | |
260 | Kbuild descend into subdirectories to build tools. | |
c0ea806f | 261 | |
9f1fe2bb | 262 | Examples:: |
c0ea806f | 263 | |
9f1fe2bb JN |
264 | # scripts/Makefile |
265 | subdir-$(CONFIG_GCC_PLUGINS) += gcc-plugins | |
266 | subdir-$(CONFIG_MODVERSIONS) += genksyms | |
267 | subdir-$(CONFIG_SECURITY_SELINUX) += selinux | |
c0ea806f | 268 | |
9f1fe2bb JN |
269 | Unlike obj-y/m, subdir-y/m does not need the trailing slash since this |
270 | syntax is always used for directories. | |
c0ea806f | 271 | |
2f0e2a39 | 272 | It is good practice to use a ``CONFIG_`` variable when assigning directory |
9f1fe2bb | 273 | names. This allows kbuild to totally skip the directory if the |
2f0e2a39 | 274 | corresponding ``CONFIG_`` option is neither "y" nor "m". |
1da177e4 | 275 | |
1a4c1c9d JN |
276 | Non-builtin vmlinux targets - extra-y |
277 | ------------------------------------- | |
d0e628cd | 278 | |
9f1fe2bb JN |
279 | extra-y specifies targets which are needed for building vmlinux, |
280 | but not combined into built-in.a. | |
d0e628cd | 281 | |
9f1fe2bb | 282 | Examples are: |
d0e628cd | 283 | |
9f1fe2bb | 284 | 1) vmlinux linker script |
d0e628cd | 285 | |
9f1fe2bb JN |
286 | The linker script for vmlinux is located at |
287 | arch/$(SRCARCH)/kernel/vmlinux.lds | |
d0e628cd | 288 | |
9f1fe2bb | 289 | Example:: |
d0e628cd | 290 | |
9f1fe2bb JN |
291 | # arch/x86/kernel/Makefile |
292 | extra-y += vmlinux.lds | |
d0e628cd | 293 | |
9f1fe2bb | 294 | $(extra-y) should only contain targets needed for vmlinux. |
d0e628cd | 295 | |
9f1fe2bb | 296 | Kbuild skips extra-y when vmlinux is apparently not a final goal. |
2f0e2a39 | 297 | (e.g. ``make modules``, or building external modules) |
d0e628cd | 298 | |
9f1fe2bb JN |
299 | If you intend to build targets unconditionally, always-y (explained |
300 | in the next section) is the correct syntax to use. | |
d0e628cd | 301 | |
1a4c1c9d JN |
302 | Always built goals - always-y |
303 | ----------------------------- | |
d0e628cd | 304 | |
9f1fe2bb JN |
305 | always-y specifies targets which are literally always built when |
306 | Kbuild visits the Makefile. | |
307 | ||
308 | Example:: | |
d0e628cd | 309 | |
9f1fe2bb JN |
310 | # ./Kbuild |
311 | offsets-file := include/generated/asm-offsets.h | |
312 | always-y += $(offsets-file) | |
d0e628cd | 313 | |
1a4c1c9d JN |
314 | Compilation flags |
315 | ----------------- | |
1da177e4 | 316 | |
9f1fe2bb JN |
317 | ccflags-y, asflags-y and ldflags-y |
318 | These three flags apply only to the kbuild makefile in which they | |
319 | are assigned. They are used for all the normal cc, as and ld | |
320 | invocations happening during a recursive build. | |
321 | Note: Flags with the same behaviour were previously named: | |
322 | EXTRA_CFLAGS, EXTRA_AFLAGS and EXTRA_LDFLAGS. | |
323 | They are still supported but their usage is deprecated. | |
1da177e4 | 324 | |
9f1fe2bb | 325 | ccflags-y specifies options for compiling with $(CC). |
1da177e4 | 326 | |
9f1fe2bb | 327 | Example:: |
cd238eff | 328 | |
9f1fe2bb JN |
329 | # drivers/acpi/acpica/Makefile |
330 | ccflags-y := -Os -D_LINUX -DBUILDING_ACPICA | |
331 | ccflags-$(CONFIG_ACPI_DEBUG) += -DACPI_DEBUG_OUTPUT | |
1da177e4 | 332 | |
9f1fe2bb JN |
333 | This variable is necessary because the top Makefile owns the |
334 | variable $(KBUILD_CFLAGS) and uses it for compilation flags for the | |
335 | entire tree. | |
1da177e4 | 336 | |
9f1fe2bb | 337 | asflags-y specifies assembler options. |
1da177e4 | 338 | |
9f1fe2bb | 339 | Example:: |
cd238eff | 340 | |
9f1fe2bb JN |
341 | #arch/sparc/kernel/Makefile |
342 | asflags-y := -ansi | |
1da177e4 | 343 | |
9f1fe2bb | 344 | ldflags-y specifies options for linking with $(LD). |
1da177e4 | 345 | |
9f1fe2bb | 346 | Example:: |
cd238eff | 347 | |
9f1fe2bb | 348 | #arch/cris/boot/compressed/Makefile |
b1992c37 | 349 | ldflags-y += -T $(src)/decompress_$(arch-y).lds |
1da177e4 | 350 | |
9f1fe2bb JN |
351 | subdir-ccflags-y, subdir-asflags-y |
352 | The two flags listed above are similar to ccflags-y and asflags-y. | |
353 | The difference is that the subdir- variants have effect for the kbuild | |
354 | file where they are present and all subdirectories. | |
355 | Options specified using subdir-* are added to the commandline before | |
356 | the options specified using the non-subdir variants. | |
720097d8 | 357 | |
9f1fe2bb | 358 | Example:: |
cd238eff | 359 | |
9f1fe2bb | 360 | subdir-ccflags-y := -Werror |
720097d8 | 361 | |
9f1fe2bb JN |
362 | ccflags-remove-y, asflags-remove-y |
363 | These flags are used to remove particular flags for the compiler, | |
364 | assembler invocations. | |
15d5761a | 365 | |
9f1fe2bb | 366 | Example:: |
15d5761a | 367 | |
9f1fe2bb | 368 | ccflags-remove-$(CONFIG_MCOUNT) += -pg |
15d5761a | 369 | |
9f1fe2bb JN |
370 | CFLAGS_$@, AFLAGS_$@ |
371 | CFLAGS_$@ and AFLAGS_$@ only apply to commands in current | |
372 | kbuild makefile. | |
1da177e4 | 373 | |
9f1fe2bb JN |
374 | $(CFLAGS_$@) specifies per-file options for $(CC). The $@ |
375 | part has a literal value which specifies the file that it is for. | |
1da177e4 | 376 | |
9f1fe2bb JN |
377 | CFLAGS_$@ has the higher priority than ccflags-remove-y; CFLAGS_$@ |
378 | can re-add compiler flags that were removed by ccflags-remove-y. | |
15d5761a | 379 | |
9f1fe2bb | 380 | Example:: |
cd238eff | 381 | |
9f1fe2bb JN |
382 | # drivers/scsi/Makefile |
383 | CFLAGS_aha152x.o = -DAHA152X_STAT -DAUTOCONF | |
1da177e4 | 384 | |
9f1fe2bb | 385 | This line specify compilation flags for aha152x.o. |
1da177e4 | 386 | |
9f1fe2bb JN |
387 | $(AFLAGS_$@) is a similar feature for source files in assembly |
388 | languages. | |
1da177e4 | 389 | |
9f1fe2bb JN |
390 | AFLAGS_$@ has the higher priority than asflags-remove-y; AFLAGS_$@ |
391 | can re-add assembler flags that were removed by asflags-remove-y. | |
15d5761a | 392 | |
9f1fe2bb | 393 | Example:: |
eb07e1b4 | 394 | |
9f1fe2bb JN |
395 | # arch/arm/kernel/Makefile |
396 | AFLAGS_head.o := -DTEXT_OFFSET=$(TEXT_OFFSET) | |
397 | AFLAGS_crunch-bits.o := -Wa,-mcpu=ep9312 | |
398 | AFLAGS_iwmmxt.o := -Wa,-mcpu=iwmmxt | |
1da177e4 | 399 | |
1a4c1c9d JN |
400 | Dependency tracking |
401 | ------------------- | |
1da177e4 | 402 | |
9f1fe2bb | 403 | Kbuild tracks dependencies on the following: |
16886949 | 404 | |
2f0e2a39 JN |
405 | 1) All prerequisite files (both ``*.c`` and ``*.h``) |
406 | 2) ``CONFIG_`` options used in all prerequisite files | |
9f1fe2bb | 407 | 3) Command-line used to compile target |
1da177e4 | 408 | |
9f1fe2bb JN |
409 | Thus, if you change an option to $(CC) all affected files will |
410 | be re-compiled. | |
1da177e4 | 411 | |
1a4c1c9d JN |
412 | Custom Rules |
413 | ------------ | |
1da177e4 | 414 | |
9f1fe2bb JN |
415 | Custom rules are used when the kbuild infrastructure does |
416 | not provide the required support. A typical example is | |
417 | header files generated during the build process. | |
418 | Another example are the architecture-specific Makefiles which | |
419 | need custom rules to prepare boot images etc. | |
1da177e4 | 420 | |
9f1fe2bb JN |
421 | Custom rules are written as normal Make rules. |
422 | Kbuild is not executing in the directory where the Makefile is | |
423 | located, so all custom rules shall use a relative | |
424 | path to prerequisite files and target files. | |
1da177e4 | 425 | |
9f1fe2bb | 426 | Two variables are used when defining custom rules: |
1da177e4 | 427 | |
9f1fe2bb | 428 | $(src) |
b1992c37 | 429 | $(src) is the directory where the Makefile is located. Always use $(src) when |
9f1fe2bb | 430 | referring to files located in the src tree. |
cd238eff | 431 | |
9f1fe2bb | 432 | $(obj) |
b1992c37 MY |
433 | $(obj) is the directory where the target is saved. Always use $(obj) when |
434 | referring to generated files. Use $(obj) for pattern rules that need to work | |
435 | for both generated files and real sources (VPATH will help to find the | |
436 | prerequisites not only in the object tree but also in the source tree). | |
1da177e4 | 437 | |
9f1fe2bb | 438 | Example:: |
1da177e4 | 439 | |
9f1fe2bb JN |
440 | #drivers/scsi/Makefile |
441 | $(obj)/53c8xx_d.h: $(src)/53c7,8xx.scr $(src)/script_asm.pl | |
442 | $(CPP) -DCHIP=810 - < $< | ... $(src)/script_asm.pl | |
1da177e4 | 443 | |
9f1fe2bb JN |
444 | This is a custom rule, following the normal syntax |
445 | required by make. | |
cd238eff | 446 | |
9f1fe2bb JN |
447 | The target file depends on two prerequisite files. References |
448 | to the target file are prefixed with $(obj), references | |
449 | to prerequisites are referenced with $(src) (because they are not | |
450 | generated files). | |
cd238eff | 451 | |
9f1fe2bb JN |
452 | $(kecho) |
453 | echoing information to user in a rule is often a good practice | |
2f0e2a39 | 454 | but when execution ``make -s`` one does not expect to see any output |
9f1fe2bb JN |
455 | except for warnings/errors. |
456 | To support this kbuild defines $(kecho) which will echo out the | |
2f0e2a39 | 457 | text following $(kecho) to stdout except if ``make -s`` is used. |
cd238eff | 458 | |
9f1fe2bb | 459 | Example:: |
cd238eff | 460 | |
9f1fe2bb JN |
461 | # arch/arm/Makefile |
462 | $(BOOT_TARGETS): vmlinux | |
463 | $(Q)$(MAKE) $(build)=$(boot) MACHINE=$(MACHINE) $(boot)/$@ | |
464 | @$(kecho) ' Kernel: $(boot)/$@ is ready' | |
5410ecc0 | 465 | |
9f1fe2bb JN |
466 | When kbuild is executing with KBUILD_VERBOSE unset, then only a shorthand |
467 | of a command is normally displayed. | |
468 | To enable this behaviour for custom commands kbuild requires | |
469 | two variables to be set:: | |
41cac083 | 470 | |
9f1fe2bb JN |
471 | quiet_cmd_<command> - what shall be echoed |
472 | cmd_<command> - the command to execute | |
41cac083 | 473 | |
9f1fe2bb | 474 | Example:: |
41cac083 | 475 | |
9f1fe2bb JN |
476 | # lib/Makefile |
477 | quiet_cmd_crc32 = GEN $@ | |
478 | cmd_crc32 = $< > $@ | |
41cac083 | 479 | |
9f1fe2bb JN |
480 | $(obj)/crc32table.h: $(obj)/gen_crc32table |
481 | $(call cmd,crc32) | |
41cac083 | 482 | |
9f1fe2bb | 483 | When updating the $(obj)/crc32table.h target, the line:: |
41cac083 | 484 | |
9f1fe2bb | 485 | GEN lib/crc32table.h |
41cac083 | 486 | |
2f0e2a39 | 487 | will be displayed with ``make KBUILD_VERBOSE=``. |
5410ecc0 | 488 | |
1a4c1c9d JN |
489 | Command change detection |
490 | ------------------------ | |
39bb232a | 491 | |
9f1fe2bb JN |
492 | When the rule is evaluated, timestamps are compared between the target |
493 | and its prerequisite files. GNU Make updates the target when any of the | |
494 | prerequisites is newer than that. | |
39bb232a | 495 | |
9f1fe2bb JN |
496 | The target should be rebuilt also when the command line has changed |
497 | since the last invocation. This is not supported by Make itself, so | |
498 | Kbuild achieves this by a kind of meta-programming. | |
39bb232a | 499 | |
9f1fe2bb | 500 | if_changed is the macro used for this purpose, in the following form:: |
39bb232a | 501 | |
9f1fe2bb JN |
502 | quiet_cmd_<command> = ... |
503 | cmd_<command> = ... | |
39bb232a | 504 | |
9f1fe2bb JN |
505 | <target>: <source(s)> FORCE |
506 | $(call if_changed,<command>) | |
39bb232a | 507 | |
9f1fe2bb JN |
508 | Any target that utilizes if_changed must be listed in $(targets), |
509 | otherwise the command line check will fail, and the target will | |
510 | always be built. | |
39bb232a | 511 | |
9f1fe2bb JN |
512 | If the target is already listed in the recognized syntax such as |
513 | obj-y/m, lib-y/m, extra-y/m, always-y/m, hostprogs, userprogs, Kbuild | |
514 | automatically adds it to $(targets). Otherwise, the target must be | |
515 | explicitly added to $(targets). | |
39bb232a | 516 | |
9f1fe2bb JN |
517 | Assignments to $(targets) are without $(obj)/ prefix. if_changed may be |
518 | used in conjunction with custom rules as defined in `Custom Rules`_. | |
39bb232a | 519 | |
9f1fe2bb JN |
520 | Note: It is a typical mistake to forget the FORCE prerequisite. |
521 | Another common pitfall is that whitespace is sometimes significant; for | |
522 | instance, the below will fail (note the extra space after the comma):: | |
39bb232a | 523 | |
9f1fe2bb | 524 | target: source(s) FORCE |
39bb232a | 525 | |
9f1fe2bb | 526 | **WRONG!** $(call if_changed, objcopy) |
39bb232a | 527 | |
9f1fe2bb JN |
528 | Note: |
529 | if_changed should not be used more than once per target. | |
530 | It stores the executed command in a corresponding .cmd | |
531 | file and multiple calls would result in overwrites and | |
532 | unwanted results when the target is up to date and only the | |
533 | tests on changed commands trigger execution of commands. | |
39bb232a | 534 | |
1a4c1c9d JN |
535 | $(CC) support functions |
536 | ----------------------- | |
20a468b5 | 537 | |
9f1fe2bb JN |
538 | The kernel may be built with several different versions of |
539 | $(CC), each supporting a unique set of features and options. | |
540 | kbuild provides basic support to check for valid options for $(CC). | |
541 | $(CC) is usually the gcc compiler, but other alternatives are | |
542 | available. | |
543 | ||
544 | as-option | |
545 | as-option is used to check if $(CC) -- when used to compile | |
2f0e2a39 | 546 | assembler (``*.S``) files -- supports the given option. An optional |
9f1fe2bb JN |
547 | second option may be specified if the first option is not supported. |
548 | ||
549 | Example:: | |
550 | ||
551 | #arch/sh/Makefile | |
552 | cflags-y += $(call as-option,-Wa$(comma)-isa=$(isa-y),) | |
20a468b5 | 553 | |
9f1fe2bb JN |
554 | In the above example, cflags-y will be assigned the option |
555 | -Wa$(comma)-isa=$(isa-y) if it is supported by $(CC). | |
556 | The second argument is optional, and if supplied will be used | |
557 | if first argument is not supported. | |
20a468b5 | 558 | |
9f1fe2bb JN |
559 | as-instr |
560 | as-instr checks if the assembler reports a specific instruction | |
561 | and then outputs either option1 or option2 | |
562 | C escapes are supported in the test instruction | |
563 | Note: as-instr-option uses KBUILD_AFLAGS for assembler options | |
cd238eff | 564 | |
9f1fe2bb JN |
565 | cc-option |
566 | cc-option is used to check if $(CC) supports a given option, and if | |
567 | not supported to use an optional second option. | |
20a468b5 | 568 | |
9f1fe2bb | 569 | Example:: |
cd238eff | 570 | |
9f1fe2bb JN |
571 | #arch/x86/Makefile |
572 | cflags-y += $(call cc-option,-march=pentium-mmx,-march=i586) | |
e2414910 | 573 | |
9f1fe2bb JN |
574 | In the above example, cflags-y will be assigned the option |
575 | -march=pentium-mmx if supported by $(CC), otherwise -march=i586. | |
576 | The second argument to cc-option is optional, and if omitted, | |
577 | cflags-y will be assigned no value if first option is not supported. | |
578 | Note: cc-option uses KBUILD_CFLAGS for $(CC) options | |
20a468b5 | 579 | |
9f1fe2bb JN |
580 | cc-option-yn |
581 | cc-option-yn is used to check if gcc supports a given option | |
2f0e2a39 | 582 | and return "y" if supported, otherwise "n". |
cd238eff | 583 | |
9f1fe2bb | 584 | Example:: |
20a468b5 | 585 | |
9f1fe2bb JN |
586 | #arch/ppc/Makefile |
587 | biarch := $(call cc-option-yn, -m32) | |
588 | aflags-$(biarch) += -a32 | |
589 | cflags-$(biarch) += -m32 | |
20a468b5 | 590 | |
9f1fe2bb | 591 | In the above example, $(biarch) is set to y if $(CC) supports the -m32 |
2f0e2a39 | 592 | option. When $(biarch) equals "y", the expanded variables $(aflags-y) |
9f1fe2bb JN |
593 | and $(cflags-y) will be assigned the values -a32 and -m32, |
594 | respectively. | |
20a468b5 | 595 | |
9f1fe2bb | 596 | Note: cc-option-yn uses KBUILD_CFLAGS for $(CC) options |
cd238eff | 597 | |
9f1fe2bb JN |
598 | cc-disable-warning |
599 | cc-disable-warning checks if gcc supports a given warning and returns | |
600 | the commandline switch to disable it. This special function is needed, | |
601 | because gcc 4.4 and later accept any unknown -Wno-* option and only | |
602 | warn about it if there is another warning in the source file. | |
39e6e9cf | 603 | |
9f1fe2bb | 604 | Example:: |
20a468b5 | 605 | |
9f1fe2bb | 606 | KBUILD_CFLAGS += $(call cc-disable-warning, unused-but-set-variable) |
8417da6f | 607 | |
9f1fe2bb JN |
608 | In the above example, -Wno-unused-but-set-variable will be added to |
609 | KBUILD_CFLAGS only if gcc really accepts it. | |
cd238eff | 610 | |
9f1fe2bb JN |
611 | gcc-min-version |
612 | gcc-min-version tests if the value of $(CONFIG_GCC_VERSION) is greater than | |
613 | or equal to the provided value and evaluates to y if so. | |
8417da6f | 614 | |
9f1fe2bb | 615 | Example:: |
8417da6f | 616 | |
9f1fe2bb | 617 | cflags-$(call gcc-min-version, 70100) := -foo |
20a468b5 | 618 | |
9f1fe2bb JN |
619 | In this example, cflags-y will be assigned the value -foo if $(CC) is gcc and |
620 | $(CONFIG_GCC_VERSION) is >= 7.1. | |
cd238eff | 621 | |
9f1fe2bb JN |
622 | clang-min-version |
623 | clang-min-version tests if the value of $(CONFIG_CLANG_VERSION) is greater | |
624 | than or equal to the provided value and evaluates to y if so. | |
20a468b5 | 625 | |
9f1fe2bb | 626 | Example:: |
88b61e3b | 627 | |
9f1fe2bb | 628 | cflags-$(call clang-min-version, 110000) := -foo |
20a468b5 | 629 | |
9f1fe2bb JN |
630 | In this example, cflags-y will be assigned the value -foo if $(CC) is clang |
631 | and $(CONFIG_CLANG_VERSION) is >= 11.0.0. | |
cd238eff | 632 | |
9f1fe2bb JN |
633 | cc-cross-prefix |
634 | cc-cross-prefix is used to check if there exists a $(CC) in path with | |
635 | one of the listed prefixes. The first prefix where there exist a | |
636 | prefix$(CC) in the PATH is returned - and if no prefix$(CC) is found | |
637 | then nothing is returned. | |
20a468b5 | 638 | |
9f1fe2bb JN |
639 | Additional prefixes are separated by a single space in the |
640 | call of cc-cross-prefix. | |
20a468b5 | 641 | |
9f1fe2bb JN |
642 | This functionality is useful for architecture Makefiles that try |
643 | to set CROSS_COMPILE to well-known values but may have several | |
644 | values to select between. | |
910b4046 | 645 | |
9f1fe2bb JN |
646 | It is recommended only to try to set CROSS_COMPILE if it is a cross |
647 | build (host arch is different from target arch). And if CROSS_COMPILE | |
648 | is already set then leave it with the old value. | |
cd238eff | 649 | |
9f1fe2bb JN |
650 | Example:: |
651 | ||
652 | #arch/m68k/Makefile | |
653 | ifneq ($(SUBARCH),$(ARCH)) | |
654 | ifeq ($(CROSS_COMPILE),) | |
655 | CROSS_COMPILE := $(call cc-cross-prefix, m68k-linux-gnu-) | |
656 | endif | |
657 | endif | |
910b4046 | 658 | |
1a4c1c9d JN |
659 | $(LD) support functions |
660 | ----------------------- | |
691ef3e7 | 661 | |
9f1fe2bb JN |
662 | ld-option |
663 | ld-option is used to check if $(LD) supports the supplied option. | |
664 | ld-option takes two options as arguments. | |
665 | ||
666 | The second argument is an optional option that can be used if the | |
667 | first option is not supported by $(LD). | |
691ef3e7 | 668 | |
9f1fe2bb | 669 | Example:: |
cd238eff | 670 | |
9f1fe2bb JN |
671 | #Makefile |
672 | LDFLAGS_vmlinux += $(call ld-option, -X) | |
691ef3e7 | 673 | |
1a4c1c9d JN |
674 | Script invocation |
675 | ----------------- | |
eb38f37c | 676 | |
9f1fe2bb JN |
677 | Make rules may invoke scripts to build the kernel. The rules shall |
678 | always provide the appropriate interpreter to execute the script. They | |
679 | shall not rely on the execute bits being set, and shall not invoke the | |
680 | script directly. For the convenience of manual script invocation, such | |
681 | as invoking ./scripts/checkpatch.pl, it is recommended to set execute | |
682 | bits on the scripts nonetheless. | |
eb38f37c | 683 | |
9f1fe2bb JN |
684 | Kbuild provides variables $(CONFIG_SHELL), $(AWK), $(PERL), |
685 | and $(PYTHON3) to refer to interpreters for the respective | |
686 | scripts. | |
eb38f37c | 687 | |
9f1fe2bb | 688 | Example:: |
eb38f37c | 689 | |
9f1fe2bb JN |
690 | #Makefile |
691 | cmd_depmod = $(CONFIG_SHELL) $(srctree)/scripts/depmod.sh $(DEPMOD) \ | |
692 | $(KERNELRELEASE) | |
691ef3e7 | 693 | |
1a4c1c9d JN |
694 | Host Program support |
695 | ==================== | |
1da177e4 LT |
696 | |
697 | Kbuild supports building executables on the host for use during the | |
698 | compilation stage. | |
9f1fe2bb | 699 | |
1da177e4 LT |
700 | Two steps are required in order to use a host executable. |
701 | ||
702 | The first step is to tell kbuild that a host program exists. This is | |
2f0e2a39 | 703 | done utilising the variable ``hostprogs``. |
1da177e4 LT |
704 | |
705 | The second step is to add an explicit dependency to the executable. | |
39e6e9cf | 706 | This can be done in two ways. Either add the dependency in a rule, |
2f0e2a39 | 707 | or utilise the variable ``always-y``. |
1da177e4 LT |
708 | Both possibilities are described in the following. |
709 | ||
1a4c1c9d JN |
710 | Simple Host Program |
711 | ------------------- | |
1da177e4 | 712 | |
9f1fe2bb JN |
713 | In some cases there is a need to compile and run a program on the |
714 | computer where the build is running. | |
715 | ||
716 | The following line tells kbuild that the program bin2hex shall be | |
717 | built on the build host. | |
1da177e4 | 718 | |
9f1fe2bb | 719 | Example:: |
cd238eff | 720 | |
9f1fe2bb | 721 | hostprogs := bin2hex |
1da177e4 | 722 | |
9f1fe2bb JN |
723 | Kbuild assumes in the above example that bin2hex is made from a single |
724 | c-source file named bin2hex.c located in the same directory as | |
725 | the Makefile. | |
39e6e9cf | 726 | |
1a4c1c9d JN |
727 | Composite Host Programs |
728 | ----------------------- | |
1da177e4 | 729 | |
9f1fe2bb JN |
730 | Host programs can be made up based on composite objects. |
731 | The syntax used to define composite objects for host programs is | |
732 | similar to the syntax used for kernel objects. | |
733 | $(<executable>-objs) lists all objects used to link the final | |
734 | executable. | |
1da177e4 | 735 | |
9f1fe2bb | 736 | Example:: |
cd238eff | 737 | |
9f1fe2bb JN |
738 | #scripts/lxdialog/Makefile |
739 | hostprogs := lxdialog | |
740 | lxdialog-objs := checklist.o lxdialog.o | |
1da177e4 | 741 | |
9f1fe2bb JN |
742 | Objects with extension .o are compiled from the corresponding .c |
743 | files. In the above example, checklist.c is compiled to checklist.o | |
744 | and lxdialog.c is compiled to lxdialog.o. | |
cd238eff | 745 | |
9f1fe2bb JN |
746 | Finally, the two .o files are linked to the executable, lxdialog. |
747 | Note: The syntax <executable>-y is not permitted for host-programs. | |
1da177e4 | 748 | |
1a4c1c9d JN |
749 | Using C++ for host programs |
750 | --------------------------- | |
1da177e4 | 751 | |
9f1fe2bb JN |
752 | kbuild offers support for host programs written in C++. This was |
753 | introduced solely to support kconfig, and is not recommended | |
754 | for general use. | |
1da177e4 | 755 | |
9f1fe2bb | 756 | Example:: |
cd238eff | 757 | |
9f1fe2bb JN |
758 | #scripts/kconfig/Makefile |
759 | hostprogs := qconf | |
760 | qconf-cxxobjs := qconf.o | |
1da177e4 | 761 | |
9f1fe2bb JN |
762 | In the example above the executable is composed of the C++ file |
763 | qconf.cc - identified by $(qconf-cxxobjs). | |
39e6e9cf | 764 | |
9f1fe2bb JN |
765 | If qconf is composed of a mixture of .c and .cc files, then an |
766 | additional line can be used to identify this. | |
1da177e4 | 767 | |
9f1fe2bb | 768 | Example:: |
cd238eff | 769 | |
9f1fe2bb JN |
770 | #scripts/kconfig/Makefile |
771 | hostprogs := qconf | |
772 | qconf-cxxobjs := qconf.o | |
773 | qconf-objs := check.o | |
39e6e9cf | 774 | |
1a4c1c9d JN |
775 | Using Rust for host programs |
776 | ---------------------------- | |
d07479b2 | 777 | |
9f1fe2bb JN |
778 | Kbuild offers support for host programs written in Rust. However, |
779 | since a Rust toolchain is not mandatory for kernel compilation, | |
780 | it may only be used in scenarios where Rust is required to be | |
781 | available (e.g. when ``CONFIG_RUST`` is enabled). | |
d07479b2 | 782 | |
9f1fe2bb | 783 | Example:: |
d07479b2 | 784 | |
9f1fe2bb JN |
785 | hostprogs := target |
786 | target-rust := y | |
d07479b2 | 787 | |
9f1fe2bb JN |
788 | Kbuild will compile ``target`` using ``target.rs`` as the crate root, |
789 | located in the same directory as the ``Makefile``. The crate may | |
790 | consist of several source files (see ``samples/rust/hostprogs``). | |
d07479b2 | 791 | |
1a4c1c9d JN |
792 | Controlling compiler options for host programs |
793 | ---------------------------------------------- | |
1da177e4 | 794 | |
9f1fe2bb JN |
795 | When compiling host programs, it is possible to set specific flags. |
796 | The programs will always be compiled utilising $(HOSTCC) passed | |
797 | the options specified in $(KBUILD_HOSTCFLAGS). | |
1da177e4 | 798 | |
9f1fe2bb JN |
799 | To set flags that will take effect for all host programs created |
800 | in that Makefile, use the variable HOST_EXTRACFLAGS. | |
cd238eff | 801 | |
9f1fe2bb | 802 | Example:: |
39e6e9cf | 803 | |
9f1fe2bb JN |
804 | #scripts/lxdialog/Makefile |
805 | HOST_EXTRACFLAGS += -I/usr/include/ncurses | |
1da177e4 | 806 | |
9f1fe2bb JN |
807 | To set specific flags for a single file the following construction |
808 | is used: | |
cd238eff | 809 | |
9f1fe2bb | 810 | Example:: |
39e6e9cf | 811 | |
9f1fe2bb JN |
812 | #arch/ppc64/boot/Makefile |
813 | HOSTCFLAGS_piggyback.o := -DKERNELBASE=$(KERNELBASE) | |
39e6e9cf | 814 | |
9f1fe2bb | 815 | It is also possible to specify additional options to the linker. |
cd238eff | 816 | |
9f1fe2bb | 817 | Example:: |
1da177e4 | 818 | |
9f1fe2bb JN |
819 | #scripts/kconfig/Makefile |
820 | HOSTLDLIBS_qconf := -L$(QTDIR)/lib | |
821 | ||
822 | When linking qconf, it will be passed the extra option | |
2f0e2a39 | 823 | ``-L$(QTDIR)/lib``. |
39e6e9cf | 824 | |
1a4c1c9d JN |
825 | When host programs are actually built |
826 | ------------------------------------- | |
1da177e4 | 827 | |
9f1fe2bb JN |
828 | Kbuild will only build host-programs when they are referenced |
829 | as a prerequisite. | |
830 | ||
831 | This is possible in two ways: | |
1da177e4 | 832 | |
9f1fe2bb | 833 | (1) List the prerequisite explicitly in a custom rule. |
1da177e4 | 834 | |
9f1fe2bb | 835 | Example:: |
cd238eff | 836 | |
9f1fe2bb JN |
837 | #drivers/pci/Makefile |
838 | hostprogs := gen-devlist | |
839 | $(obj)/devlist.h: $(src)/pci.ids $(obj)/gen-devlist | |
840 | ( cd $(obj); ./gen-devlist ) < $< | |
1da177e4 | 841 | |
9f1fe2bb JN |
842 | The target $(obj)/devlist.h will not be built before |
843 | $(obj)/gen-devlist is updated. Note that references to | |
844 | the host programs in custom rules must be prefixed with $(obj). | |
1da177e4 | 845 | |
9f1fe2bb | 846 | (2) Use always-y |
cd238eff | 847 | |
9f1fe2bb JN |
848 | When there is no suitable custom rule, and the host program |
849 | shall be built when a makefile is entered, the always-y | |
850 | variable shall be used. | |
1da177e4 | 851 | |
9f1fe2bb | 852 | Example:: |
cd238eff | 853 | |
9f1fe2bb JN |
854 | #scripts/lxdialog/Makefile |
855 | hostprogs := lxdialog | |
856 | always-y := $(hostprogs) | |
1da177e4 | 857 | |
9f1fe2bb | 858 | Kbuild provides the following shorthand for this:: |
faabed29 | 859 | |
9f1fe2bb | 860 | hostprogs-always-y := lxdialog |
faabed29 | 861 | |
9f1fe2bb JN |
862 | This will tell kbuild to build lxdialog even if not referenced in |
863 | any rule. | |
1da177e4 | 864 | |
1a4c1c9d JN |
865 | Userspace Program support |
866 | ========================= | |
e079a08c MY |
867 | |
868 | Just like host programs, Kbuild also supports building userspace executables | |
869 | for the target architecture (i.e. the same architecture as you are building | |
870 | the kernel for). | |
871 | ||
2f0e2a39 JN |
872 | The syntax is quite similar. The difference is to use ``userprogs`` instead of |
873 | ``hostprogs``. | |
e079a08c | 874 | |
1a4c1c9d JN |
875 | Simple Userspace Program |
876 | ------------------------ | |
e079a08c | 877 | |
9f1fe2bb JN |
878 | The following line tells kbuild that the program bpf-direct shall be |
879 | built for the target architecture. | |
e079a08c | 880 | |
9f1fe2bb | 881 | Example:: |
e079a08c | 882 | |
9f1fe2bb | 883 | userprogs := bpf-direct |
e079a08c | 884 | |
9f1fe2bb JN |
885 | Kbuild assumes in the above example that bpf-direct is made from a |
886 | single C source file named bpf-direct.c located in the same directory | |
887 | as the Makefile. | |
e079a08c | 888 | |
1a4c1c9d JN |
889 | Composite Userspace Programs |
890 | ---------------------------- | |
e079a08c | 891 | |
9f1fe2bb JN |
892 | Userspace programs can be made up based on composite objects. |
893 | The syntax used to define composite objects for userspace programs is | |
894 | similar to the syntax used for kernel objects. | |
895 | $(<executable>-objs) lists all objects used to link the final | |
896 | executable. | |
e079a08c | 897 | |
9f1fe2bb | 898 | Example:: |
e079a08c | 899 | |
9f1fe2bb JN |
900 | #samples/seccomp/Makefile |
901 | userprogs := bpf-fancy | |
902 | bpf-fancy-objs := bpf-fancy.o bpf-helper.o | |
e079a08c | 903 | |
9f1fe2bb JN |
904 | Objects with extension .o are compiled from the corresponding .c |
905 | files. In the above example, bpf-fancy.c is compiled to bpf-fancy.o | |
906 | and bpf-helper.c is compiled to bpf-helper.o. | |
e079a08c | 907 | |
9f1fe2bb JN |
908 | Finally, the two .o files are linked to the executable, bpf-fancy. |
909 | Note: The syntax <executable>-y is not permitted for userspace programs. | |
e079a08c | 910 | |
1a4c1c9d JN |
911 | Controlling compiler options for userspace programs |
912 | --------------------------------------------------- | |
e079a08c | 913 | |
9f1fe2bb JN |
914 | When compiling userspace programs, it is possible to set specific flags. |
915 | The programs will always be compiled utilising $(CC) passed | |
916 | the options specified in $(KBUILD_USERCFLAGS). | |
917 | ||
918 | To set flags that will take effect for all userspace programs created | |
919 | in that Makefile, use the variable userccflags. | |
e079a08c | 920 | |
9f1fe2bb | 921 | Example:: |
e079a08c | 922 | |
9f1fe2bb JN |
923 | # samples/seccomp/Makefile |
924 | userccflags += -I usr/include | |
e079a08c | 925 | |
9f1fe2bb JN |
926 | To set specific flags for a single file the following construction |
927 | is used: | |
e079a08c | 928 | |
9f1fe2bb | 929 | Example:: |
e079a08c | 930 | |
9f1fe2bb | 931 | bpf-helper-userccflags += -I user/include |
e079a08c | 932 | |
9f1fe2bb | 933 | It is also possible to specify additional options to the linker. |
e079a08c | 934 | |
9f1fe2bb | 935 | Example:: |
e079a08c | 936 | |
9f1fe2bb JN |
937 | # net/bpfilter/Makefile |
938 | bpfilter_umh-userldflags += -static | |
e079a08c | 939 | |
5f56cb03 MY |
940 | To specify libraries linked to a userspace program, you can use |
941 | ``<executable>-userldlibs``. The ``userldlibs`` syntax specifies libraries | |
942 | linked to all userspace programs created in the current Makefile. | |
943 | ||
9f1fe2bb | 944 | When linking bpfilter_umh, it will be passed the extra option -static. |
e079a08c | 945 | |
9f1fe2bb | 946 | From command line, :ref:`USERCFLAGS and USERLDFLAGS <userkbuildflags>` will also be used. |
f67695c9 | 947 | |
1a4c1c9d JN |
948 | When userspace programs are actually built |
949 | ------------------------------------------ | |
e079a08c | 950 | |
9f1fe2bb JN |
951 | Kbuild builds userspace programs only when told to do so. |
952 | There are two ways to do this. | |
faabed29 | 953 | |
9f1fe2bb | 954 | (1) Add it as the prerequisite of another file |
faabed29 | 955 | |
9f1fe2bb | 956 | Example:: |
faabed29 | 957 | |
9f1fe2bb JN |
958 | #net/bpfilter/Makefile |
959 | userprogs := bpfilter_umh | |
960 | $(obj)/bpfilter_umh_blob.o: $(obj)/bpfilter_umh | |
faabed29 | 961 | |
9f1fe2bb | 962 | $(obj)/bpfilter_umh is built before $(obj)/bpfilter_umh_blob.o |
faabed29 | 963 | |
9f1fe2bb | 964 | (2) Use always-y |
faabed29 | 965 | |
9f1fe2bb | 966 | Example:: |
faabed29 | 967 | |
9f1fe2bb JN |
968 | userprogs := binderfs_example |
969 | always-y := $(userprogs) | |
faabed29 | 970 | |
9f1fe2bb | 971 | Kbuild provides the following shorthand for this:: |
faabed29 | 972 | |
9f1fe2bb | 973 | userprogs-always-y := binderfs_example |
faabed29 | 974 | |
9f1fe2bb JN |
975 | This will tell Kbuild to build binderfs_example when it visits this |
976 | Makefile. | |
e079a08c | 977 | |
1a4c1c9d JN |
978 | Kbuild clean infrastructure |
979 | =========================== | |
1da177e4 | 980 | |
2f0e2a39 | 981 | ``make clean`` deletes most generated files in the obj tree where the kernel |
1da177e4 | 982 | is compiled. This includes generated files such as host programs. |
5f2fb52f MY |
983 | Kbuild knows targets listed in $(hostprogs), $(always-y), $(always-m), |
984 | $(always-), $(extra-y), $(extra-) and $(targets). They are all deleted | |
2f0e2a39 | 985 | during ``make clean``. Files matching the patterns ``*.[oas]``, ``*.ko``, plus |
5f2fb52f | 986 | some additional files generated by kbuild are deleted all over the kernel |
2f0e2a39 | 987 | source tree when ``make clean`` is executed. |
1da177e4 | 988 | |
1634f2bf MY |
989 | Additional files or directories can be specified in kbuild makefiles by use of |
990 | $(clean-files). | |
1da177e4 | 991 | |
9f1fe2bb | 992 | Example:: |
cd238eff | 993 | |
9f1fe2bb JN |
994 | #lib/Makefile |
995 | clean-files := crc32table.h | |
1da177e4 | 996 | |
2f0e2a39 | 997 | When executing ``make clean``, the file ``crc32table.h`` will be deleted. |
bd55daf4 | 998 | Kbuild will assume files to be in the same relative directory as the |
e3c9405e | 999 | Makefile. |
1da177e4 | 1000 | |
1634f2bf MY |
1001 | To exclude certain files or directories from make clean, use the |
1002 | $(no-clean-files) variable. | |
ef8ff89b | 1003 | |
2f0e2a39 | 1004 | Usually kbuild descends down in subdirectories due to ``obj-* := dir/``, |
1da177e4 LT |
1005 | but in the architecture makefiles where the kbuild infrastructure |
1006 | is not sufficient this sometimes needs to be explicit. | |
1007 | ||
9f1fe2bb | 1008 | Example:: |
cd238eff | 1009 | |
9f1fe2bb JN |
1010 | #arch/x86/boot/Makefile |
1011 | subdir- := compressed | |
1da177e4 LT |
1012 | |
1013 | The above assignment instructs kbuild to descend down in the | |
2f0e2a39 | 1014 | directory compressed/ when ``make clean`` is executed. |
1da177e4 | 1015 | |
2f0e2a39 | 1016 | Note 1: arch/$(SRCARCH)/Makefile cannot use ``subdir-``, because that file is |
8212f898 | 1017 | included in the top level makefile. Instead, arch/$(SRCARCH)/Kbuild can use |
2f0e2a39 | 1018 | ``subdir-``. |
1da177e4 LT |
1019 | |
1020 | Note 2: All directories listed in core-y, libs-y, drivers-y and net-y will | |
2f0e2a39 | 1021 | be visited during ``make clean``. |
1da177e4 | 1022 | |
1a4c1c9d JN |
1023 | Architecture Makefiles |
1024 | ====================== | |
1da177e4 LT |
1025 | |
1026 | The top level Makefile sets up the environment and does the preparation, | |
1027 | before starting to descend down in the individual directories. | |
9f1fe2bb | 1028 | |
a07f6033 | 1029 | The top level makefile contains the generic part, whereas |
8c4d9b14 | 1030 | arch/$(SRCARCH)/Makefile contains what is required to set up kbuild |
a07f6033 | 1031 | for said architecture. |
9f1fe2bb | 1032 | |
8c4d9b14 | 1033 | To do so, arch/$(SRCARCH)/Makefile sets up a number of variables and defines |
1da177e4 LT |
1034 | a few targets. |
1035 | ||
a07f6033 | 1036 | When kbuild executes, the following steps are followed (roughly): |
cd238eff | 1037 | |
a07f6033 | 1038 | 1) Configuration of the kernel => produce .config |
9f1fe2bb | 1039 | |
1da177e4 | 1040 | 2) Store kernel version in include/linux/version.h |
9f1fe2bb | 1041 | |
b22ae40e | 1042 | 3) Updating all other prerequisites to the target prepare: |
9f1fe2bb | 1043 | |
8c4d9b14 | 1044 | - Additional prerequisites are specified in arch/$(SRCARCH)/Makefile |
9f1fe2bb | 1045 | |
b22ae40e | 1046 | 4) Recursively descend down in all directories listed in |
1da177e4 | 1047 | init-* core* drivers-* net-* libs-* and build all targets. |
9f1fe2bb | 1048 | |
8c4d9b14 | 1049 | - The values of the above variables are expanded in arch/$(SRCARCH)/Makefile. |
9f1fe2bb | 1050 | |
b22ae40e | 1051 | 5) All object files are then linked and the resulting file vmlinux is |
a07f6033 | 1052 | located at the root of the obj tree. |
ce697cce | 1053 | The very first objects linked are listed in scripts/head-object-list.txt. |
9f1fe2bb | 1054 | |
b22ae40e | 1055 | 6) Finally, the architecture-specific part does any required post processing |
1da177e4 | 1056 | and builds the final bootimage. |
9f1fe2bb | 1057 | |
1da177e4 | 1058 | - This includes building boot records |
5c811e59 | 1059 | - Preparing initrd images and the like |
1da177e4 | 1060 | |
1a4c1c9d JN |
1061 | Set variables to tweak the build to the architecture |
1062 | ---------------------------------------------------- | |
1da177e4 | 1063 | |
9f1fe2bb JN |
1064 | KBUILD_LDFLAGS |
1065 | Generic $(LD) options | |
1da177e4 | 1066 | |
9f1fe2bb JN |
1067 | Flags used for all invocations of the linker. |
1068 | Often specifying the emulation is sufficient. | |
1da177e4 | 1069 | |
9f1fe2bb | 1070 | Example:: |
cd238eff | 1071 | |
9f1fe2bb JN |
1072 | #arch/s390/Makefile |
1073 | KBUILD_LDFLAGS := -m elf_s390 | |
cd238eff | 1074 | |
9f1fe2bb JN |
1075 | Note: ldflags-y can be used to further customise |
1076 | the flags used. See `Non-builtin vmlinux targets - extra-y`_. | |
39e6e9cf | 1077 | |
9f1fe2bb JN |
1078 | LDFLAGS_vmlinux |
1079 | Options for $(LD) when linking vmlinux | |
1da177e4 | 1080 | |
9f1fe2bb JN |
1081 | LDFLAGS_vmlinux is used to specify additional flags to pass to |
1082 | the linker when linking the final vmlinux image. | |
1da177e4 | 1083 | |
9f1fe2bb | 1084 | LDFLAGS_vmlinux uses the LDFLAGS_$@ support. |
cd238eff | 1085 | |
9f1fe2bb | 1086 | Example:: |
1da177e4 | 1087 | |
9f1fe2bb JN |
1088 | #arch/x86/Makefile |
1089 | LDFLAGS_vmlinux := -e stext | |
1da177e4 | 1090 | |
9f1fe2bb JN |
1091 | OBJCOPYFLAGS |
1092 | objcopy flags | |
1da177e4 | 1093 | |
9f1fe2bb JN |
1094 | When $(call if_changed,objcopy) is used to translate a .o file, |
1095 | the flags specified in OBJCOPYFLAGS will be used. | |
cd238eff | 1096 | |
9f1fe2bb JN |
1097 | $(call if_changed,objcopy) is often used to generate raw binaries on |
1098 | vmlinux. | |
1da177e4 | 1099 | |
9f1fe2bb | 1100 | Example:: |
1da177e4 | 1101 | |
9f1fe2bb JN |
1102 | #arch/s390/Makefile |
1103 | OBJCOPYFLAGS := -O binary | |
1da177e4 | 1104 | |
9f1fe2bb JN |
1105 | #arch/s390/boot/Makefile |
1106 | $(obj)/image: vmlinux FORCE | |
1107 | $(call if_changed,objcopy) | |
1da177e4 | 1108 | |
9f1fe2bb JN |
1109 | In this example, the binary $(obj)/image is a binary version of |
1110 | vmlinux. The usage of $(call if_changed,xxx) will be described later. | |
1da177e4 | 1111 | |
9f1fe2bb JN |
1112 | KBUILD_AFLAGS |
1113 | Assembler flags | |
cd238eff | 1114 | |
9f1fe2bb | 1115 | Default value - see top level Makefile. |
1da177e4 | 1116 | |
9f1fe2bb | 1117 | Append or modify as required per architecture. |
1da177e4 | 1118 | |
9f1fe2bb | 1119 | Example:: |
1da177e4 | 1120 | |
9f1fe2bb JN |
1121 | #arch/sparc64/Makefile |
1122 | KBUILD_AFLAGS += -m64 -mcpu=ultrasparc | |
1da177e4 | 1123 | |
9f1fe2bb JN |
1124 | KBUILD_CFLAGS |
1125 | $(CC) compiler flags | |
cd238eff | 1126 | |
9f1fe2bb | 1127 | Default value - see top level Makefile. |
1da177e4 | 1128 | |
9f1fe2bb | 1129 | Append or modify as required per architecture. |
1da177e4 | 1130 | |
9f1fe2bb | 1131 | Often, the KBUILD_CFLAGS variable depends on the configuration. |
1da177e4 | 1132 | |
9f1fe2bb JN |
1133 | Example:: |
1134 | ||
1135 | #arch/x86/boot/compressed/Makefile | |
1136 | cflags-$(CONFIG_X86_32) := -march=i386 | |
1137 | cflags-$(CONFIG_X86_64) := -mcmodel=small | |
1138 | KBUILD_CFLAGS += $(cflags-y) | |
1139 | ||
1140 | Many arch Makefiles dynamically run the target C compiler to | |
1141 | probe supported options:: | |
1142 | ||
1143 | #arch/x86/Makefile | |
1da177e4 | 1144 | |
9f1fe2bb JN |
1145 | ... |
1146 | cflags-$(CONFIG_MPENTIUMII) += $(call cc-option,\ | |
1147 | -march=pentium2,-march=i686) | |
1148 | ... | |
1149 | # Disable unit-at-a-time mode ... | |
1150 | KBUILD_CFLAGS += $(call cc-option,-fno-unit-at-a-time) | |
1151 | ... | |
1da177e4 | 1152 | |
1da177e4 | 1153 | |
9f1fe2bb | 1154 | The first example utilises the trick that a config option expands |
2f0e2a39 | 1155 | to "y" when selected. |
d07479b2 | 1156 | |
9f1fe2bb JN |
1157 | KBUILD_RUSTFLAGS |
1158 | $(RUSTC) compiler flags | |
d07479b2 | 1159 | |
9f1fe2bb | 1160 | Default value - see top level Makefile. |
d07479b2 | 1161 | |
9f1fe2bb | 1162 | Append or modify as required per architecture. |
d07479b2 | 1163 | |
9f1fe2bb | 1164 | Often, the KBUILD_RUSTFLAGS variable depends on the configuration. |
1da177e4 | 1165 | |
9f1fe2bb JN |
1166 | Note that target specification file generation (for ``--target``) |
1167 | is handled in ``scripts/generate_rust_target.rs``. | |
1da177e4 | 1168 | |
9f1fe2bb JN |
1169 | KBUILD_AFLAGS_KERNEL |
1170 | Assembler options specific for built-in | |
1da177e4 | 1171 | |
9f1fe2bb JN |
1172 | $(KBUILD_AFLAGS_KERNEL) contains extra C compiler flags used to compile |
1173 | resident kernel code. | |
cd238eff | 1174 | |
9f1fe2bb JN |
1175 | KBUILD_AFLAGS_MODULE |
1176 | Assembler options specific for modules | |
1da177e4 | 1177 | |
9f1fe2bb JN |
1178 | $(KBUILD_AFLAGS_MODULE) is used to add arch-specific options that |
1179 | are used for assembler. | |
80c00ba9 | 1180 | |
9f1fe2bb | 1181 | From commandline AFLAGS_MODULE shall be used (see kbuild.rst). |
80c00ba9 | 1182 | |
9f1fe2bb JN |
1183 | KBUILD_CFLAGS_KERNEL |
1184 | $(CC) options specific for built-in | |
6588169d | 1185 | |
9f1fe2bb JN |
1186 | $(KBUILD_CFLAGS_KERNEL) contains extra C compiler flags used to compile |
1187 | resident kernel code. | |
6588169d | 1188 | |
9f1fe2bb JN |
1189 | KBUILD_CFLAGS_MODULE |
1190 | Options for $(CC) when building modules | |
d07479b2 | 1191 | |
9f1fe2bb JN |
1192 | $(KBUILD_CFLAGS_MODULE) is used to add arch-specific options that |
1193 | are used for $(CC). | |
d07479b2 | 1194 | |
9f1fe2bb | 1195 | From commandline CFLAGS_MODULE shall be used (see kbuild.rst). |
d07479b2 | 1196 | |
9f1fe2bb JN |
1197 | KBUILD_RUSTFLAGS_KERNEL |
1198 | $(RUSTC) options specific for built-in | |
d07479b2 | 1199 | |
9f1fe2bb JN |
1200 | $(KBUILD_RUSTFLAGS_KERNEL) contains extra Rust compiler flags used to |
1201 | compile resident kernel code. | |
6588169d | 1202 | |
9f1fe2bb JN |
1203 | KBUILD_RUSTFLAGS_MODULE |
1204 | Options for $(RUSTC) when building modules | |
cd238eff | 1205 | |
9f1fe2bb JN |
1206 | $(KBUILD_RUSTFLAGS_MODULE) is used to add arch-specific options that |
1207 | are used for $(RUSTC). | |
39e6e9cf | 1208 | |
9f1fe2bb | 1209 | From commandline RUSTFLAGS_MODULE shall be used (see kbuild.rst). |
888f0c34 | 1210 | |
9f1fe2bb JN |
1211 | KBUILD_LDFLAGS_MODULE |
1212 | Options for $(LD) when linking modules | |
888f0c34 | 1213 | |
9f1fe2bb JN |
1214 | $(KBUILD_LDFLAGS_MODULE) is used to add arch-specific options |
1215 | used when linking modules. This is often a linker script. | |
10df0638 | 1216 | |
9f1fe2bb | 1217 | From commandline LDFLAGS_MODULE shall be used (see kbuild.rst). |
10df0638 | 1218 | |
9f1fe2bb JN |
1219 | KBUILD_LDS |
1220 | The linker script with full path. Assigned by the top-level Makefile. | |
888f0c34 | 1221 | |
9f1fe2bb JN |
1222 | KBUILD_VMLINUX_OBJS |
1223 | All object files for vmlinux. They are linked to vmlinux in the same | |
1224 | order as listed in KBUILD_VMLINUX_OBJS. | |
ce697cce | 1225 | |
9f1fe2bb JN |
1226 | The objects listed in scripts/head-object-list.txt are exceptions; |
1227 | they are placed before the other objects. | |
888f0c34 | 1228 | |
9f1fe2bb | 1229 | KBUILD_VMLINUX_LIBS |
2f0e2a39 | 1230 | All .a ``lib`` files for vmlinux. KBUILD_VMLINUX_OBJS and |
9f1fe2bb JN |
1231 | KBUILD_VMLINUX_LIBS together specify all the object files used to |
1232 | link vmlinux. | |
61754c18 | 1233 | |
1a4c1c9d JN |
1234 | Add prerequisites to archheaders |
1235 | -------------------------------- | |
052ad274 | 1236 | |
9f1fe2bb | 1237 | The archheaders: rule is used to generate header files that |
2f0e2a39 | 1238 | may be installed into user space by ``make header_install``. |
052ad274 | 1239 | |
2f0e2a39 | 1240 | It is run before ``make archprepare`` when run on the |
9f1fe2bb | 1241 | architecture itself. |
052ad274 | 1242 | |
1a4c1c9d JN |
1243 | Add prerequisites to archprepare |
1244 | -------------------------------- | |
1da177e4 | 1245 | |
9f1fe2bb JN |
1246 | The archprepare: rule is used to list prerequisites that need to be |
1247 | built before starting to descend down in the subdirectories. | |
1da177e4 | 1248 | |
9f1fe2bb | 1249 | This is usually used for header files containing assembler constants. |
cd238eff | 1250 | |
9f1fe2bb | 1251 | Example:: |
1da177e4 | 1252 | |
9f1fe2bb JN |
1253 | #arch/arm/Makefile |
1254 | archprepare: maketools | |
1da177e4 | 1255 | |
9f1fe2bb JN |
1256 | In this example, the file target maketools will be processed |
1257 | before descending down in the subdirectories. | |
1258 | ||
1259 | See also chapter XXX-TODO that describes how kbuild supports | |
1260 | generating offset header files. | |
1da177e4 | 1261 | |
1a4c1c9d JN |
1262 | List directories to visit when descending |
1263 | ----------------------------------------- | |
1da177e4 | 1264 | |
9f1fe2bb JN |
1265 | An arch Makefile cooperates with the top Makefile to define variables |
1266 | which specify how to build the vmlinux file. Note that there is no | |
1267 | corresponding arch-specific section for modules; the module-building | |
1268 | machinery is all architecture-independent. | |
39e6e9cf | 1269 | |
9f1fe2bb JN |
1270 | core-y, libs-y, drivers-y |
1271 | $(libs-y) lists directories where a lib.a archive can be located. | |
cd238eff | 1272 | |
9f1fe2bb JN |
1273 | The rest list directories where a built-in.a object file can be |
1274 | located. | |
cd238eff | 1275 | |
9f1fe2bb | 1276 | Then the rest follows in this order: |
1da177e4 | 1277 | |
9f1fe2bb | 1278 | $(core-y), $(libs-y), $(drivers-y) |
1da177e4 | 1279 | |
9f1fe2bb JN |
1280 | The top level Makefile defines values for all generic directories, |
1281 | and arch/$(SRCARCH)/Makefile only adds architecture-specific | |
1282 | directories. | |
cd238eff | 1283 | |
9f1fe2bb | 1284 | Example:: |
cd238eff | 1285 | |
9f1fe2bb JN |
1286 | # arch/sparc/Makefile |
1287 | core-y += arch/sparc/ | |
1da177e4 | 1288 | |
9f1fe2bb JN |
1289 | libs-y += arch/sparc/prom/ |
1290 | libs-y += arch/sparc/lib/ | |
23b53061 | 1291 | |
9f1fe2bb | 1292 | drivers-$(CONFIG_PM) += arch/sparc/power/ |
1da177e4 | 1293 | |
1a4c1c9d JN |
1294 | Architecture-specific boot images |
1295 | --------------------------------- | |
1da177e4 | 1296 | |
9f1fe2bb JN |
1297 | An arch Makefile specifies goals that take the vmlinux file, compress |
1298 | it, wrap it in bootstrapping code, and copy the resulting files | |
1299 | somewhere. This includes various kinds of installation commands. | |
1300 | The actual goals are not standardized across architectures. | |
1301 | ||
1302 | It is common to locate any additional processing in a boot/ | |
1303 | directory below arch/$(SRCARCH)/. | |
1da177e4 | 1304 | |
9f1fe2bb JN |
1305 | Kbuild does not provide any smart way to support building a |
1306 | target specified in boot/. Therefore arch/$(SRCARCH)/Makefile shall | |
1307 | call make manually to build a target in boot/. | |
1da177e4 | 1308 | |
9f1fe2bb JN |
1309 | The recommended approach is to include shortcuts in |
1310 | arch/$(SRCARCH)/Makefile, and use the full path when calling down | |
1311 | into the arch/$(SRCARCH)/boot/Makefile. | |
1da177e4 | 1312 | |
9f1fe2bb | 1313 | Example:: |
1da177e4 | 1314 | |
9f1fe2bb JN |
1315 | #arch/x86/Makefile |
1316 | boot := arch/x86/boot | |
1317 | bzImage: vmlinux | |
1318 | $(Q)$(MAKE) $(build)=$(boot) $(boot)/$@ | |
cd238eff | 1319 | |
2f0e2a39 | 1320 | ``$(Q)$(MAKE) $(build)=<dir>`` is the recommended way to invoke |
9f1fe2bb | 1321 | make in a subdirectory. |
1da177e4 | 1322 | |
9f1fe2bb | 1323 | There are no rules for naming architecture-specific targets, |
2f0e2a39 | 1324 | but executing ``make help`` will list all relevant targets. |
9f1fe2bb | 1325 | To support this, $(archhelp) must be defined. |
1da177e4 | 1326 | |
9f1fe2bb | 1327 | Example:: |
1da177e4 | 1328 | |
9f1fe2bb JN |
1329 | #arch/x86/Makefile |
1330 | define archhelp | |
1331 | echo '* bzImage - Compressed kernel image (arch/x86/boot/bzImage)' | |
1332 | endif | |
cd238eff | 1333 | |
9f1fe2bb JN |
1334 | When make is executed without arguments, the first goal encountered |
1335 | will be built. In the top level Makefile the first goal present | |
1336 | is all:. | |
1da177e4 | 1337 | |
9f1fe2bb | 1338 | An architecture shall always, per default, build a bootable image. |
2f0e2a39 | 1339 | In ``make help``, the default goal is highlighted with a ``*``. |
1da177e4 | 1340 | |
9f1fe2bb JN |
1341 | Add a new prerequisite to all: to select a default goal different |
1342 | from vmlinux. | |
cd238eff | 1343 | |
9f1fe2bb | 1344 | Example:: |
1da177e4 | 1345 | |
9f1fe2bb JN |
1346 | #arch/x86/Makefile |
1347 | all: bzImage | |
1348 | ||
2f0e2a39 | 1349 | When ``make`` is executed without arguments, bzImage will be built. |
1da177e4 | 1350 | |
1a4c1c9d JN |
1351 | Commands useful for building a boot image |
1352 | ----------------------------------------- | |
1da177e4 | 1353 | |
9f1fe2bb JN |
1354 | Kbuild provides a few macros that are useful when building a |
1355 | boot image. | |
1356 | ||
1357 | ld | |
1358 | Link target. Often, LDFLAGS_$@ is used to set specific options to ld. | |
1da177e4 | 1359 | |
9f1fe2bb | 1360 | Example:: |
39e6e9cf | 1361 | |
9f1fe2bb JN |
1362 | #arch/x86/boot/Makefile |
1363 | LDFLAGS_bootsect := -Ttext 0x0 -s --oformat binary | |
1364 | LDFLAGS_setup := -Ttext 0x0 -s --oformat binary -e begtext | |
cd238eff | 1365 | |
9f1fe2bb JN |
1366 | targets += setup setup.o bootsect bootsect.o |
1367 | $(obj)/setup $(obj)/bootsect: %: %.o FORCE | |
1368 | $(call if_changed,ld) | |
1da177e4 | 1369 | |
9f1fe2bb JN |
1370 | In this example, there are two possible targets, requiring different |
1371 | options to the linker. The linker options are specified using the | |
1372 | LDFLAGS_$@ syntax - one for each potential target. | |
1da177e4 | 1373 | |
9f1fe2bb JN |
1374 | $(targets) are assigned all potential targets, by which kbuild knows |
1375 | the targets and will: | |
cd238eff | 1376 | |
9f1fe2bb JN |
1377 | 1) check for commandline changes |
1378 | 2) delete target during make clean | |
1da177e4 | 1379 | |
2f0e2a39 | 1380 | The ``: %: %.o`` part of the prerequisite is a shorthand that |
9f1fe2bb | 1381 | frees us from listing the setup.o and bootsect.o files. |
cd238eff | 1382 | |
9f1fe2bb | 1383 | Note: |
2f0e2a39 | 1384 | It is a common mistake to forget the ``targets :=`` assignment, |
9f1fe2bb JN |
1385 | resulting in the target file being recompiled for no |
1386 | obvious reason. | |
1da177e4 | 1387 | |
9f1fe2bb JN |
1388 | objcopy |
1389 | Copy binary. Uses OBJCOPYFLAGS usually specified in | |
1390 | arch/$(SRCARCH)/Makefile. | |
d87e47e1 | 1391 | |
9f1fe2bb | 1392 | OBJCOPYFLAGS_$@ may be used to set additional options. |
d87e47e1 | 1393 | |
9f1fe2bb JN |
1394 | gzip |
1395 | Compress target. Use maximum compression to compress target. | |
cd238eff | 1396 | |
9f1fe2bb | 1397 | Example:: |
d87e47e1 | 1398 | |
9f1fe2bb JN |
1399 | #arch/x86/boot/compressed/Makefile |
1400 | $(obj)/vmlinux.bin.gz: $(vmlinux.bin.all-y) FORCE | |
1401 | $(call if_changed,gzip) | |
aab94339 | 1402 | |
9f1fe2bb JN |
1403 | dtc |
1404 | Create flattened device tree blob object suitable for linking | |
1405 | into vmlinux. Device tree blobs linked into vmlinux are placed | |
1406 | in an init section in the image. Platform code *must* copy the | |
1407 | blob to non-init memory prior to calling unflatten_device_tree(). | |
aab94339 | 1408 | |
2f0e2a39 JN |
1409 | To use this command, simply add ``*.dtb`` into obj-y or targets, or make |
1410 | some other target depend on ``%.dtb`` | |
aab94339 | 1411 | |
2f0e2a39 | 1412 | A central rule exists to create ``$(obj)/%.dtb`` from ``$(src)/%.dts``; |
9f1fe2bb | 1413 | architecture Makefiles do no need to explicitly write out that rule. |
cd238eff | 1414 | |
9f1fe2bb JN |
1415 | Example:: |
1416 | ||
1417 | targets += $(dtb-y) | |
1418 | DTC_FLAGS ?= -p 1024 | |
1da177e4 | 1419 | |
1a4c1c9d JN |
1420 | Preprocessing linker scripts |
1421 | ---------------------------- | |
1da177e4 | 1422 | |
9f1fe2bb JN |
1423 | When the vmlinux image is built, the linker script |
1424 | arch/$(SRCARCH)/kernel/vmlinux.lds is used. | |
1425 | ||
1426 | The script is a preprocessed variant of the file vmlinux.lds.S | |
1427 | located in the same directory. | |
1428 | ||
2f0e2a39 | 1429 | kbuild knows .lds files and includes a rule ``*lds.S`` -> ``*lds``. |
9f1fe2bb JN |
1430 | |
1431 | Example:: | |
cd238eff | 1432 | |
9f1fe2bb JN |
1433 | #arch/x86/kernel/Makefile |
1434 | extra-y := vmlinux.lds | |
39e6e9cf | 1435 | |
9f1fe2bb JN |
1436 | The assignment to extra-y is used to tell kbuild to build the |
1437 | target vmlinux.lds. | |
39e6e9cf | 1438 | |
9f1fe2bb JN |
1439 | The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the |
1440 | specified options when building the target vmlinux.lds. | |
39e6e9cf | 1441 | |
2f0e2a39 | 1442 | When building the ``*.lds`` target, kbuild uses the variables:: |
cd238eff | 1443 | |
9f1fe2bb JN |
1444 | KBUILD_CPPFLAGS : Set in top-level Makefile |
1445 | cppflags-y : May be set in the kbuild makefile | |
1446 | CPPFLAGS_$(@F) : Target-specific flags. | |
1447 | Note that the full filename is used in this | |
1448 | assignment. | |
1da177e4 | 1449 | |
2f0e2a39 | 1450 | The kbuild infrastructure for ``*lds`` files is used in several |
9f1fe2bb | 1451 | architecture-specific files. |
1da177e4 | 1452 | |
1a4c1c9d JN |
1453 | Generic header files |
1454 | -------------------- | |
d8ecc5cd | 1455 | |
9f1fe2bb JN |
1456 | The directory include/asm-generic contains the header files |
1457 | that may be shared between individual architectures. | |
1458 | ||
1459 | The recommended approach how to use a generic header file is | |
1460 | to list the file in the Kbuild file. | |
1461 | ||
1462 | See `generic-y`_ for further info on syntax etc. | |
d8ecc5cd | 1463 | |
1a4c1c9d JN |
1464 | Post-link pass |
1465 | -------------- | |
fbe6e37d | 1466 | |
9f1fe2bb JN |
1467 | If the file arch/xxx/Makefile.postlink exists, this makefile |
1468 | will be invoked for post-link objects (vmlinux and modules.ko) | |
1469 | for architectures to run post-link passes on. Must also handle | |
1470 | the clean target. | |
fbe6e37d | 1471 | |
9f1fe2bb JN |
1472 | This pass runs after kallsyms generation. If the architecture |
1473 | needs to modify symbol locations, rather than manipulate the | |
1474 | kallsyms, it may be easier to add another postlink target for | |
1475 | .tmp_vmlinux? targets to be called from link-vmlinux.sh. | |
fbe6e37d | 1476 | |
9f1fe2bb JN |
1477 | For example, powerpc uses this to check relocation sanity of |
1478 | the linked vmlinux file. | |
fbe6e37d | 1479 | |
1a4c1c9d JN |
1480 | Kbuild syntax for exported headers |
1481 | ================================== | |
c7bb349e | 1482 | |
39fed701 | 1483 | The kernel includes a set of headers that is exported to userspace. |
c95940f2 | 1484 | Many headers can be exported as-is but other headers require a |
c7bb349e | 1485 | minimal pre-processing before they are ready for user-space. |
9f1fe2bb | 1486 | |
c7bb349e | 1487 | The pre-processing does: |
cd238eff | 1488 | |
39fed701 | 1489 | - drop kernel-specific annotations |
c7bb349e | 1490 | - drop include of compiler.h |
2f0e2a39 | 1491 | - drop all sections that are kernel internal (guarded by ``ifdef __KERNEL__``) |
c7bb349e | 1492 | |
fcc8487d | 1493 | All headers under include/uapi/, include/generated/uapi/, |
61562f98 | 1494 | arch/<arch>/include/uapi/ and arch/<arch>/include/generated/uapi/ |
fcc8487d | 1495 | are exported. |
c7bb349e | 1496 | |
fcc8487d ND |
1497 | A Kbuild file may be defined under arch/<arch>/include/uapi/asm/ and |
1498 | arch/<arch>/include/asm/ to list asm files coming from asm-generic. | |
9f1fe2bb | 1499 | |
fcc8487d | 1500 | See subsequent chapter for the syntax of the Kbuild file. |
c7bb349e | 1501 | |
1a4c1c9d JN |
1502 | no-export-headers |
1503 | ----------------- | |
c7bb349e | 1504 | |
9f1fe2bb JN |
1505 | no-export-headers is essentially used by include/uapi/linux/Kbuild to |
1506 | avoid exporting specific headers (e.g. kvm.h) on architectures that do | |
1507 | not support it. It should be avoided as much as possible. | |
c7bb349e | 1508 | |
1a4c1c9d JN |
1509 | generic-y |
1510 | --------- | |
d8ecc5cd | 1511 | |
9f1fe2bb JN |
1512 | If an architecture uses a verbatim copy of a header from |
1513 | include/asm-generic then this is listed in the file | |
1514 | arch/$(SRCARCH)/include/asm/Kbuild like this: | |
d8ecc5cd | 1515 | |
9f1fe2bb | 1516 | Example:: |
cd238eff | 1517 | |
9f1fe2bb JN |
1518 | #arch/x86/include/asm/Kbuild |
1519 | generic-y += termios.h | |
1520 | generic-y += rtc.h | |
d8ecc5cd | 1521 | |
9f1fe2bb JN |
1522 | During the prepare phase of the build a wrapper include |
1523 | file is generated in the directory:: | |
d8ecc5cd | 1524 | |
9f1fe2bb | 1525 | arch/$(SRCARCH)/include/generated/asm |
d8ecc5cd | 1526 | |
9f1fe2bb JN |
1527 | When a header is exported where the architecture uses |
1528 | the generic header a similar wrapper is generated as part | |
1529 | of the set of exported headers in the directory:: | |
d8ecc5cd | 1530 | |
9f1fe2bb | 1531 | usr/include/asm |
d8ecc5cd | 1532 | |
9f1fe2bb | 1533 | The generated wrapper will in both cases look like the following: |
d8ecc5cd | 1534 | |
9f1fe2bb | 1535 | Example: termios.h:: |
cd238eff | 1536 | |
9f1fe2bb | 1537 | #include <asm-generic/termios.h> |
c7bb349e | 1538 | |
1a4c1c9d JN |
1539 | generated-y |
1540 | ----------- | |
54b880ca | 1541 | |
9f1fe2bb JN |
1542 | If an architecture generates other header files alongside generic-y |
1543 | wrappers, generated-y specifies them. | |
54b880ca | 1544 | |
9f1fe2bb JN |
1545 | This prevents them being treated as stale asm-generic wrappers and |
1546 | removed. | |
54b880ca | 1547 | |
9f1fe2bb | 1548 | Example:: |
cd238eff | 1549 | |
9f1fe2bb JN |
1550 | #arch/x86/include/asm/Kbuild |
1551 | generated-y += syscalls_32.h | |
54b880ca | 1552 | |
1a4c1c9d JN |
1553 | mandatory-y |
1554 | ----------- | |
fcc8487d | 1555 | |
9f1fe2bb JN |
1556 | mandatory-y is essentially used by include/(uapi/)asm-generic/Kbuild |
1557 | to define the minimum set of ASM headers that all architectures must have. | |
91998731 | 1558 | |
9f1fe2bb JN |
1559 | This works like optional generic-y. If a mandatory header is missing |
1560 | in arch/$(SRCARCH)/include/(uapi/)/asm, Kbuild will automatically | |
1561 | generate a wrapper of the asm-generic one. | |
fcc8487d | 1562 | |
1a4c1c9d JN |
1563 | Kbuild Variables |
1564 | ================ | |
1da177e4 LT |
1565 | |
1566 | The top Makefile exports the following variables: | |
1567 | ||
9f1fe2bb JN |
1568 | VERSION, PATCHLEVEL, SUBLEVEL, EXTRAVERSION |
1569 | These variables define the current kernel version. A few arch | |
1570 | Makefiles actually use these values directly; they should use | |
1571 | $(KERNELRELEASE) instead. | |
1572 | ||
1573 | $(VERSION), $(PATCHLEVEL), and $(SUBLEVEL) define the basic | |
1574 | three-part version number, such as "2", "4", and "0". These three | |
1575 | values are always numeric. | |
1576 | ||
1577 | $(EXTRAVERSION) defines an even tinier sublevel for pre-patches | |
1578 | or additional patches. It is usually some non-numeric string | |
1579 | such as "-pre4", and is often blank. | |
1580 | ||
1581 | KERNELRELEASE | |
1582 | $(KERNELRELEASE) is a single string such as "2.4.0-pre4", suitable | |
1583 | for constructing installation directory names or showing in | |
1584 | version strings. Some arch Makefiles use it for this purpose. | |
1585 | ||
1586 | ARCH | |
1587 | This variable defines the target architecture, such as "i386", | |
1588 | "arm", or "sparc". Some kbuild Makefiles test $(ARCH) to | |
1589 | determine which files to compile. | |
1590 | ||
1591 | By default, the top Makefile sets $(ARCH) to be the same as the | |
1592 | host system architecture. For a cross build, a user may | |
1593 | override the value of $(ARCH) on the command line:: | |
1594 | ||
1595 | make ARCH=m68k ... | |
1596 | ||
1597 | SRCARCH | |
1598 | This variable specifies the directory in arch/ to build. | |
1599 | ||
1600 | ARCH and SRCARCH may not necessarily match. A couple of arch | |
2f0e2a39 | 1601 | directories are biarch, that is, a single ``arch/*/`` directory supports |
9f1fe2bb JN |
1602 | both 32-bit and 64-bit. |
1603 | ||
1604 | For example, you can pass in ARCH=i386, ARCH=x86_64, or ARCH=x86. | |
1605 | For all of them, SRCARCH=x86 because arch/x86/ supports both i386 and | |
1606 | x86_64. | |
1607 | ||
1608 | INSTALL_PATH | |
1609 | This variable defines a place for the arch Makefiles to install | |
1610 | the resident kernel image and System.map file. | |
1611 | Use this for architecture-specific install targets. | |
1612 | ||
1613 | INSTALL_MOD_PATH, MODLIB | |
1614 | $(INSTALL_MOD_PATH) specifies a prefix to $(MODLIB) for module | |
1615 | installation. This variable is not defined in the Makefile but | |
1616 | may be passed in by the user if desired. | |
1617 | ||
1618 | $(MODLIB) specifies the directory for module installation. | |
1619 | The top Makefile defines $(MODLIB) to | |
1620 | $(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE). The user may | |
1621 | override this value on the command line if desired. | |
1622 | ||
1623 | INSTALL_MOD_STRIP | |
1624 | If this variable is specified, it will cause modules to be stripped | |
2f0e2a39 | 1625 | after they are installed. If INSTALL_MOD_STRIP is "1", then the |
9f1fe2bb JN |
1626 | default option --strip-debug will be used. Otherwise, the |
1627 | INSTALL_MOD_STRIP value will be used as the option(s) to the strip | |
1628 | command. | |
ac031f26 | 1629 | |
1b627289 RM |
1630 | INSTALL_DTBS_PATH |
1631 | This variable specifies a prefix for relocations required by build | |
1632 | roots. It defines a place for installing the device tree blobs. Like | |
1633 | INSTALL_MOD_PATH, it isn't defined in the Makefile, but can be passed | |
1634 | by the user if desired. Otherwise it defaults to the kernel install | |
1635 | path. | |
1636 | ||
1a4c1c9d JN |
1637 | Makefile language |
1638 | ================= | |
1da177e4 | 1639 | |
a07f6033 | 1640 | The kernel Makefiles are designed to be run with GNU Make. The Makefiles |
1da177e4 LT |
1641 | use only the documented features of GNU Make, but they do use many |
1642 | GNU extensions. | |
1643 | ||
1644 | GNU Make supports elementary list-processing functions. The kernel | |
1645 | Makefiles use a novel style of list building and manipulation with few | |
2f0e2a39 | 1646 | ``if`` statements. |
1da177e4 | 1647 | |
2f0e2a39 | 1648 | GNU Make has two assignment operators, ``:=`` and ``=``. ``:=`` performs |
1da177e4 | 1649 | immediate evaluation of the right-hand side and stores an actual string |
2f0e2a39 | 1650 | into the left-hand side. ``=`` is like a formula definition; it stores the |
1da177e4 LT |
1651 | right-hand side in an unevaluated form and then evaluates this form each |
1652 | time the left-hand side is used. | |
1653 | ||
2f0e2a39 | 1654 | There are some cases where ``=`` is appropriate. Usually, though, ``:=`` |
1da177e4 LT |
1655 | is the right choice. |
1656 | ||
1a4c1c9d JN |
1657 | Credits |
1658 | ======= | |
1da177e4 | 1659 | |
cd238eff MCC |
1660 | - Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net> |
1661 | - Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de> | |
1662 | - Updates by Sam Ravnborg <sam@ravnborg.org> | |
1663 | - Language QA by Jan Engelhardt <jengelh@gmx.de> | |
1da177e4 | 1664 | |
1a4c1c9d JN |
1665 | TODO |
1666 | ==== | |
1da177e4 | 1667 | |
a07f6033 | 1668 | - Describe how kbuild supports shipped files with _shipped. |
1da177e4 | 1669 | - Generating offset header files. |
b26ff488 | 1670 | - Add more variables to chapters 7 or 9? |