Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | Linux Kernel Makefiles |
2 | ||
3 | This document describes the Linux kernel Makefiles. | |
4 | ||
5 | === Table of Contents | |
6 | ||
7 | === 1 Overview | |
8 | === 2 Who does what | |
9 | === 3 The kbuild files | |
10 | --- 3.1 Goal definitions | |
11 | --- 3.2 Built-in object goals - obj-y | |
12 | --- 3.3 Loadable module goals - obj-m | |
13 | --- 3.4 Objects which export symbols | |
14 | --- 3.5 Library file goals - lib-y | |
15 | --- 3.6 Descending down in directories | |
16 | --- 3.7 Compilation flags | |
17 | --- 3.8 Command line dependency | |
18 | --- 3.9 Dependency tracking | |
19 | --- 3.10 Special Rules | |
20a468b5 | 20 | --- 3.11 $(CC) support functions |
691ef3e7 | 21 | --- 3.12 $(LD) support functions |
1da177e4 LT |
22 | |
23 | === 4 Host Program support | |
24 | --- 4.1 Simple Host Program | |
25 | --- 4.2 Composite Host Programs | |
39e6e9cf | 26 | --- 4.3 Defining shared libraries |
1da177e4 LT |
27 | --- 4.4 Using C++ for host programs |
28 | --- 4.5 Controlling compiler options for host programs | |
29 | --- 4.6 When host programs are actually built | |
30 | --- 4.7 Using hostprogs-$(CONFIG_FOO) | |
31 | ||
32 | === 5 Kbuild clean infrastructure | |
33 | ||
34 | === 6 Architecture Makefiles | |
35 | --- 6.1 Set variables to tweak the build to the architecture | |
5bb78269 | 36 | --- 6.2 Add prerequisites to archprepare: |
1da177e4 | 37 | --- 6.3 List directories to visit when descending |
5c811e59 | 38 | --- 6.4 Architecture-specific boot images |
1da177e4 LT |
39 | --- 6.5 Building non-kbuild targets |
40 | --- 6.6 Commands useful for building a boot image | |
41 | --- 6.7 Custom kbuild commands | |
42 | --- 6.8 Preprocessing linker scripts | |
d8ecc5cd | 43 | --- 6.9 Generic header files |
1da177e4 | 44 | |
c7bb349e SR |
45 | === 7 Kbuild syntax for exported headers |
46 | --- 7.1 header-y | |
47 | --- 7.2 objhdr-y | |
48 | --- 7.3 destination-y | |
d8ecc5cd | 49 | --- 7.4 generic-y |
c7bb349e SR |
50 | |
51 | === 8 Kbuild Variables | |
52 | === 9 Makefile language | |
53 | === 10 Credits | |
54 | === 11 TODO | |
1da177e4 LT |
55 | |
56 | === 1 Overview | |
57 | ||
58 | The Makefiles have five parts: | |
59 | ||
60 | Makefile the top Makefile. | |
61 | .config the kernel configuration file. | |
62 | arch/$(ARCH)/Makefile the arch Makefile. | |
63 | scripts/Makefile.* common rules etc. for all kbuild Makefiles. | |
64 | kbuild Makefiles there are about 500 of these. | |
65 | ||
66 | The top Makefile reads the .config file, which comes from the kernel | |
67 | configuration process. | |
68 | ||
69 | The top Makefile is responsible for building two major products: vmlinux | |
70 | (the resident kernel image) and modules (any module files). | |
71 | It builds these goals by recursively descending into the subdirectories of | |
72 | the kernel source tree. | |
73 | The list of subdirectories which are visited depends upon the kernel | |
74 | configuration. The top Makefile textually includes an arch Makefile | |
75 | with the name arch/$(ARCH)/Makefile. The arch Makefile supplies | |
76 | architecture-specific information to the top Makefile. | |
77 | ||
78 | Each subdirectory has a kbuild Makefile which carries out the commands | |
79 | passed down from above. The kbuild Makefile uses information from the | |
39e6e9cf | 80 | .config file to construct various file lists used by kbuild to build |
1da177e4 LT |
81 | any built-in or modular targets. |
82 | ||
83 | scripts/Makefile.* contains all the definitions/rules etc. that | |
84 | are used to build the kernel based on the kbuild makefiles. | |
85 | ||
86 | ||
87 | === 2 Who does what | |
88 | ||
89 | People have four different relationships with the kernel Makefiles. | |
90 | ||
91 | *Users* are people who build kernels. These people type commands such as | |
92 | "make menuconfig" or "make". They usually do not read or edit | |
93 | any kernel Makefiles (or any other source files). | |
94 | ||
95 | *Normal developers* are people who work on features such as device | |
96 | drivers, file systems, and network protocols. These people need to | |
a07f6033 | 97 | maintain the kbuild Makefiles for the subsystem they are |
1da177e4 LT |
98 | working on. In order to do this effectively, they need some overall |
99 | knowledge about the kernel Makefiles, plus detailed knowledge about the | |
100 | public interface for kbuild. | |
101 | ||
102 | *Arch developers* are people who work on an entire architecture, such | |
103 | as sparc or ia64. Arch developers need to know about the arch Makefile | |
104 | as well as kbuild Makefiles. | |
105 | ||
106 | *Kbuild developers* are people who work on the kernel build system itself. | |
107 | These people need to know about all aspects of the kernel Makefiles. | |
108 | ||
109 | This document is aimed towards normal developers and arch developers. | |
110 | ||
111 | ||
112 | === 3 The kbuild files | |
113 | ||
114 | Most Makefiles within the kernel are kbuild Makefiles that use the | |
a07f6033 | 115 | kbuild infrastructure. This chapter introduces the syntax used in the |
1da177e4 | 116 | kbuild makefiles. |
172c3ae3 | 117 | The preferred name for the kbuild files are 'Makefile' but 'Kbuild' can |
a07f6033 | 118 | be used and if both a 'Makefile' and a 'Kbuild' file exists, then the 'Kbuild' |
172c3ae3 | 119 | file will be used. |
1da177e4 LT |
120 | |
121 | Section 3.1 "Goal definitions" is a quick intro, further chapters provide | |
122 | more details, with real examples. | |
123 | ||
124 | --- 3.1 Goal definitions | |
125 | ||
126 | Goal definitions are the main part (heart) of the kbuild Makefile. | |
127 | These lines define the files to be built, any special compilation | |
128 | options, and any subdirectories to be entered recursively. | |
129 | ||
130 | The most simple kbuild makefile contains one line: | |
131 | ||
132 | Example: | |
133 | obj-y += foo.o | |
134 | ||
5c811e59 | 135 | This tells kbuild that there is one object in that directory, named |
1da177e4 LT |
136 | foo.o. foo.o will be built from foo.c or foo.S. |
137 | ||
138 | If foo.o shall be built as a module, the variable obj-m is used. | |
139 | Therefore the following pattern is often used: | |
140 | ||
141 | Example: | |
142 | obj-$(CONFIG_FOO) += foo.o | |
143 | ||
144 | $(CONFIG_FOO) evaluates to either y (for built-in) or m (for module). | |
145 | If CONFIG_FOO is neither y nor m, then the file will not be compiled | |
146 | nor linked. | |
147 | ||
148 | --- 3.2 Built-in object goals - obj-y | |
149 | ||
150 | The kbuild Makefile specifies object files for vmlinux | |
a07f6033 | 151 | in the $(obj-y) lists. These lists depend on the kernel |
1da177e4 LT |
152 | configuration. |
153 | ||
154 | Kbuild compiles all the $(obj-y) files. It then calls | |
155 | "$(LD) -r" to merge these files into one built-in.o file. | |
156 | built-in.o is later linked into vmlinux by the parent Makefile. | |
157 | ||
158 | The order of files in $(obj-y) is significant. Duplicates in | |
159 | the lists are allowed: the first instance will be linked into | |
160 | built-in.o and succeeding instances will be ignored. | |
161 | ||
162 | Link order is significant, because certain functions | |
163 | (module_init() / __initcall) will be called during boot in the | |
164 | order they appear. So keep in mind that changing the link | |
a07f6033 JE |
165 | order may e.g. change the order in which your SCSI |
166 | controllers are detected, and thus your disks are renumbered. | |
1da177e4 LT |
167 | |
168 | Example: | |
169 | #drivers/isdn/i4l/Makefile | |
170 | # Makefile for the kernel ISDN subsystem and device drivers. | |
171 | # Each configuration option enables a list of files. | |
2f5a2f81 | 172 | obj-$(CONFIG_ISDN_I4L) += isdn.o |
1da177e4 LT |
173 | obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o |
174 | ||
175 | --- 3.3 Loadable module goals - obj-m | |
176 | ||
177 | $(obj-m) specify object files which are built as loadable | |
178 | kernel modules. | |
179 | ||
180 | A module may be built from one source file or several source | |
181 | files. In the case of one source file, the kbuild makefile | |
182 | simply adds the file to $(obj-m). | |
183 | ||
184 | Example: | |
185 | #drivers/isdn/i4l/Makefile | |
186 | obj-$(CONFIG_ISDN_PPP_BSDCOMP) += isdn_bsdcomp.o | |
187 | ||
188 | Note: In this example $(CONFIG_ISDN_PPP_BSDCOMP) evaluates to 'm' | |
189 | ||
190 | If a kernel module is built from several source files, you specify | |
4f827280 MM |
191 | that you want to build a module in the same way as above; however, |
192 | kbuild needs to know which object files you want to build your | |
193 | module from, so you have to tell it by setting a $(<module_name>-y) | |
194 | variable. | |
1da177e4 LT |
195 | |
196 | Example: | |
197 | #drivers/isdn/i4l/Makefile | |
4f827280 MM |
198 | obj-$(CONFIG_ISDN_I4L) += isdn.o |
199 | isdn-y := isdn_net_lib.o isdn_v110.o isdn_common.o | |
1da177e4 LT |
200 | |
201 | In this example, the module name will be isdn.o. Kbuild will | |
4f827280 | 202 | compile the objects listed in $(isdn-y) and then run |
1da177e4 LT |
203 | "$(LD) -r" on the list of these files to generate isdn.o. |
204 | ||
4f827280 MM |
205 | Due to kbuild recognizing $(<module_name>-y) for composite objects, |
206 | you can use the value of a CONFIG_ symbol to optionally include an | |
207 | object file as part of a composite object. | |
1da177e4 LT |
208 | |
209 | Example: | |
210 | #fs/ext2/Makefile | |
4f827280 MM |
211 | obj-$(CONFIG_EXT2_FS) += ext2.o |
212 | ext2-y := balloc.o dir.o file.o ialloc.o inode.o ioctl.o \ | |
213 | namei.o super.o symlink.o | |
214 | ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o xattr_user.o \ | |
215 | xattr_trusted.o | |
216 | ||
217 | In this example, xattr.o, xattr_user.o and xattr_trusted.o are only | |
218 | part of the composite object ext2.o if $(CONFIG_EXT2_FS_XATTR) | |
219 | evaluates to 'y'. | |
1da177e4 LT |
220 | |
221 | Note: Of course, when you are building objects into the kernel, | |
222 | the syntax above will also work. So, if you have CONFIG_EXT2_FS=y, | |
223 | kbuild will build an ext2.o file for you out of the individual | |
224 | parts and then link this into built-in.o, as you would expect. | |
225 | ||
226 | --- 3.4 Objects which export symbols | |
227 | ||
228 | No special notation is required in the makefiles for | |
229 | modules exporting symbols. | |
230 | ||
231 | --- 3.5 Library file goals - lib-y | |
232 | ||
a07f6033 | 233 | Objects listed with obj-* are used for modules, or |
1da177e4 LT |
234 | combined in a built-in.o for that specific directory. |
235 | There is also the possibility to list objects that will | |
236 | be included in a library, lib.a. | |
237 | All objects listed with lib-y are combined in a single | |
238 | library for that directory. | |
5d3f083d ML |
239 | Objects that are listed in obj-y and additionally listed in |
240 | lib-y will not be included in the library, since they will | |
241 | be accessible anyway. | |
a07f6033 | 242 | For consistency, objects listed in lib-m will be included in lib.a. |
1da177e4 LT |
243 | |
244 | Note that the same kbuild makefile may list files to be built-in | |
245 | and to be part of a library. Therefore the same directory | |
246 | may contain both a built-in.o and a lib.a file. | |
247 | ||
248 | Example: | |
2f5a2f81 MM |
249 | #arch/x86/lib/Makefile |
250 | lib-y := delay.o | |
1da177e4 | 251 | |
2f5a2f81 MM |
252 | This will create a library lib.a based on delay.o. For kbuild to |
253 | actually recognize that there is a lib.a being built, the directory | |
254 | shall be listed in libs-y. | |
1da177e4 | 255 | See also "6.3 List directories to visit when descending". |
39e6e9cf | 256 | |
a07f6033 | 257 | Use of lib-y is normally restricted to lib/ and arch/*/lib. |
1da177e4 LT |
258 | |
259 | --- 3.6 Descending down in directories | |
260 | ||
261 | A Makefile is only responsible for building objects in its own | |
262 | directory. Files in subdirectories should be taken care of by | |
263 | Makefiles in these subdirs. The build system will automatically | |
264 | invoke make recursively in subdirectories, provided you let it know of | |
265 | them. | |
266 | ||
a07f6033 | 267 | To do so, obj-y and obj-m are used. |
1da177e4 LT |
268 | ext2 lives in a separate directory, and the Makefile present in fs/ |
269 | tells kbuild to descend down using the following assignment. | |
270 | ||
271 | Example: | |
272 | #fs/Makefile | |
273 | obj-$(CONFIG_EXT2_FS) += ext2/ | |
274 | ||
275 | If CONFIG_EXT2_FS is set to either 'y' (built-in) or 'm' (modular) | |
276 | the corresponding obj- variable will be set, and kbuild will descend | |
277 | down in the ext2 directory. | |
278 | Kbuild only uses this information to decide that it needs to visit | |
279 | the directory, it is the Makefile in the subdirectory that | |
280 | specifies what is modules and what is built-in. | |
281 | ||
282 | It is good practice to use a CONFIG_ variable when assigning directory | |
283 | names. This allows kbuild to totally skip the directory if the | |
284 | corresponding CONFIG_ option is neither 'y' nor 'm'. | |
285 | ||
286 | --- 3.7 Compilation flags | |
287 | ||
f77bf014 | 288 | ccflags-y, asflags-y and ldflags-y |
c95940f2 NK |
289 | These three flags apply only to the kbuild makefile in which they |
290 | are assigned. They are used for all the normal cc, as and ld | |
291 | invocations happening during a recursive build. | |
f77bf014 | 292 | Note: Flags with the same behaviour were previously named: |
c95940f2 NK |
293 | EXTRA_CFLAGS, EXTRA_AFLAGS and EXTRA_LDFLAGS. |
294 | They are still supported but their usage is deprecated. | |
1da177e4 | 295 | |
eb07e1b4 | 296 | ccflags-y specifies options for compiling with $(CC). |
1da177e4 LT |
297 | |
298 | Example: | |
eb07e1b4 MM |
299 | # drivers/acpi/Makefile |
300 | ccflags-y := -Os | |
301 | ccflags-$(CONFIG_ACPI_DEBUG) += -DACPI_DEBUG_OUTPUT | |
1da177e4 LT |
302 | |
303 | This variable is necessary because the top Makefile owns the | |
a0f97e06 | 304 | variable $(KBUILD_CFLAGS) and uses it for compilation flags for the |
1da177e4 LT |
305 | entire tree. |
306 | ||
eb07e1b4 | 307 | asflags-y specifies options for assembling with $(AS). |
1da177e4 LT |
308 | |
309 | Example: | |
eb07e1b4 MM |
310 | #arch/sparc/kernel/Makefile |
311 | asflags-y := -ansi | |
1da177e4 | 312 | |
eb07e1b4 | 313 | ldflags-y specifies options for linking with $(LD). |
1da177e4 LT |
314 | |
315 | Example: | |
eb07e1b4 MM |
316 | #arch/cris/boot/compressed/Makefile |
317 | ldflags-y += -T $(srctree)/$(src)/decompress_$(arch-y).lds | |
1da177e4 | 318 | |
720097d8 | 319 | subdir-ccflags-y, subdir-asflags-y |
eb07e1b4 | 320 | The two flags listed above are similar to ccflags-y and asflags-y. |
c95940f2 NK |
321 | The difference is that the subdir- variants have effect for the kbuild |
322 | file where they are present and all subdirectories. | |
323 | Options specified using subdir-* are added to the commandline before | |
324 | the options specified using the non-subdir variants. | |
720097d8 SR |
325 | |
326 | Example: | |
327 | subdir-ccflags-y := -Werror | |
328 | ||
1da177e4 LT |
329 | CFLAGS_$@, AFLAGS_$@ |
330 | ||
331 | CFLAGS_$@ and AFLAGS_$@ only apply to commands in current | |
332 | kbuild makefile. | |
333 | ||
334 | $(CFLAGS_$@) specifies per-file options for $(CC). The $@ | |
335 | part has a literal value which specifies the file that it is for. | |
336 | ||
337 | Example: | |
338 | # drivers/scsi/Makefile | |
339 | CFLAGS_aha152x.o = -DAHA152X_STAT -DAUTOCONF | |
340 | CFLAGS_gdth.o = # -DDEBUG_GDTH=2 -D__SERIAL__ -D__COM2__ \ | |
341 | -DGDTH_STATISTICS | |
1da177e4 | 342 | |
eb07e1b4 | 343 | These two lines specify compilation flags for aha152x.o and gdth.o. |
1da177e4 LT |
344 | |
345 | $(AFLAGS_$@) is a similar feature for source files in assembly | |
346 | languages. | |
347 | ||
348 | Example: | |
349 | # arch/arm/kernel/Makefile | |
eb07e1b4 MM |
350 | AFLAGS_head.o := -DTEXT_OFFSET=$(TEXT_OFFSET) |
351 | AFLAGS_crunch-bits.o := -Wa,-mcpu=ep9312 | |
352 | AFLAGS_iwmmxt.o := -Wa,-mcpu=iwmmxt | |
353 | ||
1da177e4 LT |
354 | |
355 | --- 3.9 Dependency tracking | |
356 | ||
357 | Kbuild tracks dependencies on the following: | |
358 | 1) All prerequisite files (both *.c and *.h) | |
359 | 2) CONFIG_ options used in all prerequisite files | |
360 | 3) Command-line used to compile target | |
361 | ||
362 | Thus, if you change an option to $(CC) all affected files will | |
363 | be re-compiled. | |
364 | ||
365 | --- 3.10 Special Rules | |
366 | ||
367 | Special rules are used when the kbuild infrastructure does | |
368 | not provide the required support. A typical example is | |
369 | header files generated during the build process. | |
5c811e59 | 370 | Another example are the architecture-specific Makefiles which |
a07f6033 | 371 | need special rules to prepare boot images etc. |
1da177e4 LT |
372 | |
373 | Special rules are written as normal Make rules. | |
374 | Kbuild is not executing in the directory where the Makefile is | |
375 | located, so all special rules shall provide a relative | |
376 | path to prerequisite files and target files. | |
377 | ||
378 | Two variables are used when defining special rules: | |
379 | ||
380 | $(src) | |
381 | $(src) is a relative path which points to the directory | |
382 | where the Makefile is located. Always use $(src) when | |
383 | referring to files located in the src tree. | |
384 | ||
385 | $(obj) | |
386 | $(obj) is a relative path which points to the directory | |
387 | where the target is saved. Always use $(obj) when | |
388 | referring to generated files. | |
389 | ||
390 | Example: | |
391 | #drivers/scsi/Makefile | |
392 | $(obj)/53c8xx_d.h: $(src)/53c7,8xx.scr $(src)/script_asm.pl | |
393 | $(CPP) -DCHIP=810 - < $< | ... $(src)/script_asm.pl | |
394 | ||
395 | This is a special rule, following the normal syntax | |
396 | required by make. | |
397 | The target file depends on two prerequisite files. References | |
398 | to the target file are prefixed with $(obj), references | |
399 | to prerequisites are referenced with $(src) (because they are not | |
400 | generated files). | |
401 | ||
5410ecc0 MF |
402 | $(kecho) |
403 | echoing information to user in a rule is often a good practice | |
404 | but when execution "make -s" one does not expect to see any output | |
405 | except for warnings/errors. | |
406 | To support this kbuild define $(kecho) which will echo out the | |
407 | text following $(kecho) to stdout except if "make -s" is used. | |
408 | ||
409 | Example: | |
410 | #arch/blackfin/boot/Makefile | |
411 | $(obj)/vmImage: $(obj)/vmlinux.gz | |
412 | $(call if_changed,uimage) | |
413 | @$(kecho) 'Kernel: $@ is ready' | |
414 | ||
415 | ||
20a468b5 SR |
416 | --- 3.11 $(CC) support functions |
417 | ||
a07f6033 | 418 | The kernel may be built with several different versions of |
20a468b5 SR |
419 | $(CC), each supporting a unique set of features and options. |
420 | kbuild provide basic support to check for valid options for $(CC). | |
e95be9a5 | 421 | $(CC) is usually the gcc compiler, but other alternatives are |
20a468b5 SR |
422 | available. |
423 | ||
424 | as-option | |
a07f6033 JE |
425 | as-option is used to check if $(CC) -- when used to compile |
426 | assembler (*.S) files -- supports the given option. An optional | |
427 | second option may be specified if the first option is not supported. | |
20a468b5 SR |
428 | |
429 | Example: | |
430 | #arch/sh/Makefile | |
431 | cflags-y += $(call as-option,-Wa$(comma)-isa=$(isa-y),) | |
432 | ||
a07f6033 | 433 | In the above example, cflags-y will be assigned the option |
20a468b5 SR |
434 | -Wa$(comma)-isa=$(isa-y) if it is supported by $(CC). |
435 | The second argument is optional, and if supplied will be used | |
436 | if first argument is not supported. | |
437 | ||
f86fd306 SR |
438 | cc-ldoption |
439 | cc-ldoption is used to check if $(CC) when used to link object files | |
0b0bf7a3 RM |
440 | supports the given option. An optional second option may be |
441 | specified if first option are not supported. | |
442 | ||
443 | Example: | |
25eb650a | 444 | #arch/x86/kernel/Makefile |
f86fd306 | 445 | vsyscall-flags += $(call cc-ldoption, -Wl$(comma)--hash-style=sysv) |
0b0bf7a3 | 446 | |
5c811e59 | 447 | In the above example, vsyscall-flags will be assigned the option |
0b0bf7a3 RM |
448 | -Wl$(comma)--hash-style=sysv if it is supported by $(CC). |
449 | The second argument is optional, and if supplied will be used | |
450 | if first argument is not supported. | |
451 | ||
e2414910 AK |
452 | as-instr |
453 | as-instr checks if the assembler reports a specific instruction | |
454 | and then outputs either option1 or option2 | |
455 | C escapes are supported in the test instruction | |
222d394d | 456 | Note: as-instr-option uses KBUILD_AFLAGS for $(AS) options |
e2414910 | 457 | |
20a468b5 | 458 | cc-option |
a07f6033 | 459 | cc-option is used to check if $(CC) supports a given option, and not |
20a468b5 SR |
460 | supported to use an optional second option. |
461 | ||
462 | Example: | |
25eb650a | 463 | #arch/x86/Makefile |
20a468b5 SR |
464 | cflags-y += $(call cc-option,-march=pentium-mmx,-march=i586) |
465 | ||
5c811e59 | 466 | In the above example, cflags-y will be assigned the option |
a07f6033 JE |
467 | -march=pentium-mmx if supported by $(CC), otherwise -march=i586. |
468 | The second argument to cc-option is optional, and if omitted, | |
20a468b5 | 469 | cflags-y will be assigned no value if first option is not supported. |
a0f97e06 | 470 | Note: cc-option uses KBUILD_CFLAGS for $(CC) options |
20a468b5 SR |
471 | |
472 | cc-option-yn | |
39e6e9cf | 473 | cc-option-yn is used to check if gcc supports a given option |
20a468b5 SR |
474 | and return 'y' if supported, otherwise 'n'. |
475 | ||
476 | Example: | |
477 | #arch/ppc/Makefile | |
478 | biarch := $(call cc-option-yn, -m32) | |
479 | aflags-$(biarch) += -a32 | |
480 | cflags-$(biarch) += -m32 | |
39e6e9cf | 481 | |
a07f6033 JE |
482 | In the above example, $(biarch) is set to y if $(CC) supports the -m32 |
483 | option. When $(biarch) equals 'y', the expanded variables $(aflags-y) | |
484 | and $(cflags-y) will be assigned the values -a32 and -m32, | |
485 | respectively. | |
a0f97e06 | 486 | Note: cc-option-yn uses KBUILD_CFLAGS for $(CC) options |
20a468b5 SR |
487 | |
488 | cc-option-align | |
a07f6033 JE |
489 | gcc versions >= 3.0 changed the type of options used to specify |
490 | alignment of functions, loops etc. $(cc-option-align), when used | |
491 | as prefix to the align options, will select the right prefix: | |
20a468b5 SR |
492 | gcc < 3.00 |
493 | cc-option-align = -malign | |
494 | gcc >= 3.00 | |
495 | cc-option-align = -falign | |
39e6e9cf | 496 | |
20a468b5 | 497 | Example: |
a0f97e06 | 498 | KBUILD_CFLAGS += $(cc-option-align)-functions=4 |
20a468b5 | 499 | |
a07f6033 JE |
500 | In the above example, the option -falign-functions=4 is used for |
501 | gcc >= 3.00. For gcc < 3.00, -malign-functions=4 is used. | |
a0f97e06 | 502 | Note: cc-option-align uses KBUILD_CFLAGS for $(CC) options |
39e6e9cf | 503 | |
8417da6f MM |
504 | cc-disable-warning |
505 | cc-disable-warning checks if gcc supports a given warning and returns | |
506 | the commandline switch to disable it. This special function is needed, | |
507 | because gcc 4.4 and later accept any unknown -Wno-* option and only | |
508 | warn about it if there is another warning in the source file. | |
509 | ||
510 | Example: | |
511 | KBUILD_CFLAGS += $(call cc-disable-warning, unused-but-set-variable) | |
512 | ||
513 | In the above example, -Wno-unused-but-set-variable will be added to | |
514 | KBUILD_CFLAGS only if gcc really accepts it. | |
515 | ||
20a468b5 | 516 | cc-version |
a07f6033 | 517 | cc-version returns a numerical version of the $(CC) compiler version. |
20a468b5 SR |
518 | The format is <major><minor> where both are two digits. So for example |
519 | gcc 3.41 would return 0341. | |
520 | cc-version is useful when a specific $(CC) version is faulty in one | |
a07f6033 | 521 | area, for example -mregparm=3 was broken in some gcc versions |
20a468b5 SR |
522 | even though the option was accepted by gcc. |
523 | ||
524 | Example: | |
25eb650a | 525 | #arch/x86/Makefile |
20a468b5 SR |
526 | cflags-y += $(shell \ |
527 | if [ $(call cc-version) -ge 0300 ] ; then \ | |
528 | echo "-mregparm=3"; fi ;) | |
529 | ||
a07f6033 | 530 | In the above example, -mregparm=3 is only used for gcc version greater |
20a468b5 SR |
531 | than or equal to gcc 3.0. |
532 | ||
533 | cc-ifversion | |
a07f6033 | 534 | cc-ifversion tests the version of $(CC) and equals last argument if |
20a468b5 SR |
535 | version expression is true. |
536 | ||
537 | Example: | |
538 | #fs/reiserfs/Makefile | |
f77bf014 | 539 | ccflags-y := $(call cc-ifversion, -lt, 0402, -O1) |
20a468b5 | 540 | |
f77bf014 | 541 | In this example, ccflags-y will be assigned the value -O1 if the |
20a468b5 | 542 | $(CC) version is less than 4.2. |
39e6e9cf | 543 | cc-ifversion takes all the shell operators: |
20a468b5 SR |
544 | -eq, -ne, -lt, -le, -gt, and -ge |
545 | The third parameter may be a text as in this example, but it may also | |
546 | be an expanded variable or a macro. | |
547 | ||
7015030f SR |
548 | cc-fullversion |
549 | cc-fullversion is useful when the exact version of gcc is needed. | |
550 | One typical use-case is when a specific GCC version is broken. | |
551 | cc-fullversion points out a more specific version than cc-version does. | |
552 | ||
553 | Example: | |
554 | #arch/powerpc/Makefile | |
555 | $(Q)if test "$(call cc-fullversion)" = "040200" ; then \ | |
556 | echo -n '*** GCC-4.2.0 cannot compile the 64-bit powerpc ' ; \ | |
557 | false ; \ | |
558 | fi | |
559 | ||
560 | In this example for a specific GCC version the build will error out explaining | |
561 | to the user why it stops. | |
1da177e4 | 562 | |
910b4046 | 563 | cc-cross-prefix |
631bcfbb | 564 | cc-cross-prefix is used to check if there exists a $(CC) in path with |
910b4046 SR |
565 | one of the listed prefixes. The first prefix where there exist a |
566 | prefix$(CC) in the PATH is returned - and if no prefix$(CC) is found | |
567 | then nothing is returned. | |
568 | Additional prefixes are separated by a single space in the | |
569 | call of cc-cross-prefix. | |
631bcfbb GU |
570 | This functionality is useful for architecture Makefiles that try |
571 | to set CROSS_COMPILE to well-known values but may have several | |
910b4046 | 572 | values to select between. |
631bcfbb GU |
573 | It is recommended only to try to set CROSS_COMPILE if it is a cross |
574 | build (host arch is different from target arch). And if CROSS_COMPILE | |
910b4046 SR |
575 | is already set then leave it with the old value. |
576 | ||
577 | Example: | |
578 | #arch/m68k/Makefile | |
579 | ifneq ($(SUBARCH),$(ARCH)) | |
580 | ifeq ($(CROSS_COMPILE),) | |
581 | CROSS_COMPILE := $(call cc-cross-prefix, m68k-linux-gnu-) | |
582 | endif | |
583 | endif | |
584 | ||
691ef3e7 SR |
585 | --- 3.12 $(LD) support functions |
586 | ||
587 | ld-option | |
588 | ld-option is used to check if $(LD) supports the supplied option. | |
589 | ld-option takes two options as arguments. | |
590 | The second argument is an optional option that can be used if the | |
591 | first option is not supported by $(LD). | |
592 | ||
593 | Example: | |
594 | #Makefile | |
595 | LDFLAGS_vmlinux += $(call really-ld-option, -X) | |
596 | ||
597 | ||
1da177e4 LT |
598 | === 4 Host Program support |
599 | ||
600 | Kbuild supports building executables on the host for use during the | |
601 | compilation stage. | |
602 | Two steps are required in order to use a host executable. | |
603 | ||
604 | The first step is to tell kbuild that a host program exists. This is | |
605 | done utilising the variable hostprogs-y. | |
606 | ||
607 | The second step is to add an explicit dependency to the executable. | |
39e6e9cf | 608 | This can be done in two ways. Either add the dependency in a rule, |
1da177e4 LT |
609 | or utilise the variable $(always). |
610 | Both possibilities are described in the following. | |
611 | ||
612 | --- 4.1 Simple Host Program | |
613 | ||
614 | In some cases there is a need to compile and run a program on the | |
615 | computer where the build is running. | |
616 | The following line tells kbuild that the program bin2hex shall be | |
617 | built on the build host. | |
618 | ||
619 | Example: | |
620 | hostprogs-y := bin2hex | |
621 | ||
622 | Kbuild assumes in the above example that bin2hex is made from a single | |
623 | c-source file named bin2hex.c located in the same directory as | |
624 | the Makefile. | |
39e6e9cf | 625 | |
1da177e4 LT |
626 | --- 4.2 Composite Host Programs |
627 | ||
628 | Host programs can be made up based on composite objects. | |
629 | The syntax used to define composite objects for host programs is | |
630 | similar to the syntax used for kernel objects. | |
5d3f083d | 631 | $(<executable>-objs) lists all objects used to link the final |
1da177e4 LT |
632 | executable. |
633 | ||
634 | Example: | |
635 | #scripts/lxdialog/Makefile | |
39e6e9cf | 636 | hostprogs-y := lxdialog |
1da177e4 LT |
637 | lxdialog-objs := checklist.o lxdialog.o |
638 | ||
639 | Objects with extension .o are compiled from the corresponding .c | |
a07f6033 | 640 | files. In the above example, checklist.c is compiled to checklist.o |
1da177e4 | 641 | and lxdialog.c is compiled to lxdialog.o. |
a07f6033 | 642 | Finally, the two .o files are linked to the executable, lxdialog. |
1da177e4 LT |
643 | Note: The syntax <executable>-y is not permitted for host-programs. |
644 | ||
39e6e9cf BH |
645 | --- 4.3 Defining shared libraries |
646 | ||
1da177e4 LT |
647 | Objects with extension .so are considered shared libraries, and |
648 | will be compiled as position independent objects. | |
649 | Kbuild provides support for shared libraries, but the usage | |
650 | shall be restricted. | |
651 | In the following example the libkconfig.so shared library is used | |
652 | to link the executable conf. | |
653 | ||
654 | Example: | |
655 | #scripts/kconfig/Makefile | |
656 | hostprogs-y := conf | |
657 | conf-objs := conf.o libkconfig.so | |
658 | libkconfig-objs := expr.o type.o | |
39e6e9cf | 659 | |
1da177e4 LT |
660 | Shared libraries always require a corresponding -objs line, and |
661 | in the example above the shared library libkconfig is composed by | |
662 | the two objects expr.o and type.o. | |
663 | expr.o and type.o will be built as position independent code and | |
664 | linked as a shared library libkconfig.so. C++ is not supported for | |
665 | shared libraries. | |
666 | ||
667 | --- 4.4 Using C++ for host programs | |
668 | ||
669 | kbuild offers support for host programs written in C++. This was | |
670 | introduced solely to support kconfig, and is not recommended | |
671 | for general use. | |
672 | ||
673 | Example: | |
674 | #scripts/kconfig/Makefile | |
675 | hostprogs-y := qconf | |
676 | qconf-cxxobjs := qconf.o | |
677 | ||
678 | In the example above the executable is composed of the C++ file | |
679 | qconf.cc - identified by $(qconf-cxxobjs). | |
39e6e9cf | 680 | |
1da177e4 LT |
681 | If qconf is composed by a mixture of .c and .cc files, then an |
682 | additional line can be used to identify this. | |
683 | ||
684 | Example: | |
685 | #scripts/kconfig/Makefile | |
686 | hostprogs-y := qconf | |
687 | qconf-cxxobjs := qconf.o | |
688 | qconf-objs := check.o | |
39e6e9cf | 689 | |
1da177e4 LT |
690 | --- 4.5 Controlling compiler options for host programs |
691 | ||
692 | When compiling host programs, it is possible to set specific flags. | |
693 | The programs will always be compiled utilising $(HOSTCC) passed | |
694 | the options specified in $(HOSTCFLAGS). | |
695 | To set flags that will take effect for all host programs created | |
a07f6033 | 696 | in that Makefile, use the variable HOST_EXTRACFLAGS. |
1da177e4 LT |
697 | |
698 | Example: | |
699 | #scripts/lxdialog/Makefile | |
700 | HOST_EXTRACFLAGS += -I/usr/include/ncurses | |
39e6e9cf | 701 | |
1da177e4 LT |
702 | To set specific flags for a single file the following construction |
703 | is used: | |
704 | ||
705 | Example: | |
706 | #arch/ppc64/boot/Makefile | |
707 | HOSTCFLAGS_piggyback.o := -DKERNELBASE=$(KERNELBASE) | |
39e6e9cf | 708 | |
1da177e4 | 709 | It is also possible to specify additional options to the linker. |
39e6e9cf | 710 | |
1da177e4 LT |
711 | Example: |
712 | #scripts/kconfig/Makefile | |
713 | HOSTLOADLIBES_qconf := -L$(QTDIR)/lib | |
714 | ||
a07f6033 JE |
715 | When linking qconf, it will be passed the extra option |
716 | "-L$(QTDIR)/lib". | |
39e6e9cf | 717 | |
1da177e4 LT |
718 | --- 4.6 When host programs are actually built |
719 | ||
720 | Kbuild will only build host-programs when they are referenced | |
721 | as a prerequisite. | |
722 | This is possible in two ways: | |
723 | ||
724 | (1) List the prerequisite explicitly in a special rule. | |
725 | ||
726 | Example: | |
727 | #drivers/pci/Makefile | |
728 | hostprogs-y := gen-devlist | |
729 | $(obj)/devlist.h: $(src)/pci.ids $(obj)/gen-devlist | |
730 | ( cd $(obj); ./gen-devlist ) < $< | |
731 | ||
39e6e9cf | 732 | The target $(obj)/devlist.h will not be built before |
1da177e4 LT |
733 | $(obj)/gen-devlist is updated. Note that references to |
734 | the host programs in special rules must be prefixed with $(obj). | |
735 | ||
736 | (2) Use $(always) | |
737 | When there is no suitable special rule, and the host program | |
738 | shall be built when a makefile is entered, the $(always) | |
739 | variable shall be used. | |
740 | ||
741 | Example: | |
742 | #scripts/lxdialog/Makefile | |
743 | hostprogs-y := lxdialog | |
744 | always := $(hostprogs-y) | |
745 | ||
746 | This will tell kbuild to build lxdialog even if not referenced in | |
747 | any rule. | |
748 | ||
749 | --- 4.7 Using hostprogs-$(CONFIG_FOO) | |
750 | ||
39e6e9cf | 751 | A typical pattern in a Kbuild file looks like this: |
1da177e4 LT |
752 | |
753 | Example: | |
754 | #scripts/Makefile | |
755 | hostprogs-$(CONFIG_KALLSYMS) += kallsyms | |
756 | ||
757 | Kbuild knows about both 'y' for built-in and 'm' for module. | |
758 | So if a config symbol evaluate to 'm', kbuild will still build | |
a07f6033 JE |
759 | the binary. In other words, Kbuild handles hostprogs-m exactly |
760 | like hostprogs-y. But only hostprogs-y is recommended to be used | |
761 | when no CONFIG symbols are involved. | |
1da177e4 LT |
762 | |
763 | === 5 Kbuild clean infrastructure | |
764 | ||
a07f6033 | 765 | "make clean" deletes most generated files in the obj tree where the kernel |
1da177e4 LT |
766 | is compiled. This includes generated files such as host programs. |
767 | Kbuild knows targets listed in $(hostprogs-y), $(hostprogs-m), $(always), | |
768 | $(extra-y) and $(targets). They are all deleted during "make clean". | |
769 | Files matching the patterns "*.[oas]", "*.ko", plus some additional files | |
770 | generated by kbuild are deleted all over the kernel src tree when | |
771 | "make clean" is executed. | |
772 | ||
773 | Additional files can be specified in kbuild makefiles by use of $(clean-files). | |
774 | ||
775 | Example: | |
776 | #drivers/pci/Makefile | |
777 | clean-files := devlist.h classlist.h | |
778 | ||
779 | When executing "make clean", the two files "devlist.h classlist.h" will | |
780 | be deleted. Kbuild will assume files to be in same relative directory as the | |
781 | Makefile except if an absolute path is specified (path starting with '/'). | |
782 | ||
39e6e9cf BH |
783 | To delete a directory hierarchy use: |
784 | ||
1da177e4 LT |
785 | Example: |
786 | #scripts/package/Makefile | |
787 | clean-dirs := $(objtree)/debian/ | |
788 | ||
789 | This will delete the directory debian, including all subdirectories. | |
790 | Kbuild will assume the directories to be in the same relative path as the | |
791 | Makefile if no absolute path is specified (path does not start with '/'). | |
792 | ||
ef8ff89b MM |
793 | To exclude certain files from make clean, use the $(no-clean-files) variable. |
794 | This is only a special case used in the top level Kbuild file: | |
795 | ||
796 | Example: | |
797 | #Kbuild | |
798 | no-clean-files := $(bounds-file) $(offsets-file) | |
799 | ||
1da177e4 LT |
800 | Usually kbuild descends down in subdirectories due to "obj-* := dir/", |
801 | but in the architecture makefiles where the kbuild infrastructure | |
802 | is not sufficient this sometimes needs to be explicit. | |
803 | ||
804 | Example: | |
25eb650a | 805 | #arch/x86/boot/Makefile |
1da177e4 LT |
806 | subdir- := compressed/ |
807 | ||
808 | The above assignment instructs kbuild to descend down in the | |
809 | directory compressed/ when "make clean" is executed. | |
810 | ||
811 | To support the clean infrastructure in the Makefiles that builds the | |
812 | final bootimage there is an optional target named archclean: | |
813 | ||
814 | Example: | |
25eb650a | 815 | #arch/x86/Makefile |
1da177e4 | 816 | archclean: |
25eb650a | 817 | $(Q)$(MAKE) $(clean)=arch/x86/boot |
1da177e4 | 818 | |
25eb650a WG |
819 | When "make clean" is executed, make will descend down in arch/x86/boot, |
820 | and clean as usual. The Makefile located in arch/x86/boot/ may use | |
1da177e4 LT |
821 | the subdir- trick to descend further down. |
822 | ||
823 | Note 1: arch/$(ARCH)/Makefile cannot use "subdir-", because that file is | |
824 | included in the top level makefile, and the kbuild infrastructure | |
825 | is not operational at that point. | |
826 | ||
827 | Note 2: All directories listed in core-y, libs-y, drivers-y and net-y will | |
828 | be visited during "make clean". | |
829 | ||
830 | === 6 Architecture Makefiles | |
831 | ||
832 | The top level Makefile sets up the environment and does the preparation, | |
833 | before starting to descend down in the individual directories. | |
a07f6033 JE |
834 | The top level makefile contains the generic part, whereas |
835 | arch/$(ARCH)/Makefile contains what is required to set up kbuild | |
836 | for said architecture. | |
837 | To do so, arch/$(ARCH)/Makefile sets up a number of variables and defines | |
1da177e4 LT |
838 | a few targets. |
839 | ||
a07f6033 JE |
840 | When kbuild executes, the following steps are followed (roughly): |
841 | 1) Configuration of the kernel => produce .config | |
1da177e4 LT |
842 | 2) Store kernel version in include/linux/version.h |
843 | 3) Symlink include/asm to include/asm-$(ARCH) | |
844 | 4) Updating all other prerequisites to the target prepare: | |
845 | - Additional prerequisites are specified in arch/$(ARCH)/Makefile | |
846 | 5) Recursively descend down in all directories listed in | |
847 | init-* core* drivers-* net-* libs-* and build all targets. | |
a07f6033 | 848 | - The values of the above variables are expanded in arch/$(ARCH)/Makefile. |
39e6e9cf | 849 | 6) All object files are then linked and the resulting file vmlinux is |
a07f6033 | 850 | located at the root of the obj tree. |
1da177e4 LT |
851 | The very first objects linked are listed in head-y, assigned by |
852 | arch/$(ARCH)/Makefile. | |
5c811e59 | 853 | 7) Finally, the architecture-specific part does any required post processing |
1da177e4 LT |
854 | and builds the final bootimage. |
855 | - This includes building boot records | |
5c811e59 | 856 | - Preparing initrd images and the like |
1da177e4 LT |
857 | |
858 | ||
859 | --- 6.1 Set variables to tweak the build to the architecture | |
860 | ||
861 | LDFLAGS Generic $(LD) options | |
862 | ||
863 | Flags used for all invocations of the linker. | |
864 | Often specifying the emulation is sufficient. | |
865 | ||
866 | Example: | |
867 | #arch/s390/Makefile | |
868 | LDFLAGS := -m elf_s390 | |
f77bf014 | 869 | Note: ldflags-y can be used to further customise |
a9af3305 | 870 | the flags used. See chapter 3.7. |
39e6e9cf | 871 | |
1da177e4 LT |
872 | LDFLAGS_MODULE Options for $(LD) when linking modules |
873 | ||
874 | LDFLAGS_MODULE is used to set specific flags for $(LD) when | |
875 | linking the .ko files used for modules. | |
876 | Default is "-r", for relocatable output. | |
877 | ||
878 | LDFLAGS_vmlinux Options for $(LD) when linking vmlinux | |
879 | ||
880 | LDFLAGS_vmlinux is used to specify additional flags to pass to | |
a07f6033 | 881 | the linker when linking the final vmlinux image. |
1da177e4 LT |
882 | LDFLAGS_vmlinux uses the LDFLAGS_$@ support. |
883 | ||
884 | Example: | |
25eb650a | 885 | #arch/x86/Makefile |
1da177e4 LT |
886 | LDFLAGS_vmlinux := -e stext |
887 | ||
888 | OBJCOPYFLAGS objcopy flags | |
889 | ||
890 | When $(call if_changed,objcopy) is used to translate a .o file, | |
a07f6033 | 891 | the flags specified in OBJCOPYFLAGS will be used. |
1da177e4 LT |
892 | $(call if_changed,objcopy) is often used to generate raw binaries on |
893 | vmlinux. | |
894 | ||
895 | Example: | |
896 | #arch/s390/Makefile | |
897 | OBJCOPYFLAGS := -O binary | |
898 | ||
899 | #arch/s390/boot/Makefile | |
900 | $(obj)/image: vmlinux FORCE | |
901 | $(call if_changed,objcopy) | |
902 | ||
a07f6033 | 903 | In this example, the binary $(obj)/image is a binary version of |
1da177e4 LT |
904 | vmlinux. The usage of $(call if_changed,xxx) will be described later. |
905 | ||
222d394d | 906 | KBUILD_AFLAGS $(AS) assembler flags |
1da177e4 LT |
907 | |
908 | Default value - see top level Makefile | |
909 | Append or modify as required per architecture. | |
910 | ||
911 | Example: | |
912 | #arch/sparc64/Makefile | |
222d394d | 913 | KBUILD_AFLAGS += -m64 -mcpu=ultrasparc |
1da177e4 | 914 | |
a0f97e06 | 915 | KBUILD_CFLAGS $(CC) compiler flags |
1da177e4 LT |
916 | |
917 | Default value - see top level Makefile | |
918 | Append or modify as required per architecture. | |
919 | ||
a0f97e06 | 920 | Often, the KBUILD_CFLAGS variable depends on the configuration. |
1da177e4 LT |
921 | |
922 | Example: | |
25eb650a | 923 | #arch/x86/Makefile |
1da177e4 | 924 | cflags-$(CONFIG_M386) += -march=i386 |
a0f97e06 | 925 | KBUILD_CFLAGS += $(cflags-y) |
1da177e4 LT |
926 | |
927 | Many arch Makefiles dynamically run the target C compiler to | |
928 | probe supported options: | |
929 | ||
25eb650a | 930 | #arch/x86/Makefile |
1da177e4 LT |
931 | |
932 | ... | |
933 | cflags-$(CONFIG_MPENTIUMII) += $(call cc-option,\ | |
934 | -march=pentium2,-march=i686) | |
935 | ... | |
936 | # Disable unit-at-a-time mode ... | |
a0f97e06 | 937 | KBUILD_CFLAGS += $(call cc-option,-fno-unit-at-a-time) |
1da177e4 LT |
938 | ... |
939 | ||
940 | ||
a07f6033 | 941 | The first example utilises the trick that a config option expands |
1da177e4 LT |
942 | to 'y' when selected. |
943 | ||
80c00ba9 | 944 | KBUILD_AFLAGS_KERNEL $(AS) options specific for built-in |
1da177e4 | 945 | |
80c00ba9 | 946 | $(KBUILD_AFLAGS_KERNEL) contains extra C compiler flags used to compile |
1da177e4 LT |
947 | resident kernel code. |
948 | ||
6588169d | 949 | KBUILD_AFLAGS_MODULE Options for $(AS) when building modules |
1da177e4 | 950 | |
6588169d SR |
951 | $(KBUILD_AFLAGS_MODULE) is used to add arch specific options that |
952 | are used for $(AS). | |
953 | From commandline AFLAGS_MODULE shall be used (see kbuild.txt). | |
1da177e4 | 954 | |
80c00ba9 SR |
955 | KBUILD_CFLAGS_KERNEL $(CC) options specific for built-in |
956 | ||
957 | $(KBUILD_CFLAGS_KERNEL) contains extra C compiler flags used to compile | |
958 | resident kernel code. | |
959 | ||
6588169d SR |
960 | KBUILD_CFLAGS_MODULE Options for $(CC) when building modules |
961 | ||
962 | $(KBUILD_CFLAGS_MODULE) is used to add arch specific options that | |
963 | are used for $(CC). | |
964 | From commandline CFLAGS_MODULE shall be used (see kbuild.txt). | |
965 | ||
966 | KBUILD_LDFLAGS_MODULE Options for $(LD) when linking modules | |
967 | ||
968 | $(KBUILD_LDFLAGS_MODULE) is used to add arch specific options | |
969 | used when linking modules. This is often a linker script. | |
970 | From commandline LDFLAGS_MODULE shall be used (see kbuild.txt). | |
39e6e9cf | 971 | |
40df759e MM |
972 | KBUILD_ARFLAGS Options for $(AR) when creating archives |
973 | ||
974 | $(KBUILD_ARFLAGS) set by the top level Makefile to "D" (deterministic | |
975 | mode) if this option is supported by $(AR). | |
976 | ||
5bb78269 | 977 | --- 6.2 Add prerequisites to archprepare: |
1da177e4 | 978 | |
a07f6033 | 979 | The archprepare: rule is used to list prerequisites that need to be |
1da177e4 | 980 | built before starting to descend down in the subdirectories. |
a07f6033 | 981 | This is usually used for header files containing assembler constants. |
1da177e4 LT |
982 | |
983 | Example: | |
5bb78269 SR |
984 | #arch/arm/Makefile |
985 | archprepare: maketools | |
1da177e4 | 986 | |
a07f6033 | 987 | In this example, the file target maketools will be processed |
5bb78269 | 988 | before descending down in the subdirectories. |
1da177e4 LT |
989 | See also chapter XXX-TODO that describe how kbuild supports |
990 | generating offset header files. | |
991 | ||
992 | ||
993 | --- 6.3 List directories to visit when descending | |
994 | ||
995 | An arch Makefile cooperates with the top Makefile to define variables | |
996 | which specify how to build the vmlinux file. Note that there is no | |
997 | corresponding arch-specific section for modules; the module-building | |
998 | machinery is all architecture-independent. | |
999 | ||
39e6e9cf | 1000 | |
1da177e4 LT |
1001 | head-y, init-y, core-y, libs-y, drivers-y, net-y |
1002 | ||
a07f6033 JE |
1003 | $(head-y) lists objects to be linked first in vmlinux. |
1004 | $(libs-y) lists directories where a lib.a archive can be located. | |
5c811e59 | 1005 | The rest list directories where a built-in.o object file can be |
a07f6033 | 1006 | located. |
1da177e4 LT |
1007 | |
1008 | $(init-y) objects will be located after $(head-y). | |
1009 | Then the rest follows in this order: | |
1010 | $(core-y), $(libs-y), $(drivers-y) and $(net-y). | |
1011 | ||
a07f6033 | 1012 | The top level Makefile defines values for all generic directories, |
5c811e59 | 1013 | and arch/$(ARCH)/Makefile only adds architecture-specific directories. |
1da177e4 LT |
1014 | |
1015 | Example: | |
1016 | #arch/sparc64/Makefile | |
1017 | core-y += arch/sparc64/kernel/ | |
1018 | libs-y += arch/sparc64/prom/ arch/sparc64/lib/ | |
1019 | drivers-$(CONFIG_OPROFILE) += arch/sparc64/oprofile/ | |
1020 | ||
1021 | ||
5c811e59 | 1022 | --- 6.4 Architecture-specific boot images |
1da177e4 LT |
1023 | |
1024 | An arch Makefile specifies goals that take the vmlinux file, compress | |
1025 | it, wrap it in bootstrapping code, and copy the resulting files | |
1026 | somewhere. This includes various kinds of installation commands. | |
1027 | The actual goals are not standardized across architectures. | |
1028 | ||
1029 | It is common to locate any additional processing in a boot/ | |
1030 | directory below arch/$(ARCH)/. | |
1031 | ||
1032 | Kbuild does not provide any smart way to support building a | |
1033 | target specified in boot/. Therefore arch/$(ARCH)/Makefile shall | |
1034 | call make manually to build a target in boot/. | |
1035 | ||
1036 | The recommended approach is to include shortcuts in | |
1037 | arch/$(ARCH)/Makefile, and use the full path when calling down | |
1038 | into the arch/$(ARCH)/boot/Makefile. | |
1039 | ||
1040 | Example: | |
25eb650a WG |
1041 | #arch/x86/Makefile |
1042 | boot := arch/x86/boot | |
1da177e4 LT |
1043 | bzImage: vmlinux |
1044 | $(Q)$(MAKE) $(build)=$(boot) $(boot)/$@ | |
1045 | ||
1046 | "$(Q)$(MAKE) $(build)=<dir>" is the recommended way to invoke | |
1047 | make in a subdirectory. | |
1048 | ||
5c811e59 | 1049 | There are no rules for naming architecture-specific targets, |
1da177e4 | 1050 | but executing "make help" will list all relevant targets. |
a07f6033 | 1051 | To support this, $(archhelp) must be defined. |
1da177e4 LT |
1052 | |
1053 | Example: | |
25eb650a | 1054 | #arch/x86/Makefile |
1da177e4 LT |
1055 | define archhelp |
1056 | echo '* bzImage - Image (arch/$(ARCH)/boot/bzImage)' | |
39e6e9cf | 1057 | endif |
1da177e4 LT |
1058 | |
1059 | When make is executed without arguments, the first goal encountered | |
1060 | will be built. In the top level Makefile the first goal present | |
1061 | is all:. | |
a07f6033 JE |
1062 | An architecture shall always, per default, build a bootable image. |
1063 | In "make help", the default goal is highlighted with a '*'. | |
1da177e4 LT |
1064 | Add a new prerequisite to all: to select a default goal different |
1065 | from vmlinux. | |
1066 | ||
1067 | Example: | |
25eb650a | 1068 | #arch/x86/Makefile |
39e6e9cf | 1069 | all: bzImage |
1da177e4 LT |
1070 | |
1071 | When "make" is executed without arguments, bzImage will be built. | |
1072 | ||
1073 | --- 6.5 Building non-kbuild targets | |
1074 | ||
1075 | extra-y | |
1076 | ||
1077 | extra-y specify additional targets created in the current | |
1078 | directory, in addition to any targets specified by obj-*. | |
1079 | ||
1080 | Listing all targets in extra-y is required for two purposes: | |
1081 | 1) Enable kbuild to check changes in command lines | |
1082 | - When $(call if_changed,xxx) is used | |
1083 | 2) kbuild knows what files to delete during "make clean" | |
1084 | ||
1085 | Example: | |
25eb650a | 1086 | #arch/x86/kernel/Makefile |
1da177e4 LT |
1087 | extra-y := head.o init_task.o |
1088 | ||
a07f6033 | 1089 | In this example, extra-y is used to list object files that |
1da177e4 LT |
1090 | shall be built, but shall not be linked as part of built-in.o. |
1091 | ||
39e6e9cf | 1092 | |
1da177e4 LT |
1093 | --- 6.6 Commands useful for building a boot image |
1094 | ||
1095 | Kbuild provides a few macros that are useful when building a | |
1096 | boot image. | |
1097 | ||
1098 | if_changed | |
1099 | ||
1100 | if_changed is the infrastructure used for the following commands. | |
1101 | ||
1102 | Usage: | |
1103 | target: source(s) FORCE | |
1104 | $(call if_changed,ld/objcopy/gzip) | |
1105 | ||
a07f6033 | 1106 | When the rule is evaluated, it is checked to see if any files |
5c811e59 | 1107 | need an update, or the command line has changed since the last |
1da177e4 LT |
1108 | invocation. The latter will force a rebuild if any options |
1109 | to the executable have changed. | |
1110 | Any target that utilises if_changed must be listed in $(targets), | |
1111 | otherwise the command line check will fail, and the target will | |
1112 | always be built. | |
1113 | Assignments to $(targets) are without $(obj)/ prefix. | |
1114 | if_changed may be used in conjunction with custom commands as | |
1115 | defined in 6.7 "Custom kbuild commands". | |
49490571 | 1116 | |
1da177e4 | 1117 | Note: It is a typical mistake to forget the FORCE prerequisite. |
49490571 PBG |
1118 | Another common pitfall is that whitespace is sometimes |
1119 | significant; for instance, the below will fail (note the extra space | |
1120 | after the comma): | |
1121 | target: source(s) FORCE | |
1122 | #WRONG!# $(call if_changed, ld/objcopy/gzip) | |
1da177e4 LT |
1123 | |
1124 | ld | |
a07f6033 | 1125 | Link target. Often, LDFLAGS_$@ is used to set specific options to ld. |
39e6e9cf | 1126 | |
1da177e4 LT |
1127 | objcopy |
1128 | Copy binary. Uses OBJCOPYFLAGS usually specified in | |
1129 | arch/$(ARCH)/Makefile. | |
1130 | OBJCOPYFLAGS_$@ may be used to set additional options. | |
1131 | ||
1132 | gzip | |
1133 | Compress target. Use maximum compression to compress target. | |
1134 | ||
1135 | Example: | |
25eb650a | 1136 | #arch/x86/boot/Makefile |
1da177e4 LT |
1137 | LDFLAGS_bootsect := -Ttext 0x0 -s --oformat binary |
1138 | LDFLAGS_setup := -Ttext 0x0 -s --oformat binary -e begtext | |
1139 | ||
1140 | targets += setup setup.o bootsect bootsect.o | |
1141 | $(obj)/setup $(obj)/bootsect: %: %.o FORCE | |
1142 | $(call if_changed,ld) | |
1143 | ||
a07f6033 JE |
1144 | In this example, there are two possible targets, requiring different |
1145 | options to the linker. The linker options are specified using the | |
1da177e4 | 1146 | LDFLAGS_$@ syntax - one for each potential target. |
5d3f083d | 1147 | $(targets) are assigned all potential targets, by which kbuild knows |
1da177e4 LT |
1148 | the targets and will: |
1149 | 1) check for commandline changes | |
1150 | 2) delete target during make clean | |
1151 | ||
1152 | The ": %: %.o" part of the prerequisite is a shorthand that | |
1153 | free us from listing the setup.o and bootsect.o files. | |
1154 | Note: It is a common mistake to forget the "target :=" assignment, | |
1155 | resulting in the target file being recompiled for no | |
1156 | obvious reason. | |
1157 | ||
aab94339 DB |
1158 | dtc |
1159 | Create flattend device tree blob object suitable for linking | |
1160 | into vmlinux. Device tree blobs linked into vmlinux are placed | |
1161 | in an init section in the image. Platform code *must* copy the | |
1162 | blob to non-init memory prior to calling unflatten_device_tree(). | |
1163 | ||
1164 | Example: | |
1165 | #arch/x86/platform/ce4100/Makefile | |
1166 | clean-files := *dtb.S | |
1167 | ||
1168 | DTC_FLAGS := -p 1024 | |
1169 | obj-y += foo.dtb.o | |
1170 | ||
1171 | $(obj)/%.dtb: $(src)/%.dts | |
1172 | $(call cmd,dtc) | |
1da177e4 LT |
1173 | |
1174 | --- 6.7 Custom kbuild commands | |
1175 | ||
a07f6033 | 1176 | When kbuild is executing with KBUILD_VERBOSE=0, then only a shorthand |
1da177e4 LT |
1177 | of a command is normally displayed. |
1178 | To enable this behaviour for custom commands kbuild requires | |
1179 | two variables to be set: | |
1180 | quiet_cmd_<command> - what shall be echoed | |
1181 | cmd_<command> - the command to execute | |
1182 | ||
1183 | Example: | |
1184 | # | |
1185 | quiet_cmd_image = BUILD $@ | |
1186 | cmd_image = $(obj)/tools/build $(BUILDFLAGS) \ | |
1187 | $(obj)/vmlinux.bin > $@ | |
1188 | ||
1189 | targets += bzImage | |
1190 | $(obj)/bzImage: $(obj)/vmlinux.bin $(obj)/tools/build FORCE | |
1191 | $(call if_changed,image) | |
1192 | @echo 'Kernel: $@ is ready' | |
1193 | ||
a07f6033 | 1194 | When updating the $(obj)/bzImage target, the line |
1da177e4 | 1195 | |
25eb650a | 1196 | BUILD arch/x86/boot/bzImage |
1da177e4 LT |
1197 | |
1198 | will be displayed with "make KBUILD_VERBOSE=0". | |
39e6e9cf | 1199 | |
1da177e4 LT |
1200 | |
1201 | --- 6.8 Preprocessing linker scripts | |
1202 | ||
a07f6033 | 1203 | When the vmlinux image is built, the linker script |
1da177e4 LT |
1204 | arch/$(ARCH)/kernel/vmlinux.lds is used. |
1205 | The script is a preprocessed variant of the file vmlinux.lds.S | |
1206 | located in the same directory. | |
a07f6033 | 1207 | kbuild knows .lds files and includes a rule *lds.S -> *lds. |
39e6e9cf | 1208 | |
1da177e4 | 1209 | Example: |
25eb650a | 1210 | #arch/x86/kernel/Makefile |
1da177e4 | 1211 | always := vmlinux.lds |
39e6e9cf | 1212 | |
1da177e4 LT |
1213 | #Makefile |
1214 | export CPPFLAGS_vmlinux.lds += -P -C -U$(ARCH) | |
39e6e9cf BH |
1215 | |
1216 | The assignment to $(always) is used to tell kbuild to build the | |
a07f6033 JE |
1217 | target vmlinux.lds. |
1218 | The assignment to $(CPPFLAGS_vmlinux.lds) tells kbuild to use the | |
1da177e4 | 1219 | specified options when building the target vmlinux.lds. |
39e6e9cf | 1220 | |
a07f6033 | 1221 | When building the *.lds target, kbuild uses the variables: |
06c5040c | 1222 | KBUILD_CPPFLAGS : Set in top-level Makefile |
f77bf014 | 1223 | cppflags-y : May be set in the kbuild makefile |
1da177e4 LT |
1224 | CPPFLAGS_$(@F) : Target specific flags. |
1225 | Note that the full filename is used in this | |
1226 | assignment. | |
1227 | ||
1228 | The kbuild infrastructure for *lds file are used in several | |
5c811e59 | 1229 | architecture-specific files. |
1da177e4 | 1230 | |
d8ecc5cd SR |
1231 | --- 6.9 Generic header files |
1232 | ||
1233 | The directory include/asm-generic contains the header files | |
1234 | that may be shared between individual architectures. | |
1235 | The recommended approach how to use a generic header file is | |
1236 | to list the file in the Kbuild file. | |
1237 | See "7.4 generic-y" for further info on syntax etc. | |
1238 | ||
c7bb349e SR |
1239 | === 7 Kbuild syntax for exported headers |
1240 | ||
1241 | The kernel include a set of headers that is exported to userspace. | |
c95940f2 | 1242 | Many headers can be exported as-is but other headers require a |
c7bb349e SR |
1243 | minimal pre-processing before they are ready for user-space. |
1244 | The pre-processing does: | |
1245 | - drop kernel specific annotations | |
1246 | - drop include of compiler.h | |
c95940f2 | 1247 | - drop all sections that are kernel internal (guarded by ifdef __KERNEL__) |
c7bb349e | 1248 | |
c95940f2 | 1249 | Each relevant directory contains a file name "Kbuild" which specifies the |
c7bb349e SR |
1250 | headers to be exported. |
1251 | See subsequent chapter for the syntax of the Kbuild file. | |
1252 | ||
1253 | --- 7.1 header-y | |
1254 | ||
1255 | header-y specify header files to be exported. | |
1256 | ||
1257 | Example: | |
1258 | #include/linux/Kbuild | |
1259 | header-y += usb/ | |
1260 | header-y += aio_abi.h | |
1261 | ||
1262 | The convention is to list one file per line and | |
1263 | preferably in alphabetic order. | |
1264 | ||
1265 | header-y also specify which subdirectories to visit. | |
1266 | A subdirectory is identified by a trailing '/' which | |
1267 | can be seen in the example above for the usb subdirectory. | |
1268 | ||
1269 | Subdirectories are visited before their parent directories. | |
1270 | ||
1271 | --- 7.2 objhdr-y | |
1272 | ||
1273 | objhdr-y specifies generated files to be exported. | |
1274 | Generated files are special as they need to be looked | |
1275 | up in another directory when doing 'make O=...' builds. | |
1276 | ||
1277 | Example: | |
1278 | #include/linux/Kbuild | |
1279 | objhdr-y += version.h | |
1280 | ||
1281 | --- 7.3 destination-y | |
1282 | ||
1283 | When an architecture have a set of exported headers that needs to be | |
1284 | exported to a different directory destination-y is used. | |
1285 | destination-y specify the destination directory for all exported | |
1286 | headers in the file where it is present. | |
1287 | ||
1288 | Example: | |
1289 | #arch/xtensa/platforms/s6105/include/platform/Kbuild | |
1290 | destination-y := include/linux | |
1291 | ||
1292 | In the example above all exported headers in the Kbuild file | |
1293 | will be located in the directory "include/linux" when exported. | |
1294 | ||
d8ecc5cd SR |
1295 | --- 7.4 generic-y |
1296 | ||
1297 | If an architecture uses a verbatim copy of a header from | |
1298 | include/asm-generic then this is listed in the file | |
1299 | arch/$(ARCH)/include/asm/Kbuild like this: | |
1300 | ||
1301 | Example: | |
1302 | #arch/x86/include/asm/Kbuild | |
1303 | generic-y += termios.h | |
1304 | generic-y += rtc.h | |
1305 | ||
1306 | During the prepare phase of the build a wrapper include | |
1307 | file is generated in the directory: | |
1308 | ||
1309 | arch/$(ARCH)/include/generated/asm | |
1310 | ||
1311 | When a header is exported where the architecture uses | |
1312 | the generic header a similar wrapper is generated as part | |
1313 | of the set of exported headers in the directory: | |
1314 | ||
1315 | usr/include/asm | |
1316 | ||
1317 | The generated wrapper will in both cases look like the following: | |
1318 | ||
1319 | Example: termios.h | |
1320 | #include <asm-generic/termios.h> | |
c7bb349e | 1321 | |
c7bb349e | 1322 | === 8 Kbuild Variables |
1da177e4 LT |
1323 | |
1324 | The top Makefile exports the following variables: | |
1325 | ||
1326 | VERSION, PATCHLEVEL, SUBLEVEL, EXTRAVERSION | |
1327 | ||
1328 | These variables define the current kernel version. A few arch | |
1329 | Makefiles actually use these values directly; they should use | |
1330 | $(KERNELRELEASE) instead. | |
1331 | ||
1332 | $(VERSION), $(PATCHLEVEL), and $(SUBLEVEL) define the basic | |
1333 | three-part version number, such as "2", "4", and "0". These three | |
1334 | values are always numeric. | |
1335 | ||
1336 | $(EXTRAVERSION) defines an even tinier sublevel for pre-patches | |
1337 | or additional patches. It is usually some non-numeric string | |
1338 | such as "-pre4", and is often blank. | |
1339 | ||
1340 | KERNELRELEASE | |
1341 | ||
1342 | $(KERNELRELEASE) is a single string such as "2.4.0-pre4", suitable | |
1343 | for constructing installation directory names or showing in | |
1344 | version strings. Some arch Makefiles use it for this purpose. | |
1345 | ||
1346 | ARCH | |
1347 | ||
1348 | This variable defines the target architecture, such as "i386", | |
1349 | "arm", or "sparc". Some kbuild Makefiles test $(ARCH) to | |
1350 | determine which files to compile. | |
1351 | ||
1352 | By default, the top Makefile sets $(ARCH) to be the same as the | |
1353 | host system architecture. For a cross build, a user may | |
1354 | override the value of $(ARCH) on the command line: | |
1355 | ||
1356 | make ARCH=m68k ... | |
1357 | ||
1358 | ||
1359 | INSTALL_PATH | |
1360 | ||
1361 | This variable defines a place for the arch Makefiles to install | |
1362 | the resident kernel image and System.map file. | |
5c811e59 | 1363 | Use this for architecture-specific install targets. |
1da177e4 LT |
1364 | |
1365 | INSTALL_MOD_PATH, MODLIB | |
1366 | ||
1367 | $(INSTALL_MOD_PATH) specifies a prefix to $(MODLIB) for module | |
1368 | installation. This variable is not defined in the Makefile but | |
1369 | may be passed in by the user if desired. | |
1370 | ||
1371 | $(MODLIB) specifies the directory for module installation. | |
1372 | The top Makefile defines $(MODLIB) to | |
1373 | $(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE). The user may | |
1374 | override this value on the command line if desired. | |
1375 | ||
ac031f26 TT |
1376 | INSTALL_MOD_STRIP |
1377 | ||
1378 | If this variable is specified, will cause modules to be stripped | |
1379 | after they are installed. If INSTALL_MOD_STRIP is '1', then the | |
1380 | default option --strip-debug will be used. Otherwise, | |
177b241d GE |
1381 | INSTALL_MOD_STRIP value will be used as the option(s) to the strip |
1382 | command. | |
ac031f26 TT |
1383 | |
1384 | ||
c7bb349e | 1385 | === 9 Makefile language |
1da177e4 | 1386 | |
a07f6033 | 1387 | The kernel Makefiles are designed to be run with GNU Make. The Makefiles |
1da177e4 LT |
1388 | use only the documented features of GNU Make, but they do use many |
1389 | GNU extensions. | |
1390 | ||
1391 | GNU Make supports elementary list-processing functions. The kernel | |
1392 | Makefiles use a novel style of list building and manipulation with few | |
1393 | "if" statements. | |
1394 | ||
1395 | GNU Make has two assignment operators, ":=" and "=". ":=" performs | |
1396 | immediate evaluation of the right-hand side and stores an actual string | |
1397 | into the left-hand side. "=" is like a formula definition; it stores the | |
1398 | right-hand side in an unevaluated form and then evaluates this form each | |
1399 | time the left-hand side is used. | |
1400 | ||
1401 | There are some cases where "=" is appropriate. Usually, though, ":=" | |
1402 | is the right choice. | |
1403 | ||
c7bb349e | 1404 | === 10 Credits |
1da177e4 LT |
1405 | |
1406 | Original version made by Michael Elizabeth Chastain, <mailto:mec@shout.net> | |
1407 | Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de> | |
1408 | Updates by Sam Ravnborg <sam@ravnborg.org> | |
a07f6033 | 1409 | Language QA by Jan Engelhardt <jengelh@gmx.de> |
1da177e4 | 1410 | |
c7bb349e | 1411 | === 11 TODO |
1da177e4 | 1412 | |
a07f6033 | 1413 | - Describe how kbuild supports shipped files with _shipped. |
1da177e4 LT |
1414 | - Generating offset header files. |
1415 | - Add more variables to section 7? | |
1416 | ||
39e6e9cf BH |
1417 | |
1418 |