Documentation/process/changes.rst

   1 .. _changes:
   2
   3 Minimal requirements to compile the Kernel
   4 ++++++++++++++++++++++++++++++++++++++++++
   5
   6 Intro
   7 =====
   8
   9 This document is designed to provide a list of the minimum levels of
  10 software necessary to run the current kernel version.
  11
  12 This document is originally based on my "Changes" file for 2.0.x kernels
  13 and therefore owes credit to the same people as that file (Jared Mauch,
  14 Axel Boldt, Alessandro Sigala, and countless other users all over the
  15 'net).
  16
  17 Current Minimal Requirements
  18 ****************************
  19
  20 Upgrade to at **least** these software revisions before thinking you've
  21 encountered a bug!  If you're unsure what version you're currently
  22 running, the suggested command should tell you.
  23
  24 Again, keep in mind that this list assumes you are already functionally
  25 running a Linux kernel.  Also, not all tools are necessary on all
  26 systems; obviously, if you don't have any PC Card hardware, for example,
  27 you probably needn't concern yourself with pcmciautils.
  28
  29 ====================== ===============  ========================================
  30         Program        Minimal version       Command to check the version
  31 ====================== ===============  ========================================
  32 GNU C                  5.1              gcc --version
  33 Clang/LLVM (optional)  11.0.0           clang --version
  34 Rust (optional)        1.68.2           rustc --version
  35 bindgen (optional)     0.56.0           bindgen --version
  36 GNU make               3.82             make --version
  37 bash                   4.2              bash --version
  38 binutils               2.25             ld -v
  39 flex                   2.5.35           flex --version
  40 bison                  2.0              bison --version
  41 pahole                 1.16             pahole --version
  42 util-linux             2.10o            fdformat --version
  43 kmod                   13               depmod -V
  44 e2fsprogs              1.41.4           e2fsck -V
  45 jfsutils               1.1.3            fsck.jfs -V
  46 reiserfsprogs          3.6.3            reiserfsck -V
  47 xfsprogs               2.6.0            xfs_db -V
  48 squashfs-tools         4.0              mksquashfs -version
  49 btrfs-progs            0.18             btrfsck
  50 pcmciautils            004              pccardctl -V
  51 quota-tools            3.09             quota -V
  52 PPP                    2.4.0            pppd --version
  53 nfs-utils              1.0.5            showmount --version
  54 procps                 3.2.0            ps --version
  55 udev                   081              udevd --version
  56 grub                   0.93             grub --version || grub-install --version
  57 mcelog                 0.6              mcelog --version
  58 iptables               1.4.2            iptables -V
  59 openssl & libcrypto    1.0.0            openssl version
  60 bc                     1.06.95          bc --version
  61 Sphinx\ [#f1]_         1.7              sphinx-build --version
  62 cpio                   any              cpio --version
  63 ====================== ===============  ========================================
  64
  65 .. [#f1] Sphinx is needed only to build the Kernel documentation
  66
  67 Kernel compilation
  68 ******************
  69
  70 GCC
  71 ---
  72
  73 The gcc version requirements may vary depending on the type of CPU in your
  74 computer.
  75
  76 Clang/LLVM (optional)
  77 ---------------------
  78
  79 The latest formal release of clang and LLVM utils (according to
  80 `releases.llvm.org <https://releases.llvm.org>`_) are supported for building
  81 kernels. Older releases aren't guaranteed to work, and we may drop workarounds
  82 from the kernel that were used to support older versions. Please see additional
  83 docs on :ref:`Building Linux with Clang/LLVM <kbuild_llvm>`.
  84
  85 Rust (optional)
  86 ---------------
  87
  88 A particular version of the Rust toolchain is required. Newer versions may or
  89 may not work because the kernel depends on some unstable Rust features, for
  90 the moment.
  91
  92 Each Rust toolchain comes with several "components", some of which are required
  93 (like ``rustc``) and some that are optional. The ``rust-src`` component (which
  94 is optional) needs to be installed to build the kernel. Other components are
  95 useful for developing.
  96
  97 Please see Documentation/rust/quick-start.rst for instructions on how to
  98 satisfy the build requirements of Rust support. In particular, the ``Makefile``
  99 target ``rustavailable`` is useful to check why the Rust toolchain may not
 100 be detected.
 101
 102 bindgen (optional)
 103 ------------------
 104
 105 ``bindgen`` is used to generate the Rust bindings to the C side of the kernel.
 106 It depends on ``libclang``.
 107
 108 Make
 109 ----
 110
 111 You will need GNU make 3.82 or later to build the kernel.
 112
 113 Bash
 114 ----
 115
 116 Some bash scripts are used for the kernel build.
 117 Bash 4.2 or newer is needed.
 118
 119 Binutils
 120 --------
 121
 122 Binutils 2.25 or newer is needed to build the kernel.
 123
 124 pkg-config
 125 ----------
 126
 127 The build system, as of 4.18, requires pkg-config to check for installed
 128 kconfig tools and to determine flags settings for use in
 129 'make {g,x}config'.  Previously pkg-config was being used but not
 130 verified or documented.
 131
 132 Flex
 133 ----
 134
 135 Since Linux 4.16, the build system generates lexical analyzers
 136 during build.  This requires flex 2.5.35 or later.
 137
 138
 139 Bison
 140 -----
 141
 142 Since Linux 4.16, the build system generates parsers
 143 during build.  This requires bison 2.0 or later.
 144
 145 pahole:
 146 -------
 147
 148 Since Linux 5.2, if CONFIG_DEBUG_INFO_BTF is selected, the build system
 149 generates BTF (BPF Type Format) from DWARF in vmlinux, a bit later from kernel
 150 modules as well.  This requires pahole v1.16 or later.
 151
 152 It is found in the 'dwarves' or 'pahole' distro packages or from
 153 https://fedorapeople.org/~acme/dwarves/.
 154
 155 Perl
 156 ----
 157
 158 You will need perl 5 and the following modules: ``Getopt::Long``,
 159 ``Getopt::Std``, ``File::Basename``, and ``File::Find`` to build the kernel.
 160
 161 BC
 162 --
 163
 164 You will need bc to build kernels 3.10 and higher
 165
 166
 167 OpenSSL
 168 -------
 169
 170 Module signing and external certificate handling use the OpenSSL program and
 171 crypto library to do key creation and signature generation.
 172
 173 You will need openssl to build kernels 3.7 and higher if module signing is
 174 enabled.  You will also need openssl development packages to build kernels 4.3
 175 and higher.
 176
 177
 178 System utilities
 179 ****************
 180
 181 Architectural changes
 182 ---------------------
 183
 184 DevFS has been obsoleted in favour of udev
 185 (https://www.kernel.org/pub/linux/utils/kernel/hotplug/)
 186
 187 32-bit UID support is now in place.  Have fun!
 188
 189 Linux documentation for functions is transitioning to inline
 190 documentation via specially-formatted comments near their
 191 definitions in the source.  These comments can be combined with ReST
 192 files the Documentation/ directory to make enriched documentation, which can
 193 then be converted to PostScript, HTML, LaTex, ePUB and PDF files.
 194 In order to convert from ReST format to a format of your choice, you'll need
 195 Sphinx.
 196
 197 Util-linux
 198 ----------
 199
 200 New versions of util-linux provide ``fdisk`` support for larger disks,
 201 support new options to mount, recognize more supported partition
 202 types, have a fdformat which works with 2.4 kernels, and similar goodies.
 203 You'll probably want to upgrade.
 204
 205 Ksymoops
 206 --------
 207
 208 If the unthinkable happens and your kernel oopses, you may need the
 209 ksymoops tool to decode it, but in most cases you don't.
 210 It is generally preferred to build the kernel with ``CONFIG_KALLSYMS`` so
 211 that it produces readable dumps that can be used as-is (this also
 212 produces better output than ksymoops).  If for some reason your kernel
 213 is not build with ``CONFIG_KALLSYMS`` and you have no way to rebuild and
 214 reproduce the Oops with that option, then you can still decode that Oops
 215 with ksymoops.
 216
 217 Mkinitrd
 218 --------
 219
 220 These changes to the ``/lib/modules`` file tree layout also require that
 221 mkinitrd be upgraded.
 222
 223 E2fsprogs
 224 ---------
 225
 226 The latest version of ``e2fsprogs`` fixes several bugs in fsck and
 227 debugfs.  Obviously, it's a good idea to upgrade.
 228
 229 JFSutils
 230 --------
 231
 232 The ``jfsutils`` package contains the utilities for the file system.
 233 The following utilities are available:
 234
 235 - ``fsck.jfs`` - initiate replay of the transaction log, and check
 236   and repair a JFS formatted partition.
 237
 238 - ``mkfs.jfs`` - create a JFS formatted partition.
 239
 240 - other file system utilities are also available in this package.
 241
 242 Reiserfsprogs
 243 -------------
 244
 245 The reiserfsprogs package should be used for reiserfs-3.6.x
 246 (Linux kernels 2.4.x). It is a combined package and contains working
 247 versions of ``mkreiserfs``, ``resize_reiserfs``, ``debugreiserfs`` and
 248 ``reiserfsck``. These utils work on both i386 and alpha platforms.
 249
 250 Xfsprogs
 251 --------
 252
 253 The latest version of ``xfsprogs`` contains ``mkfs.xfs``, ``xfs_db``, and the
 254 ``xfs_repair`` utilities, among others, for the XFS filesystem.  It is
 255 architecture independent and any version from 2.0.0 onward should
 256 work correctly with this version of the XFS kernel code (2.6.0 or
 257 later is recommended, due to some significant improvements).
 258
 259 PCMCIAutils
 260 -----------
 261
 262 PCMCIAutils replaces ``pcmcia-cs``. It properly sets up
 263 PCMCIA sockets at system startup and loads the appropriate modules
 264 for 16-bit PCMCIA devices if the kernel is modularized and the hotplug
 265 subsystem is used.
 266
 267 Quota-tools
 268 -----------
 269
 270 Support for 32 bit uid's and gid's is required if you want to use
 271 the newer version 2 quota format.  Quota-tools version 3.07 and
 272 newer has this support.  Use the recommended version or newer
 273 from the table above.
 274
 275 Intel IA32 microcode
 276 --------------------
 277
 278 A driver has been added to allow updating of Intel IA32 microcode,
 279 accessible as a normal (misc) character device.  If you are not using
 280 udev you may need to::
 281
 282   mkdir /dev/cpu
 283   mknod /dev/cpu/microcode c 10 184
 284   chmod 0644 /dev/cpu/microcode
 285
 286 as root before you can use this.  You'll probably also want to
 287 get the user-space microcode_ctl utility to use with this.
 288
 289 udev
 290 ----
 291
 292 ``udev`` is a userspace application for populating ``/dev`` dynamically with
 293 only entries for devices actually present. ``udev`` replaces the basic
 294 functionality of devfs, while allowing persistent device naming for
 295 devices.
 296
 297 FUSE
 298 ----
 299
 300 Needs libfuse 2.4.0 or later.  Absolute minimum is 2.3.0 but mount
 301 options ``direct_io`` and ``kernel_cache`` won't work.
 302
 303 Networking
 304 **********
 305
 306 General changes
 307 ---------------
 308
 309 If you have advanced network configuration needs, you should probably
 310 consider using the network tools from ip-route2.
 311
 312 Packet Filter / NAT
 313 -------------------
 314 The packet filtering and NAT code uses the same tools like the previous 2.4.x
 315 kernel series (iptables).  It still includes backwards-compatibility modules
 316 for 2.2.x-style ipchains and 2.0.x-style ipfwadm.
 317
 318 PPP
 319 ---
 320
 321 The PPP driver has been restructured to support multilink and to
 322 enable it to operate over diverse media layers.  If you use PPP,
 323 upgrade pppd to at least 2.4.0.
 324
 325 If you are not using udev, you must have the device file /dev/ppp
 326 which can be made by::
 327
 328   mknod /dev/ppp c 108 0
 329
 330 as root.
 331
 332 NFS-utils
 333 ---------
 334
 335 In ancient (2.4 and earlier) kernels, the nfs server needed to know
 336 about any client that expected to be able to access files via NFS.  This
 337 information would be given to the kernel by ``mountd`` when the client
 338 mounted the filesystem, or by ``exportfs`` at system startup.  exportfs
 339 would take information about active clients from ``/var/lib/nfs/rmtab``.
 340
 341 This approach is quite fragile as it depends on rmtab being correct
 342 which is not always easy, particularly when trying to implement
 343 fail-over.  Even when the system is working well, ``rmtab`` suffers from
 344 getting lots of old entries that never get removed.
 345
 346 With modern kernels we have the option of having the kernel tell mountd
 347 when it gets a request from an unknown host, and mountd can give
 348 appropriate export information to the kernel.  This removes the
 349 dependency on ``rmtab`` and means that the kernel only needs to know about
 350 currently active clients.
 351
 352 To enable this new functionality, you need to::
 353
 354   mount -t nfsd nfsd /proc/fs/nfsd
 355
 356 before running exportfs or mountd.  It is recommended that all NFS
 357 services be protected from the internet-at-large by a firewall where
 358 that is possible.
 359
 360 mcelog
 361 ------
 362
 363 On x86 kernels the mcelog utility is needed to process and log machine check
 364 events when ``CONFIG_X86_MCE`` is enabled. Machine check events are errors
 365 reported by the CPU. Processing them is strongly encouraged.
 366
 367 Kernel documentation
 368 ********************
 369
 370 Sphinx
 371 ------
 372
 373 Please see :ref:`sphinx_install` in :ref:`Documentation/doc-guide/sphinx.rst <sphinxdoc>`
 374 for details about Sphinx requirements.
 375
 376 rustdoc
 377 -------
 378
 379 ``rustdoc`` is used to generate the documentation for Rust code. Please see
 380 Documentation/rust/general-information.rst for more information.
 381
 382 Getting updated software
 383 ========================
 384
 385 Kernel compilation
 386 ******************
 387
 388 gcc
 389 ---
 390
 391 - <ftp://ftp.gnu.org/gnu/gcc/>
 392
 393 Clang/LLVM
 394 ----------
 395
 396 - :ref:`Getting LLVM <getting_llvm>`.
 397
 398 Rust
 399 ----
 400
 401 - Documentation/rust/quick-start.rst.
 402
 403 bindgen
 404 -------
 405
 406 - Documentation/rust/quick-start.rst.
 407
 408 Make
 409 ----
 410
 411 - <ftp://ftp.gnu.org/gnu/make/>
 412
 413 Bash
 414 ----
 415
 416 - <ftp://ftp.gnu.org/gnu/bash/>
 417
 418 Binutils
 419 --------
 420
 421 - <https://www.kernel.org/pub/linux/devel/binutils/>
 422
 423 Flex
 424 ----
 425
 426 - <https://github.com/westes/flex/releases>
 427
 428 Bison
 429 -----
 430
 431 - <ftp://ftp.gnu.org/gnu/bison/>
 432
 433 OpenSSL
 434 -------
 435
 436 - <https://www.openssl.org/>
 437
 438 System utilities
 439 ****************
 440
 441 Util-linux
 442 ----------
 443
 444 - <https://www.kernel.org/pub/linux/utils/util-linux/>
 445
 446 Kmod
 447 ----
 448
 449 - <https://www.kernel.org/pub/linux/utils/kernel/kmod/>
 450 - <https://git.kernel.org/pub/scm/utils/kernel/kmod/kmod.git>
 451
 452 Ksymoops
 453 --------
 454
 455 - <https://www.kernel.org/pub/linux/utils/kernel/ksymoops/v2.4/>
 456
 457 Mkinitrd
 458 --------
 459
 460 - <https://code.launchpad.net/initrd-tools/main>
 461
 462 E2fsprogs
 463 ---------
 464
 465 - <https://www.kernel.org/pub/linux/kernel/people/tytso/e2fsprogs/>
 466 - <https://git.kernel.org/pub/scm/fs/ext2/e2fsprogs.git/>
 467
 468 JFSutils
 469 --------
 470
 471 - <http://jfs.sourceforge.net/>
 472
 473 Reiserfsprogs
 474 -------------
 475
 476 - <https://git.kernel.org/pub/scm/linux/kernel/git/jeffm/reiserfsprogs.git/>
 477
 478 Xfsprogs
 479 --------
 480
 481 - <https://git.kernel.org/pub/scm/fs/xfs/xfsprogs-dev.git>
 482 - <https://www.kernel.org/pub/linux/utils/fs/xfs/xfsprogs/>
 483
 484 Pcmciautils
 485 -----------
 486
 487 - <https://www.kernel.org/pub/linux/utils/kernel/pcmcia/>
 488
 489 Quota-tools
 490 -----------
 491
 492 - <http://sourceforge.net/projects/linuxquota/>
 493
 494
 495 Intel P6 microcode
 496 ------------------
 497
 498 - <https://downloadcenter.intel.com/>
 499
 500 udev
 501 ----
 502
 503 - <https://www.freedesktop.org/software/systemd/man/udev.html>
 504
 505 FUSE
 506 ----
 507
 508 - <https://github.com/libfuse/libfuse/releases>
 509
 510 mcelog
 511 ------
 512
 513 - <http://www.mcelog.org/>
 514
 515 cpio
 516 ----
 517
 518 - <https://www.gnu.org/software/cpio/>
 519
 520 Networking
 521 **********
 522
 523 PPP
 524 ---
 525
 526 - <https://download.samba.org/pub/ppp/>
 527 - <https://git.ozlabs.org/?p=ppp.git>
 528 - <https://github.com/paulusmack/ppp/>
 529
 530 NFS-utils
 531 ---------
 532
 533 - <http://sourceforge.net/project/showfiles.php?group_id=14>
 534
 535 Iptables
 536 --------
 537
 538 - <https://netfilter.org/projects/iptables/index.html>
 539
 540 Ip-route2
 541 ---------
 542
 543 - <https://www.kernel.org/pub/linux/utils/net/iproute2/>
 544
 545 OProfile
 546 --------
 547
 548 - <http://oprofile.sf.net/download/>
 549
 550 NFS-Utils
 551 ---------
 552
 553 - <http://nfs.sourceforge.net/>
 554
 555 Kernel documentation
 556 ********************
 557
 558 Sphinx
 559 ------
 560
 561 - <https://www.sphinx-doc.org/>