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