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.
 141
 142 The output directory can also be specified using "O=...".
 143
 144 Setting "O=..." takes precedence over KBUILD_OUTPUT.
 145
 146 KBUILD_EXTRA_WARN
 147 -----------------
 148 Specify the extra build checks. The same value can be assigned by passing
 149 W=... from the command line.
 150
 151 See `make help` for the list of the supported values.
 152
 153 Setting "W=..." takes precedence over KBUILD_EXTRA_WARN.
 154
 155 KBUILD_DEBARCH
 156 --------------
 157 For the deb-pkg target, allows overriding the normal heuristics deployed by
 158 deb-pkg. Normally deb-pkg attempts to guess the right architecture based on
 159 the UTS_MACHINE variable, and on some architectures also the kernel config.
 160 The value of KBUILD_DEBARCH is assumed (not checked) to be a valid Debian
 161 architecture.
 162
 163 KDOCFLAGS
 164 ---------
 165 Specify extra (warning/error) flags for kernel-doc checks during the build,
 166 see scripts/kernel-doc for which flags are supported. Note that this doesn't
 167 (currently) apply to documentation builds.
 168
 169 ARCH
 170 ----
 171 Set ARCH to the architecture to be built.
 172
 173 In most cases the name of the architecture is the same as the
 174 directory name found in the arch/ directory.
 175
 176 But some architectures such as x86 and sparc have aliases.
 177
 178 - x86: i386 for 32 bit, x86_64 for 64 bit
 179 - parisc: parisc64 for 64 bit
 180 - sparc: sparc32 for 32 bit, sparc64 for 64 bit
 181
 182 CROSS_COMPILE
 183 -------------
 184 Specify an optional fixed part of the binutils filename.
 185 CROSS_COMPILE can be a part of the filename or the full path.
 186
 187 CROSS_COMPILE is also used for ccache in some setups.
 188
 189 CF
 190 --
 191 Additional options for sparse.
 192
 193 CF is often used on the command-line like this::
 194
 195     make CF=-Wbitwise C=2
 196
 197 INSTALL_PATH
 198 ------------
 199 INSTALL_PATH specifies where to place the updated kernel and system map
 200 images. Default is /boot, but you can set it to other values.
 201
 202 INSTALLKERNEL
 203 -------------
 204 Install script called when using "make install".
 205 The default name is "installkernel".
 206
 207 The script will be called with the following arguments:
 208
 209    - $1 - kernel version
 210    - $2 - kernel image file
 211    - $3 - kernel map file
 212    - $4 - default install path (use root directory if blank)
 213
 214 The implementation of "make install" is architecture specific
 215 and it may differ from the above.
 216
 217 INSTALLKERNEL is provided to enable the possibility to
 218 specify a custom installer when cross compiling a kernel.
 219
 220 MODLIB
 221 ------
 222 Specify where to install modules.
 223 The default value is::
 224
 225      $(INSTALL_MOD_PATH)/lib/modules/$(KERNELRELEASE)
 226
 227 The value can be overridden in which case the default value is ignored.
 228
 229 INSTALL_MOD_PATH
 230 ----------------
 231 INSTALL_MOD_PATH specifies a prefix to MODLIB for module directory
 232 relocations required by build roots.  This is not defined in the
 233 makefile but the argument can be passed to make if needed.
 234
 235 INSTALL_MOD_STRIP
 236 -----------------
 237 INSTALL_MOD_STRIP, if defined, will cause modules to be
 238 stripped after they are installed.  If INSTALL_MOD_STRIP is '1', then
 239 the default option --strip-debug will be used.  Otherwise,
 240 INSTALL_MOD_STRIP value will be used as the options to the strip command.
 241
 242 INSTALL_HDR_PATH
 243 ----------------
 244 INSTALL_HDR_PATH specifies where to install user space headers when
 245 executing "make headers_*".
 246
 247 The default value is::
 248
 249     $(objtree)/usr
 250
 251 $(objtree) is the directory where output files are saved.
 252 The output directory is often set using "O=..." on the commandline.
 253
 254 The value can be overridden in which case the default value is ignored.
 255
 256 INSTALL_DTBS_PATH
 257 -----------------
 258 INSTALL_DTBS_PATH specifies where to install device tree blobs for
 259 relocations required by build roots.  This is not defined in the
 260 makefile but the argument can be passed to make if needed.
 261
 262 KBUILD_ABS_SRCTREE
 263 --------------------------------------------------
 264 Kbuild uses a relative path to point to the tree when possible. For instance,
 265 when building in the source tree, the source tree path is '.'
 266
 267 Setting this flag requests Kbuild to use absolute path to the source tree.
 268 There are some useful cases to do so, like when generating tag files with
 269 absolute path entries etc.
 270
 271 KBUILD_SIGN_PIN
 272 ---------------
 273 This variable allows a passphrase or PIN to be passed to the sign-file
 274 utility when signing kernel modules, if the private key requires such.
 275
 276 KBUILD_MODPOST_WARN
 277 -------------------
 278 KBUILD_MODPOST_WARN can be set to avoid errors in case of undefined
 279 symbols in the final module linking stage. It changes such errors
 280 into warnings.
 281
 282 KBUILD_MODPOST_NOFINAL
 283 ----------------------
 284 KBUILD_MODPOST_NOFINAL can be set to skip the final link of modules.
 285 This is solely useful to speed up test compiles.
 286
 287 KBUILD_EXTRA_SYMBOLS
 288 --------------------
 289 For modules that use symbols from other modules.
 290 See more details in modules.rst.
 291
 292 ALLSOURCE_ARCHS
 293 ---------------
 294 For tags/TAGS/cscope targets, you can specify more than one arch
 295 to be included in the databases, separated by blank space. E.g.::
 296
 297     $ make ALLSOURCE_ARCHS="x86 mips arm" tags
 298
 299 To get all available archs you can also specify all. E.g.::
 300
 301     $ make ALLSOURCE_ARCHS=all tags
 302
 303 IGNORE_DIRS
 304 -----------
 305 For tags/TAGS/cscope targets, you can choose which directories won't
 306 be included in the databases, separated by blank space. E.g.::
 307
 308     $ make IGNORE_DIRS="drivers/gpu/drm/radeon tools" cscope
 309
 310 KBUILD_BUILD_TIMESTAMP
 311 ----------------------
 312 Setting this to a date string overrides the timestamp used in the
 313 UTS_VERSION definition (uname -v in the running kernel). The value has to
 314 be a string that can be passed to date -d. The default value
 315 is the output of the date command at one point during build.
 316
 317 KBUILD_BUILD_USER, KBUILD_BUILD_HOST
 318 ------------------------------------
 319 These two variables allow to override the user@host string displayed during
 320 boot and in /proc/version. The default value is the output of the commands
 321 whoami and host, respectively.
 322
 323 LLVM
 324 ----
 325 If this variable is set to 1, Kbuild will use Clang and LLVM utilities instead
 326 of GCC and GNU binutils to build the kernel.