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