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