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