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