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