Documentation/kbuild/kbuild.rst

   1 ======
   2 Kbuild
   3 ======
   4
   5
   6 Output files
   7 ============
   8
   9 modules.order
  10 -------------
  11 This file records the order in which modules appear in Makefiles. This
  12 is used by modprobe to deterministically resolve aliases that match
  13 multiple modules.
  14
  15 modules.builtin
  16 ---------------
  17 This file lists all modules that are built into the kernel. This is used
  18 by modprobe to not fail when trying to load something builtin.
  19
  20 modules.builtin.modinfo
  21 -----------------------
  22 This file contains modinfo from all modules that are built into the kernel.
  23 Unlike modinfo of a separate module, all fields are prefixed with module name.
  24
  25
  26 Environment variables
  27 =====================
  28
  29 KCPPFLAGS
  30 ---------
  31 Additional options to pass when preprocessing. The preprocessing options
  32 will be used in all cases where kbuild does preprocessing including
  33 building C files and assembler files.
  34
  35 KAFLAGS
  36 -------
  37 Additional options to the assembler (for built-in and modules).
  38
  39 AFLAGS_MODULE
  40 -------------
  41 Additional assembler options for modules.
  42
  43 AFLAGS_KERNEL
  44 -------------
  45 Additional assembler options for built-in.
  46
  47 KCFLAGS
  48 -------
  49 Additional options to the C compiler (for built-in and modules).
  50
  51 CFLAGS_KERNEL
  52 -------------
  53 Additional options for $(CC) when used to compile
  54 code that is compiled as built-in.
  55
  56 CFLAGS_MODULE
  57 -------------
  58 Additional module specific options to use for $(CC).
  59
  60 LDFLAGS_MODULE
  61 --------------
  62 Additional options used for $(LD) when linking modules.
  63
  64 HOSTCFLAGS
  65 ----------
  66 Additional flags to be passed to $(HOSTCC) when building host programs.
  67
  68 HOSTCXXFLAGS
  69 ------------
  70 Additional flags to be passed to $(HOSTCXX) when building host programs.
  71
  72 HOSTLDFLAGS
  73 -----------
  74 Additional flags to be passed when linking host programs.
  75
  76 HOSTLDLIBS
  77 ----------
  78 Additional libraries to link against when building host programs.
  79
  80 .. _userkbuildflags:
  81
  82 USERCFLAGS
  83 ----------
  84 Additional options used for $(CC) when compiling userprogs.
  85
  86 USERLDFLAGS
  87 -----------
  88 Additional options used for $(LD) when linking userprogs. userprogs are linked
  89 with CC, so $(USERLDFLAGS) should include "-Wl," prefix as applicable.
  90
  91 KBUILD_KCONFIG
  92 --------------
  93 Set the top-level Kconfig file to the value of this environment
  94 variable.  The default name is "Kconfig".
  95
  96 KBUILD_VERBOSE
  97 --------------
  98 Set the kbuild verbosity. Can be assigned same values as "V=...".
  99
 100 See make help for the full list.
 101
 102 Setting "V=..." takes precedence over KBUILD_VERBOSE.
 103
 104 KBUILD_EXTMOD
 105 -------------
 106 Set the directory to look for the kernel source when building external
 107 modules.
 108
 109 Setting "M=..." takes precedence over KBUILD_EXTMOD.
 110
 111 KBUILD_OUTPUT
 112 -------------
 113 Specify the output directory when building the kernel.
 114
 115 The output directory can also be specified using "O=...".
 116
 117 Setting "O=..." takes precedence over KBUILD_OUTPUT.
 118
 119 KBUILD_EXTRA_WARN
 120 -----------------
 121 Specify the extra build checks. The same value can be assigned by passing
 122 W=... from the command line.
 123
 124 See `make help` for the list of the supported values.
 125
 126 Setting "W=..." takes precedence over KBUILD_EXTRA_WARN.
 127
 128 KBUILD_DEBARCH
 129 --------------
 130 For the deb-pkg target, allows overriding the normal heuristics deployed by
 131 deb-pkg. Normally deb-pkg attempts to guess the right architecture based on
 132 the UTS_MACHINE variable, and on some architectures also the kernel config.
 133 The value of KBUILD_DEBARCH is assumed (not checked) to be a valid Debian
 134 architecture.
 135
 136 ARCH
 137 ----
 138 Set ARCH to the architecture to be built.
 139
 140 In most cases the name of the architecture is the same as the
 141 directory name found in the arch/ directory.
 142
 143 But some architectures such as x86 and sparc have aliases.
 144
 145 - x86: i386 for 32 bit, x86_64 for 64 bit
 146 - sh: sh for 32 bit, sh64 for 64 bit
 147 - sparc: sparc32 for 32 bit, sparc64 for 64 bit
 148
 149 CROSS_COMPILE
 150 -------------
 151 Specify an optional fixed part of the binutils filename.
 152 CROSS_COMPILE can be a part of the filename or the full path.
 153
 154 CROSS_COMPILE is also used for ccache in some setups.
 155
 156 CF
 157 --
 158 Additional options for sparse.
 159
 160 CF is often used on the command-line like this::
 161
 162     make CF=-Wbitwise C=2
 163
 164 INSTALL_PATH
 165 ------------
 166 INSTALL_PATH specifies where to place the updated kernel and system map
 167 images. Default is /boot, but you can set it to other values.
 168
 169 INSTALLKERNEL
 170 -------------
 171 Install script called when using "make install".
 172 The default name is "installkernel".
 173
 174 The script will be called with the following arguments:
 175
 176    - $1 - kernel version
 177    - $2 - kernel image file
 178    - $3 - kernel map file
 179    - $4 - default install path (use root directory if blank)
 180
 181 The implementation of "make install" is architecture specific
 182 and it may differ from the above.
 183
 184 INSTALLKERNEL is provided to enable the possibility to
 185 specify a custom installer when cross compiling a kernel.
 186
 187 MODLIB
 188 ------
 189 Specify where to install modules.
 190 The default value is::
 191
 192      $(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE)
 193
 194 The value can be overridden in which case the default value is ignored.
 195
 196 INSTALL_MOD_PATH
 197 ----------------
 198 INSTALL_MOD_PATH specifies a prefix to MODLIB for module directory
 199 relocations required by build roots.  This is not defined in the
 200 makefile but the argument can be passed to make if needed.
 201
 202 INSTALL_MOD_STRIP
 203 -----------------
 204 INSTALL_MOD_STRIP, if defined, will cause modules to be
 205 stripped after they are installed.  If INSTALL_MOD_STRIP is '1', then
 206 the default option --strip-debug will be used.  Otherwise,
 207 INSTALL_MOD_STRIP value will be used as the options to the strip command.
 208
 209 INSTALL_HDR_PATH
 210 ----------------
 211 INSTALL_HDR_PATH specifies where to install user space headers when
 212 executing "make headers_*".
 213
 214 The default value is::
 215
 216     $(objtree)/usr
 217
 218 $(objtree) is the directory where output files are saved.
 219 The output directory is often set using "O=..." on the commandline.
 220
 221 The value can be overridden in which case the default value is ignored.
 222
 223 KBUILD_ABS_SRCTREE
 224 --------------------------------------------------
 225 Kbuild uses a relative path to point to the tree when possible. For instance,
 226 when building in the source tree, the source tree path is '.'
 227
 228 Setting this flag requests Kbuild to use absolute path to the source tree.
 229 There are some useful cases to do so, like when generating tag files with
 230 absolute path entries etc.
 231
 232 KBUILD_SIGN_PIN
 233 ---------------
 234 This variable allows a passphrase or PIN to be passed to the sign-file
 235 utility when signing kernel modules, if the private key requires such.
 236
 237 KBUILD_MODPOST_WARN
 238 -------------------
 239 KBUILD_MODPOST_WARN can be set to avoid errors in case of undefined
 240 symbols in the final module linking stage. It changes such errors
 241 into warnings.
 242
 243 KBUILD_MODPOST_NOFINAL
 244 ----------------------
 245 KBUILD_MODPOST_NOFINAL can be set to skip the final link of modules.
 246 This is solely useful to speed up test compiles.
 247
 248 KBUILD_EXTRA_SYMBOLS
 249 --------------------
 250 For modules that use symbols from other modules.
 251 See more details in modules.rst.
 252
 253 ALLSOURCE_ARCHS
 254 ---------------
 255 For tags/TAGS/cscope targets, you can specify more than one arch
 256 to be included in the databases, separated by blank space. E.g.::
 257
 258     $ make ALLSOURCE_ARCHS="x86 mips arm" tags
 259
 260 To get all available archs you can also specify all. E.g.::
 261
 262     $ make ALLSOURCE_ARCHS=all tags
 263
 264 KBUILD_BUILD_TIMESTAMP
 265 ----------------------
 266 Setting this to a date string overrides the timestamp used in the
 267 UTS_VERSION definition (uname -v in the running kernel). The value has to
 268 be a string that can be passed to date -d. The default value
 269 is the output of the date command at one point during build.
 270
 271 KBUILD_BUILD_USER, KBUILD_BUILD_HOST
 272 ------------------------------------
 273 These two variables allow to override the user@host string displayed during
 274 boot and in /proc/version. The default value is the output of the commands
 275 whoami and host, respectively.
 276
 277 LLVM
 278 ----
 279 If this variable is set to 1, Kbuild will use Clang and LLVM utilities instead
 280 of GCC and GNU binutils to build the kernel.