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