1 Linux Kernel Makefiles
2 2000-September-14
3 Michael Elizabeth Chastain, <mec@shout.net>
4
5
6
7 === Table of Contents
8
9 This document describes the Linux kernel Makefiles.
10
11 1 Overview
12 2 Who does what
13 3 Makefile language
14 4 Variables passed down from the top
15 5 The structure of an arch Makefile
16 5.1 Architecture-specific variables
17 5.2 Vmlinux build variables
18 5.3 Post-vmlinux goals
19 5.4 Mandatory arch-specific goals
20 6 The structure of a subdirectory Makefile
21 6.1 Comments
22 6.2 Goal definitions
23 6.3 Adapter section
24 6.4 Rules.make section
25 6.5 Special rules
26 7 Rules.make variables
27 7.1 Subdirectories
28 7.2 Object file goals
29 7.3 Library file goals
30 7.4 Loadable module goals
31 7.5 Multi-part modules
32 7.6 Compilation flags
33 7.7 Miscellaneous variables
34 8 New-style variables
35 8.1 New variables
36 8.2 Converting to old-style
37 9 Compatibility with Linux Kernel 2.2
38 10 Credits
39
40
41 === 1 Overview
42
43 The Makefiles have five parts:
44
45 Makefile: the top Makefile.
46 .config: the kernel configuration file.
47 arch/*/Makefile: the arch Makefiles.
48 Subdirectory Makefiles: there are about 300 of these.
49 Rules.make: the common rules for all subdirectory Makefiles.
50
51 The top Makefile reads the .config file, which comes from the
52 kernel configuration process.
53
54 The top Makefile is responsible for building two major products: vmlinux
55 (the resident kernel image) and modules (any module files). It builds
56 these goals by recursively descending into the subdirectories of the
57 kernel source tree. The list of subdirectories which are visited depends
58 upon the kernel configuration.
59
60 The top Makefile textually includes an arch Makefile with the name
61 arch/$(ARCH)/Makefile. The arch Makefile supplies architecture-specific
62 information to the top Makefile.
63
64 Each subdirectory has a Makefile which carries out the commands passed
65 down from above. The subdirectory Makefile uses information from the
66 .config file to construct various file lists, and then it textually
67 includes the common rules in Rules.make.
68
69 Rules.make defines rules which are common to all the subdirectory
70 Makefiles. It has a public interface in the form of certain variable
71 lists. It then declares rules based on those lists.
72
73
74
75 === 2 Who does what
76
77 People have four different relationships with the kernel Makefiles.
78
79 *Users* are people who build kernels. These people type commands such as
80 "make menuconfig" or "make bzImage". They usually do not read or edit
81 any kernel Makefiles (or any other source files).
82
83 *Normal developers* are people who work on features such as device
84 drivers, file systems, and network protocols. These people need to
85 maintain the subdirectory Makefiles for the subsystem that they are
86 working on. In order to do this effectively, they need some overall
87 knowledge about the kernel Makefiles, plus detailed knowledge about the
88 public interface for Rules.make.
89
90 *Arch developers* are people who work on an entire architecture, such
91 as sparc or ia64. Arch developers need to know about the arch Makefiles
92 as well as subdirectory Makefiles.
93
94 *Kbuild developers* are people who work on the kernel build system itself.
95 These people need to know about all aspects of the kernel Makefiles.
96
97 This document is aimed towards normal developers and arch developers.
98
99
100
101 === 3 Makefile language
102
103 The kernel Makefiles are designed to run with Gnu Make. The Makefiles
104 use only the documented features of Gnu Make, but they do use many
105 Gnu extensions.
106
107 Gnu Make supports elementary list-processing functions. The kernel
108 Makefiles use a novel style of list building and manipulation with few
109 "if" statements.
110
111 Gnu Make has two assignment operators, ":=" and "=". ":=" performs
112 immediate evaluation of the right-hand side and stores an actual string
113 into the left-hand side. "=" is like a formula definition; it stores the
114 right-hand side in an unevaluated form and then evaluates this form each
115 time the left-hand side is used.
116
117 There are some cases where "=" is appropriate. Usually, though, ":="
118 is the right choice.
119
120 All of the examples in this document were drawn from actual kernel
121 sources. The examples have been reformatted (white space changed, lines
122 split), but are otherwise exactly the same.
123
124
125
126 === 4 Variables passed down from the top
127
128 The top Makefile exports the following variables:
129
130 VERSION, PATCHLEVEL, SUBLEVEL, EXTRAVERSION
131
132 These variables define the current kernel version. A few arch
133 Makefiles actually use these values directly; they should use
134 $(KERNELRELEASE) instead.
135
136 $(VERSION), $(PATCHLEVEL), and $(SUBLEVEL) define the basic
137 three-part version number, such as "2", "4", and "0". These three
138 values are always numeric.
139
140 $(EXTRAVERSION) defines an even tinier sublevel for pre-patches
141 or additional patches. It is usually some non-numeric string
142 such as "-pre4", and is often blank.
143
144 KERNELRELEASE
145
146 $(KERNELRELEASE) is a single string such as "2.4.0-pre4", suitable
147 for constructing installation directory names or showing in
148 version strings. Some arch Makefiles use it for this purpose.
149
150 ARCH
151
152 This variable defines the target architecture, such as "i386",
153 "arm", or "sparc". Many subdirectory Makefiles test $(ARCH)
154 to determine which files to compile.
155
156 By default, the top Makefile sets $(ARCH) to be the same as the
157 host system system architecture. For a cross build, a user may
158 override the value of $(ARCH) on the command line:
159
160 make ARCH=m68k ...
161
162 TOPDIR, HPATH
163
164 $(TOPDIR) is the path to the top of the kernel source tree.
165 Subdirectory Makefiles need this so that they can include
166 $(TOPDIR)/Rules.make.
167
168 $(HPATH) is equal to $(TOPDIR)/include. A few arch Makefiles
169 need to use this to do special things using include files.
170
171 SUBDIRS
172
173 $(SUBDIRS) is a list of directories which the top Makefile
174 enters in order to build either vmlinux or modules. The actual
175 directories in $(SUBDIRS) depend on the kernel configuration.
176 The top Makefile defines this variable, and the arch Makefile
177 extends it.
178
179 HEAD, CORE_FILES, NETWORKS, DRIVERS, LIBS
180 LINKFLAGS
181
182 $(HEAD), $(CORE_FILES), $(NETWORKS), $(DRIVERS), and $(LIBS)
183 specify lists of object files and libraries to be linked into
184 vmlinux.
185
186 The files in $(HEAD) are linked first in vmlinux.
187
188 $(LINKFLAGS) specifies the flags to build vmlinux.
189
190 The top Makefile and the arch Makefile jointly define these
191 variables. The top Makefile defines $(CORE_FILES), $(NETWORKS),
192 $(DRIVERS), and $(LIBS). The arch Makefile defines $(HEAD)
193 and $(LINKFLAGS), and extends $(CORE_FILES) and $(LIBS).
194
195 Note: there are more names here than necessary. $(NETWORKS),
196 $(DRIVERS), and even $(LIBS) could be subsumed into $(CORE_FILES).
197
198 CPP, CC, AS, LD, AR, NM, STRIP, OBJCOPY, OBJDUMP
199 CPPFLAGS, CFLAGS, CFLAGS_KERNEL, MODFLAGS, AFLAGS, LDFLAGS
200 PERL
201 GENKSYMS
202
203 These variables specify the commands and flags that Rules.make
204 uses to build goal files from source files.
205
206 $(CFLAGS_KERNEL) contains extra C compiler flags used to compile
207 resident kernel code.
208
209 $(MODFLAGS) contains extra C compiler flags used to compile code
210 for loadable kernel modules. In the future, this flag may be
211 renamed to the more regular name $(CFLAGS_MODULE).
212
213 $(AFLAGS) contains assembler flags.
214
215 $(GENKSYMS) contains the command used to generate kernel symbol
216 signatures when CONFIG_MODVERSIONS is enabled. The genksyms
217 command comes from the modutils package.
218
219 CROSS_COMPILE
220
221 This variable is a prefix path for other variables such as $(CC),
222 $(AS), and $(LD). The arch Makefiles sometimes use and set this
223 variable explicitly. Subdirectory Makefiles don't need to worry
224 about it.
225
226 The user may override $(CROSS_COMPILE) on the command line if
227 desired.
228
229 HOSTCC, HOSTCFLAGS
230
231 These variables define the C compiler and C compiler flags to
232 be used for compiling host side programs. These are separate
233 variables because the target architecture can be different from
234 the host architecture.
235
236 If your Makefile compiles and runs a program that is executed
237 during the course of building the kernel, then it should use
238 $(HOSTCC) and $(HOSTCFLAGS).
239
240 For example, the subdirectory drivers/pci has a helper program
241 named gen-devlist.c. This program reads a list of PCI ID's and
242 generates C code in the output files classlist.h and devlist.h.
243
244 Suppose that a user has an i386 computer and wants to build a
245 kernel for an ia64 machine. Then the user would use an ia64
246 cross-compiler for most of the compilation, but would use a
247 native i386 host compiler to compile drivers/pci/gen-devlist.c.
248
249 For another example, kbuild helper programs such as
250 scripts/mkdep.c and scripts/lxdialog/*.c are compiled with
251 $(HOSTCC) rather than $(CC).
252
253 ROOT_DEV, SVGA_MODE, RAMDISK
254
255 End users edit these variables to specify certain information
256 about the configuration of their kernel. These variables
257 are ancient! They are also specific to the i386 architecture.
258 They really should be replaced with CONFIG_* options.
259
260 MAKEBOOT
261
262 This variable is defined and used only inside the main arch
263 Makefiles. The top Makefile should not export it.
264
265 INSTALL_PATH
266
267 This variable defines a place for the arch Makefiles to install
268 the resident kernel image and System.map file.
269
270 INSTALL_MOD_PATH, MODLIB
271
272 $(INSTALL_MOD_PATH) specifies a prefix to $(MODLIB) for module
273 installation. This variable is not defined in the Makefile but
274 may be passed in by the user if desired.
275
276 $(MODLIB) specifies the directory for module installation.
277 The top Makefile defines $(MODLIB) to
278 $(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE). The user may
279 override this value on the command line if desired.
280
281 CONFIG_SHELL
282
283 This variable is private between Makefile and Rules.make.
284 Arch makefiles and subdirectory Makefiles should never use this.
285
286 MODVERFILE
287
288 An internal variable. This doesn't need to be exported, as it
289 is never used outside of the top Makefile.
290
291 MAKE, MAKEFILES
292
293 Some variables internal to Gnu Make.
294
295 $(MAKEFILES) in particular is used to force the arch Makefiles
296 and subdirectory Makefiles to read $(TOPDIR)/.config without
297 including it explicitly. (This was an implementation hack and
298 could be fixed).
299
300
301
302 === 5 The structure of an arch Makefile
303
304
305
306 --- 5.1 Architecture-specific variables
307
308 The top Makefile includes one arch Makefile file, arch/$(ARCH)/Makefile.
309 This section describes the functions of the arch Makefile.
310
311 An arch Makefile extends some of the top Makefile's variables with
312 architecture-specific values.
313
314 SUBDIRS
315
316 The top Makefile defines $(SUBDIRS). The arch Makefile extends
317 $(SUBDIRS) with a list of architecture-specific directories.
318
319 Example:
320
321 # arch/alpha/Makefile
322
323 SUBDIRS := $(SUBDIRS) arch/alpha/kernel arch/alpha/mm \
324 arch/alpha/lib arch/alpha/math-emu
325
326 This list may depend on the configuration:
327
328 # arch/arm/Makefile
329
330 ifeq ($(CONFIG_ARCH_ACORN),y)
331 SUBDIRS += drivers/acorn
332 ...
333 endif
334
335 CPP, CC, AS, LD, AR, NM, STRIP, OBJCOPY, OBJDUMP
336 CPPFLAGS, CFLAGS, CFLAGS_KERNEL, MODFLAGS, AFLAGS, LDFLAGS
337
338 The top Makefile defines these variables, and the arch Makefile
339 extends them.
340
341 Many arch Makefiles dynamically run the target C compiler to
342 probe what options it supports:
343
344 # arch/i386/Makefile
345
346 # prevent gcc from keeping the stack 16 byte aligned
347 CFLAGS += $(shell if $(CC) -mpreferred-stack-boundary=2 \
348 -S -o /dev/null -xc /dev/null >/dev/null 2>&1; \
349 then echo "-mpreferred-stack-boundary=2"; fi)
350
351 And, of course, $(CFLAGS) can depend on the configuration:
352
353 # arch/i386/Makefile
354
355 ifdef CONFIG_M386
356 CFLAGS += -march=i386
357 endif
358
359 ifdef CONFIG_M486
360 CFLAGS += -march=i486
361 endif
362
363 ifdef CONFIG_M586
364 CFLAGS += -march=i586
365 endif
366
367 Some arch Makefiles redefine the compilation commands in order
368 to add architecture-specific flags:
369
370 # arch/s390/Makefile
371
372 LD=$(CROSS_COMPILE)ld -m elf_s390
373 OBJCOPY=$(CROSS_COMPILE)objcopy -O binary -R .note -R .comment -S
374
375
376
377 --- 5.2 Vmlinux build variables
378
379 An arch Makefile co-operates with the top Makefile to define variables
380 which specify how to build the vmlinux file. Note that there is no
381 corresponding arch-specific section for modules; the module-building
382 machinery is all architecture-independent.
383
384 HEAD, CORE_FILES, LIBS
385 LINKFLAGS
386
387 The top Makefile defines the architecture-independent core of
388 thse variables, and the arch Makefile extends them. Note that the
389 arch Makefile defines (not just extends) $(HEAD) and $(LINKFLAGS).
390
391 Example:
392
393 # arch/m68k/Makefile
394
395 ifndef CONFIG_SUN3
396 LINKFLAGS = -T $(TOPDIR)/arch/m68k/vmlinux.lds
397 else
398 LINKFLAGS = -T $(TOPDIR)/arch/m68k/vmlinux-sun3.lds -N
399 endif
400
401 ...
402
403 ifndef CONFIG_SUN3
404 HEAD := arch/m68k/kernel/head.o
405 else
406 HEAD := arch/m68k/kernel/sun3-head.o
407 endif
408
409 SUBDIRS += arch/m68k/kernel arch/m68k/mm arch/m68k/lib
410 CORE_FILES := arch/m68k/kernel/kernel.o arch/m68k/mm/mm.o $(CORE_FILES)
411 LIBS += arch/m68k/lib/lib.a
412
413
414
415 --- 5.3 Post-vmlinux goals
416
417 An arch Makefile specifies goals that take the vmlinux file, compress
418 it, wrap it in bootstrapping code, and copy the resulting files somewhere.
419 This includes various kinds of installation commands.
420
421 These post-vmlinux goals are not standardized across different
422 architectures. Here is a list of these goals and the architectures
423 that support each of them (as of kernel version 2.4.0-test6-pre5):
424
425 balo mips
426 bootimage alpha
427 bootpfile alpha, ia64
428 bzImage i386, m68k
429 bzdisk i386
430 bzlilo i386
431 compressed i386, m68k, mips, mips64, sh
432 dasdfmt s390
433 Image arm
434 image s390
435 install arm, i386
436 lilo m68k
437 msb alpha, ia64
438 my-special-boot alpha, ia64
439 orionboot mips
440 rawboot alpha
441 silo s390
442 srmboot alpha
443 tftpboot.img sparc, sparc64
444 vmlinux.64 mips64
445 vmlinux.aout sparc64
446 zImage arm, i386, m68k, mips, mips64, ppc, sh
447 zImage.initrd ppc
448 zdisk i386, mips, mips64, sh
449 zinstall arm
450 zlilo i386
451 znetboot.initrd ppc
452
453
454
455 --- 5.4 Mandatory arch-specific goals
456
457 An arch Makefile must define the following arch-specific goals.
458 These goals provide arch-specific actions for the corresponding goals
459 in the top Makefile:
460
461 archclean clean
462 archdep dep
463 archmrproper mrproper
464
465
466
467 === 6 The structure of a subdirectory Makefile
468
469 A subdirectory Makefile has five sections.
470
471
472
473 --- 6.1 Comments
474
475 The first section is a comment header. Just write what you would
476 write if you were editing a C source file, but use "# ..." instead of
477 "/* ... */". Historically, many anonymous people have edited kernel
478 Makefiles without leaving any change histories in the header; comments
479 from them would have been valuable.
480
481
482
483 --- 6.2 Goal definitions
484
485 The second section is a bunch of definitions that are the heart of the
486 subdirectory Makefile. These lines define the files to be built, any
487 special compilation options, and any subdirectories to be recursively
488 entered. The declarations in these lines depend heavily on the kernel
489 configuration variables (CONFIG_* symbols).
490
491 In some Makefiles ("old-style Makefiles"), the second section looks
492 like this:
493
494 # drivers/parport/Makefile
495 ifeq ($(CONFIG_PARPORT_PC),y)
496 LX_OBJS += parport_pc.o
497 else
498 ifeq ($(CONFIG_PARPORT_PC),m)
499 MX_OBJS += parport_pc.o
500 endif
501 endif
502
503 In most Makefiles ("new-style Makefiles"), the second section looks
504 like this:
505
506 # drivers/block/Makefile
507 obj-$(CONFIG_MAC_FLOPPY) += swim3.o
508 obj-$(CONFIG_BLK_DEV_FD) += floppy.o
509 obj-$(CONFIG_AMIGA_FLOPPY) += amiflop.o
510 obj-$(CONFIG_ATARI_FLOPPY) += ataflop.o
511
512 The new-style Makefiles are more compact and easier to get correct
513 for certain features (such as CONFIG_* options that enable more than
514 one file). If you have a choice, please write a new-style Makefile.
515
516
517
518 --- 6.3 Adapter section
519
520 The third section is an adapter section. In old-style Makefiles, this
521 third section is not present. In new-style Makefiles, the third section
522 contains boilerplate code which converts from new-style variables to
523 old-style variables. This is because Rules.make processes only the
524 old-style variables.
525
526 See section 8.2 ("Converting to old-style") for examples.
527
528
529
530 --- 6.4 Rules.make section
531
532 The fourth section is the single line:
533
534 include $(TOPDIR)/Rules.make
535
536
537
538 --- 6.5 Special rules
539
540 The fifth section contains any special Makefile rules needed that are
541 not available through the common rules in Rules.make.
542
543
544
545 === 7 Rules.make variables
546
547 The public interface of Rules.make consists of the following variables:
548
549
550
551 --- 7.1 Subdirectories
552
553 ALL_SUB_DIRS, SUB_DIRS, MOD_IN_SUB_DIRS, MOD_SUB_DIRS
554
555 $(ALL_SUB_DIRS) is an unconditional list of *all* the
556 subdirectories in a given directory. This list should not depend
557 on the kernel configuration.
558
559 $(SUB_DIRS) is a list of subdirectories which may contribute code
560 to vmlinux. This list may depend on the kernel configuration.
561
562 $(MOD_SUB_DIRS) and $(MOD_IN_SUB_DIRS) are lists of subdirectories
563 which may build kernel modules. Both names have exactly the
564 same meaning. (In version 2.2 and earlier kernels, these
565 variables had different meanings -- hence the different names).
566
567 For new code, $(MOD_SUB_DIRS) is recommended and $(MOD_IN_SUB_DIRS)
568 is deprecated.
569
570 Example:
571
572 # fs/Makefile
573 ALL_SUB_DIRS = coda minix ext2 fat msdos vfat proc isofs nfs \
574 umsdos ntfs hpfs sysv smbfs ncpfs ufs efs affs \
575 romfs autofs hfs lockd nfsd nls devpts devfs \
576 adfs partitions qnx4 udf bfs cramfs openpromfs \
577 autofs4 ramfs jffs
578 SUB_DIRS :=
579
580 ...
581
582 ifeq ($(CONFIG_EXT2_FS),y)
583 SUB_DIRS += ext2
584 else
585 ifeq ($(CONFIG_EXT2_FS),m)
586 MOD_SUB_DIRS += ext2
587 endif
588 endif
589
590 ifeq ($(CONFIG_CRAMFS),y)
591 SUB_DIRS += cramfs
592 else
593 ifeq ($(CONFIG_CRAMFS),m)
594 MOD_SUB_DIRS += cramfs
595 endif
596 endif
597
598 Example:
599
600 # drivers/net/Makefile
601 SUB_DIRS :=
602 MOD_SUB_DIRS :=
603 MOD_IN_SUB_DIRS :=
604 ALL_SUB_DIRS := $(SUB_DIRS) fc hamradio irda pcmcia tokenring \
605 wan sk98lin arcnet skfp tulip appletalk
606
607 ...
608
609 ifeq ($(CONFIG_IRDA),y)
610 SUB_DIRS += irda
611 MOD_IN_SUB_DIRS += irda
612 else
613 ifeq ($(CONFIG_IRDA),m)
614 MOD_IN_SUB_DIRS += irda
615 endif
616 endif
617
618 ifeq ($(CONFIG_TR),y)
619 SUB_DIRS += tokenring
620 MOD_IN_SUB_DIRS += tokenring
621 else
622 ifeq ($(CONFIG_TR),m)
623 MOD_IN_SUB_DIRS += tokenring
624 endif
625 endif
626
627
628
629 --- 7.2 Object file goals
630
631 O_TARGET, O_OBJS, OX_OBJS
632
633 The subdirectory Makefile specifies object files for vmlinux in
634 the lists $(O_OBJS) and $(OX_OBJS). These lists depend on the
635 kernel configuration.
636
637 The "X" in "OX_OBJS" stands for "eXport". Files in $(OX_OBJS)
638 may use the EXPORT_SYMBOL macro to define public symbols which
639 loadable kernel modules can see. Files in $(O_OBJS) may not use
640 EXPORT_SYMBOL (and you will get a funky error message if you try).
641
642 [Yes, it's kludgy to do this by hand. Yes, you can define all
643 your objects as $(OX_OBJS) whether they define symbols or not;
644 but then you will notice a lot of extra compiles when you edit
645 any source file. Blame CONFIG_MODVERSIONS for this.]
646
647 Data that is passed to other objects via registration functions
648 (e.g. pci_register_driver, pm_register) does not need to be marked
649 as EXPORT_SYMBOL. The objects that pass data via registration
650 functions do not need to be marked as OX_OBJS, unless they also have
651 exported symbols.
652
653 Rules.make compiles all the $(O_OBJS) and $(OX_OBJS) files.
654 It then calls "$(LD) -r" to merge these files into one .o file
655 with the name $(O_TARGET). This $(O_TARGET) name also appears
656 in the top Makefile.
657
658 The order of files in $(O_OBJS) and $(OX_OBJS) is significant.
659 All $(OX_OBJS) files come first, in the order listed, followed by
660 all $(O_OBJS) files, in the order listed. Duplicates in the lists
661 are allowed: the first instance will be linked into $(O_TARGET)
662 and succeeding instances will be ignored. (Note: Rules.make may
663 emit warning messages for duplicates, but this is harmless).
664
665 Example:
666
667 # arch/alpha/kernel/Makefile
668 O_TARGET := kernel.o
669 O_OBJS := entry.o traps.o process.o osf_sys.o irq.o \
670 irq_alpha.o signal.o setup.o ptrace.o time.o \
671 semaphore.o
672 OX_OBJS := alpha_ksyms.o
673
674 ifdef CONFIG_SMP
675 O_OBJS += smp.o irq_smp.o
676 endif
677
678 ifdef CONFIG_PCI
679 O_OBJS += pci.o pci_iommu.o
680 endif
681
682 Even if a subdirectory Makefile has an $(O_TARGET), the .config
683 options still control whether or not its $(O_TARGET) goes into
684 vmlinux. See the $(M_OBJS) example below.
685
686 Sometimes the ordering of all $(OX_OBJS) files before all
687 $(O_OBJS) files can be a problem, particularly if both
688 $(O_OBJS) files and $(OX_OBJS) files contain __initcall
689 declarations where order is important. To avoid this imposed
690 ordering, the use of $(OX_OBJS) can be dropped altogether and
691 $(MIX_OBJS) used instead.
692
693 If this approach is used, then:
694 - All objects to be linked into vmlinux should be listed in
695 $(O_OBJS) in the desired order.
696 - All objects to be created as modules should be listed in
697 $(M_OBJS)
698 - All objects that export symbols should also be listed in
699 $(MIX_OBJS).
700
701 This has the same effect as maintaining the
702 exported/non-exported split, except that there is more control
703 over the ordering of object files in vmlinux.
704
705
706
707 --- 7.3 Library file goals
708
709 L_TARGET, L_OBJS, LX_OBJS
710
711 These names are similar to the O_* names. Once again, $(L_OBJS)
712 and $(LX_OBJS) specify object files for the resident kernel;
713 once again, the lists depend on the current configuration; and
714 once again, the files that call EXPORT_SYMBOL go on the "X" list.
715
716 The difference is that "L" stands for "Library". After making
717 $(L_OBJS) and $(LX_OBJS), Rules.make uses the "$(AR) rcs" command
718 to put these files into an archive file (a library) with the
719 name $(L_TARGET). This name also appears in the top Makefile.
720
721 Example:
722
723 # arch/i386/lib/Makefile
724 L_TARGET = lib.a
725 L_OBJS = checksum.o old-checksum.o delay.o \
726 usercopy.o getuser.o putuser.o iodebug.o
727
728 ifdef CONFIG_X86_USE_3DNOW
729 L_OBJS += mmx.o
730 endif
731
732 ifdef CONFIG_HAVE_DEC_LOCK
733 L_OBJS += dec_and_lock.o
734 endif
735
736 The order of files in $(L_OBJS) and $(LX_OBJS) is not significant.
737 Duplicates in the lists are allowed. (Note: Rules.make may emit
738 warning messages for duplicates, but this is harmless).
739
740 A subdirectory Makefile can specify either an $(O_TARGET),
741 an $(L_TARGET), or both. Here is a discussion of the differences.
742
743 All of the files in an $(O_TARGET) are guaranteed to appear in
744 the resident vmlinux image. In an $(L_TARGET), only the files
745 that satisfy undefined symbol references from other files will
746 appear in vmlinux.
747
748 In a conventional link process, the linker processes some
749 object files and creates a list of unresolved external symbols.
750 The linker then looks in a set of libraries to resolve these
751 symbols. Indeed, the Linux kernel used to be linked this way,
752 with the bulk of the code stored in libraries.
753
754 But vmlinux contains two types of object files that cannot be
755 fetched out of libraries this way:
756
757 (1) object files that are purely EXPORT_SYMBOL definitions
758 (2) object files that use module_init or __initcall initializers
759 (instead of an initialization routine called externally)
760
761 These files contain autonomous initializer sections which provide
762 code and data without being explicitly called. If these files
763 were stored in $(L_TARGET) libraries, the linker would fail
764 to include them in vmlinux. Thus, most subdirectory Makefiles
765 specify an $(O_TARGET) and do not use $(L_TARGET).
766
767 Other considerations: $(O_TARGET) leads to faster re-link times
768 during development activity, but $(L_TARGET) gives better error
769 messages for unresolved symbols.
770
771
772
773 --- 7.4 Loadable module goals
774
775 M_OBJS, MX_OBJS
776
777 $(M_OBJS) and $(MX_OBJS) specify object files which are built
778 as loadable kernel modules. As usual, the "X" in $(MX_OBJS)
779 stands for "eXport"; source files that use EXPORT_SYMBOL must
780 appear on an $(MX_OBJS) list.
781
782 A module may be built from one source file or several source
783 files. In the case of one source file, the subdirectory
784 Makefile simply adds the file to either $(M_OBJS) or $(MX_OBJS),
785 as appropriate.
786
787 Example:
788
789 # drivers/net/irda/Makefile
790 ifeq ($(CONFIG_IRTTY_SIR),y)
791 L_OBJS += irtty.o
792 else
793 ifeq ($(CONFIG_IRTTY_SIR),m)
794 M_OBJS += irtty.o
795 endif
796 endif
797
798 ifeq ($(CONFIG_IRPORT_SIR),y)
799 LX_OBJS += irport.o
800 else
801 ifeq ($(CONFIG_IRPORT_SIR),m)
802 MX_OBJS += irport.o
803 endif
804 endif
805
806 If a kernel module is built from several source files, there
807 are two ways to specify the set of source files. One way is to
808 build a single module for the entire subdirectory. This way is
809 popular in the file system and network protocol stacks.
810
811 Example:
812
813 # fs/ext2/Makefile
814 O_TARGET := ext2.o
815 O_OBJS := acl.o balloc.o bitmap.o dir.o file.o fsync.o \
816 ialloc.o inode.o ioctl.o namei.o super.o symlink.o \
817 truncate.o
818 M_OBJS := $(O_TARGET)
819
820 In this example, the module name will be ext2.o. Because this
821 file has the same name has $(O_TARGET), Rules.make will use
822 the $(O_TARGET) rule to build ext2.o: it will run "$(LD) -r"
823 on the list of $(O_OBJS) files.
824
825 Note that this subdirectory Makefile defines both an $(O_TARGET)
826 and an $(M_OBJS). The control code, up in fs/Makefile, will
827 select between these two. If CONFIG_EXT2_FS=y, then fs/Makefile
828 will build $(O_TARGET); and if CONFIG_EXT_FS=m, then fs/Makefile
829 will build $(M_OBJS) instead. (Yes, this is a little delicate
830 and a little confusing).
831
832
833
834 --- 7.5 Multi-part modules
835
836 MI_OBJS, MIX_OBJS
837
838 Some kernel modules are composed of several object files
839 linked together, but do not include every object file in their
840 subdirectory. $(MI_OBJS) and $(MIX_OBJS) are for this case.
841
842 "M" stands for Module.
843 "I" stands for Intermediate.
844 "X", as usual, stands for "eXport symbol".
845
846 Example:
847
848 # drivers/sound/Makefile
849 gus-objs := gus_card.o gus_midi.o gus_vol.o gus_wave.o ics2101.o
850 pas2-objs := pas2_card.o pas2_midi.o pas2_mixer.o pas2_pcm.o
851 sb-objs := sb_card.o
852
853 gus.o: $(gus-objs)
854 $(LD) -r -o $@ $(gus-objs)
855
856 pas2.o: $(pas2-objs)
857 $(LD) -r -o $@ $(pas2-objs)
858
859 sb.o: $(sb-objs)
860 $(LD) -r -o $@ $(sb-objs)
861
862 The kernel modules gus.o, pas2.o, and sb.o are the *composite
863 files*. The object files gus_card.o, gus_midi.o, gus_vol.o,
864 gus_wave.o, ics2101.o, pas2_card.o, pas2_midi.o, pas2_mixer.o,
865 pas2_pcm.o, and sb_card.o are *component files*. The component
866 files are also called *intermediate files*.
867
868 In another part of drivers/sound/Makefile (not shown), all of
869 the component files are split out. For the resident drivers:
870 the component object files go onto $(O_OBJS) and $(OX_OBJS)
871 lists, depending on whether they export symbols or not; and the
872 composite files are never built. For the kernel modules: the
873 component object files go onto $(MI_OBJS) and $(MIX_OBJS);
874 the composite files go onto $(M_OBJS).
875
876 The subdirectory Makefile must also specify the linking rule
877 for a multi-object-file module:
878
879 # drivers/sound/Makefile
880
881 gus.o: $(gus-objs)
882 $(LD) -r -o $@ $(gus-objs)
883
884 pas2.o: $(pas2-objs)
885 $(LD) -r -o $@ $(pas2-objs)
886
887 sb.o: $(sb-objs)
888 $(LD) -r -o $@ $(sb-objs)
889
890
891 As is mentioned in section 7.2 ("Object file goals"),
892 $(MIX_OBJS) can also be used simply to list all objects that
893 export any symbols. If this approach is taken, then
894 $(O_OBJS), $(L_OBJS), $(M_OBJS) and $(MI_OBJS) should simply
895 lists all of the vmlinux object files, library object files,
896 module object files and intermediate module files
897 respectively. Duplication between $(MI_OBJS) and $(MIX_OBJS)
898 is not a problem.
899
900 --- 7.6 Compilation flags
901
902 EXTRA_CFLAGS, EXTRA_AFLAGS, EXTRA_LDFLAGS, EXTRA_ARFLAGS
903
904 $(EXTRA_CFLAGS) specifies options for compiling C files with
905 $(CC). The options in this variable apply to all $(CC) commands
906 for files in the current directory.
907
908 Example:
909
910 # drivers/sound/emu10k1/Makefile
911 EXTRA_CFLAGS += -I.
912 ifdef DEBUG
913 EXTRA_CFLAGS += -DEMU10K1_DEBUG
914 endif
915
916 $(EXTRA_CFLAGS) does not apply to subdirectories of the current
917 directory. Also, it does not apply to files compiled with
918 $(HOSTCC).
919
920 This variable is necessary because the top Makefile owns the
921 variable $(CFLAGS) and uses it for compilation flags for the
922 entire tree.
923
924 $(EXTRA_AFLAGS) is a similar string for per-directory options
925 when compiling assembly language source.
926
927 Example: at the time of writing, there were no examples of
928 $(EXTRA_AFLAGS) in the kernel corpus.
929
930 $(EXTRA_LDFLAGS) and $(EXTRA_ARFLAGS) are similar strings for
931 per-directory options to $(LD) and $(AR).
932
933 Example: at the time of writing, there were no examples of
934 $(EXTRA_LDFLAGS) or $(EXTRA_ARFLAGS) in the kernel corpus.
935
936 CFLAGS_$@, AFLAGS_$@
937
938 $(CFLAGS_$@) specifies per-file options for $(CC). The $@
939 part has a literal value which specifies the file that it's for.
940
941 Example:
942
943 # drivers/scsi/Makefile
944 CFLAGS_aha152x.o = -DAHA152X_STAT -DAUTOCONF
945 CFLAGS_gdth.o = # -DDEBUG_GDTH=2 -D__SERIAL__ -D__COM2__ \
946 -DGDTH_STATISTICS
947 CFLAGS_seagate.o = -DARBITRATE -DPARITY -DSEAGATE_USE_ASM
948
949 These three lines specify compilation flags for aha152x.o,
950 gdth.o, and seagate.o
951
952 $(AFLAGS_$@) is a similar feature for source files in assembly
953 languages.
954
955 Example:
956
957 # arch/arm/kernel/Makefile
958 AFLAGS_head-armv.o := -DTEXTADDR=$(TEXTADDR) -traditional
959 AFLAGS_head-armo.o := -DTEXTADDR=$(TEXTADDR) -traditional
960
961 Rules.make has a feature where an object file depends on the
962 value of $(CFLAGS_$@) that was used to compile it. (It also
963 depends on the values of $(CFLAGS) and $(EXTRA_CFLAGS)). Thus,
964 if you change the value of $(CFLAGS_$@) for a file, either by
965 editing the Makefile or overriding the value some other way,
966 Rules.make will do the right thing and re-compile your source
967 file with the new options.
968
969 Note: because of a deficiency in Rules.make, assembly language
970 files do not have flag dependencies. If you edit $(AFLAGS_$@)
971 for such a file, you will have to remove the object file in order
972 to re-build from source.
973
974 LD_RFLAG
975
976 This variable is used, but never defined. It appears to be a
977 vestige of some abandoned experiment.
978
979
980
981 --- 7.7 Miscellaneous variables
982
983 IGNORE_FLAGS_OBJS
984
985 $(IGNORE_FLAGS_OBJS) is a list of object files which will not have
986 their flag dependencies automatically tracked. This is a hackish
987 feature, used to kludge around a problem in the implementation
988 of flag dependencies. (The problem is that flag dependencies
989 assume that a %.o file is built from a matching %.S or %.c file.
990 This is sometimes not true).
991
992 USE_STANDARD_AS_RULE
993
994 This is a transition variable. If $(USE_STANDARD_AS_RULE)
995 is defined, then Rules.make will provide standard rules for
996 assembling %.S files into %.o files or %.s files (%.s files
997 are useful only to developers).
998
999 If $(USE_STANDARD_AS_RULE) is not defined, then Rules.make
1000 will not provide these standard rules. In this case, the
1001 subdirectory Makefile must provide its own private rules for
1002 assembling %.S files.
1003
1004 In the past, all Makefiles provided private %.S rules. Newer
1005 Makefiles should define USE_STANDARD_AS_RULE and use the standard
1006 Rules.make rules. As soon as all the Makefiles across all
1007 architectures have been converted to USE_STANDARD_AS_RULE, then
1008 Rules.make can drop the conditional test on USE_STANDARD_AS_RULE.
1009 After that, all the other Makefiles can drop the definition of
1010 USE_STANDARD_AS_RULE.
1011
1012
1013
1014 === 8 New-style variables
1015
1016 The "new-style variables" are simpler and more powerful than the
1017 "old-style variables". As a result, many subdirectory Makefiles shrank
1018 more than 60%. This author hopes that, in time, all arch Makefiles and
1019 subdirectory Makefiles will convert to the new style.
1020
1021 Rules.make does not understand new-style variables. Thus, each new-style
1022 Makefile has a section of boilerplate code that converts the new-style
1023 variables into old-style variables. There is also some mixing, where
1024 people define most variables using "new style" but then fall back to
1025 "old style" for a few lines.
1026
1027 --- 8.1 New variables
1028
1029 obj-y obj-m obj-n obj-
1030
1031 These variables replace $(O_OBJS), $(OX_OBJS), $(M_OBJS),
1032 and $(MX_OBJS).
1033
1034 Example:
1035
1036 # drivers/block/Makefile
1037 obj-$(CONFIG_MAC_FLOPPY) += swim3.o
1038 obj-$(CONFIG_BLK_DEV_FD) += floppy.o
1039 obj-$(CONFIG_AMIGA_FLOPPY) += amiflop.o
1040 obj-$(CONFIG_ATARI_FLOPPY) += ataflop.o
1041
1042 Notice the use of $(CONFIG_...) substitutions on the left hand
1043 side of an assignment operator. This gives Gnu Make the power
1044 of associative indexing! Each of these assignments replaces
1045 eight lines of code in an old-style Makefile.
1046
1047 After executing all of the assignments, the subdirectory
1048 Makefile has built up four lists: $(obj-y), $(obj-m), $(obj-n),
1049 and $(obj-).
1050
1051 $(obj-y) is a list of files to include in vmlinux.
1052 $(obj-m) is a list of files to build as single-file modules.
1053 $(obj-n) and $(obj-) are ignored.
1054
1055 Each list may contain duplicates items; duplicates are
1056 automatically removed later. Also, if a file appears in both
1057 $(obj-y) and $(obj-m), it will automatically be removed from
1058 the $(obj-m) list.
1059
1060 Example:
1061
1062 # drivers/net/Makefile
1063
1064 ...
1065 obj-$(CONFIG_OAKNET) += oaknet.o 8390.o
1066 ...
1067 obj-$(CONFIG_NE2K_PCI) += ne2k-pci.o 8390.o
1068 ...
1069 obj-$(CONFIG_STNIC) += stnic.o 8390.o
1070 ...
1071 obj-$(CONFIG_MAC8390) += daynaport.o 8390.o
1072 ...
1073
1074 In this example, four different drivers require the code in
1075 8390.o. If one or more of these four drivers are built into
1076 vmlinux, then 8390.o will also be built into vmlinux, and will
1077 *not* be built as a module -- even if another driver which needs
1078 8390.o is built as a module. (The modular driver is able to
1079 use services of the 8390.o code in the resident vmlinux image).
1080
1081 export-objs
1082
1083 $(export-objs) is a list of all the files in the subdirectory
1084 which potentially export symbols. The canonical way to construct
1085 this list is:
1086
1087 grep -l EXPORT_SYMBOL *.c
1088
1089 (but watch out for sneaky files that call EXPORT_SYMBOL from an
1090 included header file!)
1091
1092 This is a potential list, independent of the kernel configuration.
1093 All files that export symbols go into $(export-objs). The
1094 boilerplate code then uses the $(export-objs) list to separate
1095 the real file lists into $(*_OBJS) and $(*X_OBJS).
1096
1097 Experience has shown that maintaining the proper X's in an
1098 old-style Makefile is difficult and error-prone. Maintaining the
1099 $(export-objs) list in a new-style Makefile is simpler and easier
1100 to audit.
1101
1102 list-multi
1103 $(foo)-objs
1104
1105 Some kernel modules are composed of multiple object files linked
1106 together. $(list-multi) is a list of such kernel modules.
1107 This is a static list; it does not depend on the configuration.
1108
1109 For each kernel module in $(list-multi) there is another list
1110 of all the object files which make up that module. For a kernel
1111 module named foo.o, its object file list is foo-objs.
1112
1113 Example:
1114
1115 # drivers/scsi/Makefile
1116 list-multi := scsi_mod.o sr_mod.o initio.o a100u2w.o
1117
1118 ...
1119
1120 scsi_mod-objs := hosts.o scsi.o scsi_ioctl.o constants.o \
1121 scsicam.o scsi_proc.o scsi_error.o \
1122 scsi_obsolete.o scsi_queue.o scsi_lib.o \
1123 scsi_merge.o scsi_dma.o scsi_scan.o \
1124 scsi_syms.o
1125 sr_mod-objs := sr.o sr_ioctl.o sr_vendor.o
1126 initio-objs := ini9100u.o i91uscsi.o
1127 a100u2w-objs := inia100.o i60uscsi.o
1128
1129 The subdirectory Makefile puts the modules onto obj-* lists in
1130 the usual configuration-dependent way:
1131
1132 obj-$(CONFIG_SCSI) += scsi_mod.o
1133 obj-$(CONFIG_BLK_DEV_SR) += sr_mod.o
1134 obj-$(CONFIG_SCSI_INITIO) += initio.o
1135 obj-$(CONFIG_SCSI_INIA100) += a100u2w.o
1136
1137 Suppose that CONFIG_SCSI=y. Then vmlinux needs to link in all
1138 14 components of scsi_mod.o, so these components will go onto
1139 $(O_OBJS) and $(OX_OBJS). The composite file scsi_mod.o will
1140 never be created. The boilerplate conversion code produces this
1141 result with a few lines of list processing commands.
1142
1143 Suppose that CONFIG_BLK_DEV_SR=m. Then the 3 components
1144 of sr_mod.o will linked together with "$(LD) -r" to make the
1145 kernel module sr_mod.o, so these 3 components need to go onto
1146 the $(MI_OBJS) and $(MIX_OBJS) lists; the composite file sr_mod.o
1147 goes onto $(M_OBJS). The boilerplate conversion code takes care
1148 of this, too.
1149
1150 And suppose CONFIG_SCSI_INITIO=n. Then initio.o goes onto the
1151 $(obj-n) list and that's the end of it. Its component files
1152 are not compiled, and the composite file is not created.
1153
1154 Finally, the subdirectory Makefile needs to define rules to
1155 build each multi-object kernel module from its component list.
1156 Example:
1157
1158 # drivers/scsi/Makefile
1159
1160 scsi_mod.o: $(scsi_mod-objs)
1161 $(LD) -r -o $@ $(scsi_mod-objs)
1162
1163 sr_mod.o: $(sr_mod-objs)
1164 $(LD) -r -o $@ $(sr_mod-objs)
1165
1166 initio.o: $(initio-objs)
1167 $(LD) -r -o $@ $(initio-objs)
1168
1169 a100u2w.o: $(a100u2w-objs)
1170 $(LD) -r -o $@ $(a100u2w-objs)
1171
1172 These rules are very regular; it would be nice for the boilerplate
1173 code or Rules.make to synthesize these rules automatically.
1174 But until that happens, the subdirectory Makefile needs to define
1175 these rules explicitly.
1176
1177 subdir-y subdir-m subdir-n subdir-
1178
1179 These variables replace $(ALL_SUB_DIRS), $(SUB_DIRS) and
1180 $(MOD_SUB_DIRS).
1181
1182 Example:
1183
1184 # drivers/Makefile
1185 subdir-$(CONFIG_PCI) += pci
1186 subdir-$(CONFIG_PCMCIA) += pcmcia
1187 subdir-$(CONFIG_MTD) += mtd
1188 subdir-$(CONFIG_SBUS) += sbus
1189
1190 These variables work similar to obj-*, but are used for
1191 subdirectories instead of object files.
1192
1193 After executing all of the assignments, the subdirectory
1194 Makefile has built up four lists: $(subdir-y), $(subdir-m),
1195 $(subdir-n), and $(subdir-).
1196
1197 $(subdir-y) is a list of directories that should be entered
1198 for making vmlinux.
1199 $(subdir-m) is a list of directories that should be entered
1200 for making modules.
1201 $(subdir-n) and $(subdir-) are only used for collecting a list
1202 of all subdirectories of this directory.
1203
1204 Each list besides subdir-y may contain duplicates items; duplicates
1205 are automatically removed later.
1206
1207 mod-subdirs
1208
1209 $(mod-subdirs) is a list of all the the subdirectories that should
1210 be added to $(subdir-m), too if they appear in $(subdir-y)
1211
1212 Example:
1213
1214 # fs/Makefile
1215 mod-subdirs := nls
1216
1217 This means nls should be added to (subdir-y) and $(subdir-m) if
1218 CONFIG_NFS = y.
1219
1220 --- 8.2 Converting to old-style
1221
1222 The following example is taken from drivers/usb/Makefile.
1223 Note that this uses MIX_OBJS to avoid the need for OX_OBJS and
1224 MX_OBJS and thus to maintain the ordering of objects in $(obj-y)
1225
1226 # Translate to Rules.make lists.
1227 multi-used := $(filter $(list-multi), $(obj-y) $(obj-m))
1228 multi-objs := $(foreach m, $(multi-used), $($(basename $(m))-objs))
1229 active-objs := $(sort $(multi-objs) $(obj-y) $(obj-m))
1230
1231 O_OBJS := $(obj-y)
1232 M_OBJS := $(obj-m)
1233 MIX_OBJS := $(filter $(export-objs), $(active-objs))
1234
1235 An example for libraries from drivers/acorn/scsi/Makefile:
1236
1237 # Translate to Rules.make lists.
1238
1239 L_OBJS := $(filter-out $(export-objs), $(obj-y))
1240 LX_OBJS := $(filter $(export-objs), $(obj-y))
1241 M_OBJS := $(sort $(filter-out $(export-objs), $(obj-m)))
1242 MX_OBJS := $(sort $(filter $(export-objs), $(obj-m)))
1243
1244 As ordering is not so important in libraries, this still uses
1245 LX_OBJS and MX_OBJS, though (presumably) it could be changed to
1246 use MIX_OBJS as follows:
1247
1248 active-objs := $(sort $(obj-y) $(obj-m))
1249 L_OBJS := $(obj-y)
1250 M_OBJS := $(obj-m)
1251 MIX_OBJS := $(filter $(export-objs), $(active-objs))
1252
1253
1254 which is clearly shorted and arguably clearer.
1255
1256 === 9 Compatibility with Linux Kernel 2.2
1257
1258 Most of the information in this document also applies to 2.2, although
1259 there is no indication of which things have changed when. Here are some
1260 hints for writing subdirectory Makefiles that are compatible with Linux
1261 kernel 2.2.
1262
1263 You can write either an old-style Makefile or a new-style Makefile
1264 with a boilerplate adapter section. See the 2.2 version of
1265 drivers/sound/Makefile for a copy of the boilerplate code.
1266
1267 In 2.2, Rules.make makes a distinction between $(MOD_SUB_DIRS)
1268 and $(MOD_IN_SUB_DIRS). If you have a single directory with no
1269 subdirectories, this will not matter to you. If you have a whole
1270 tree, then you need to know the difference between $(MOD_SUB_DIRS)
1271 and $(MOD_IN_SUB_DIRS). For example code: $(MOD_SUB_DIRS) is used
1272 extensively in fs/Makefile; $(MOD_IN_SUB_DIRS) is used extensively in
1273 drivers/net/Makefile.
1274
1275 If you are already using MOD_LIST_NAME, go ahead and keep using it.
1276 If you don't already have a MOD_LIST_NAME, go ahead and keep not using
1277 one; your module will be a 'misc' module in 2.2.
1278
1279 Assembly language rules were a mess in 2.2. If you have assembly language
1280 files, this author recommends that you write your own explicit rules
1281 for each file by name.
1282
1283
1284
1285 === 10 Credits
1286
1287 Thanks to the members of the linux-kbuild mailing list for reviewing
1288 drafts of this document, with particular thanks to Peter Samuelson
1289 and Thomas Molina.
This page was automatically generated by the
LXR engine.
Visit the LXR main site for more
information.