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