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