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 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 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.a 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 Mkinitrd
 160 --------
 161
 162 These changes to the ``/lib/modules`` file tree layout also require that
 163 mkinitrd be upgraded.
 164
 165 E2fsprogs
 166 ---------
 167
 168 The latest version of ``e2fsprogs`` fixes several bugs in fsck and
 169 debugfs.  Obviously, it's a good idea to upgrade.
 170
 171 JFSutils
 172 --------
 173
 174 The ``jfsutils`` package contains the utilities for the file system.
 175 The following utilities are available:
 176
 177 - ``fsck.jfs`` - initiate replay of the transaction log, and check
 178   and repair a JFS formatted partition.
 179
 180 - ``mkfs.jfs`` - create a JFS formatted partition.
 181
 182 - other file system utilities are also available in this package.
 183
 184 Reiserfsprogs
 185 -------------
 186
 187 The reiserfsprogs package should be used for reiserfs-3.6.x
 188 (Linux kernels 2.4.x). It is a combined package and contains working
 189 versions of ``mkreiserfs``, ``resize_reiserfs``, ``debugreiserfs`` and
 190 ``reiserfsck``. These utils work on both i386 and alpha platforms.
 191
 192 Xfsprogs
 193 --------
 194
 195 The latest version of ``xfsprogs`` contains ``mkfs.xfs``, ``xfs_db``, and the
 196 ``xfs_repair`` utilities, among others, for the XFS filesystem.  It is
 197 architecture independent and any version from 2.0.0 onward should
 198 work correctly with this version of the XFS kernel code (2.6.0 or
 199 later is recommended, due to some significant improvements).
 200
 201 PCMCIAutils
 202 -----------
 203
 204 PCMCIAutils replaces ``pcmcia-cs``. It properly sets up
 205 PCMCIA sockets at system startup and loads the appropriate modules
 206 for 16-bit PCMCIA devices if the kernel is modularized and the hotplug
 207 subsystem is used.
 208
 209 Quota-tools
 210 -----------
 211
 212 Support for 32 bit uid's and gid's is required if you want to use
 213 the newer version 2 quota format.  Quota-tools version 3.07 and
 214 newer has this support.  Use the recommended version or newer
 215 from the table above.
 216
 217 Intel IA32 microcode
 218 --------------------
 219
 220 A driver has been added to allow updating of Intel IA32 microcode,
 221 accessible as a normal (misc) character device.  If you are not using
 222 udev you may need to::
 223
 224   mkdir /dev/cpu
 225   mknod /dev/cpu/microcode c 10 184
 226   chmod 0644 /dev/cpu/microcode
 227
 228 as root before you can use this.  You'll probably also want to
 229 get the user-space microcode_ctl utility to use with this.
 230
 231 udev
 232 ----
 233
 234 ``udev`` is a userspace application for populating ``/dev`` dynamically with
 235 only entries for devices actually present. ``udev`` replaces the basic
 236 functionality of devfs, while allowing persistent device naming for
 237 devices.
 238
 239 FUSE
 240 ----
 241
 242 Needs libfuse 2.4.0 or later.  Absolute minimum is 2.3.0 but mount
 243 options ``direct_io`` and ``kernel_cache`` won't work.
 244
 245 Networking
 246 **********
 247
 248 General changes
 249 ---------------
 250
 251 If you have advanced network configuration needs, you should probably
 252 consider using the network tools from ip-route2.
 253
 254 Packet Filter / NAT
 255 -------------------
 256 The packet filtering and NAT code uses the same tools like the previous 2.4.x
 257 kernel series (iptables).  It still includes backwards-compatibility modules
 258 for 2.2.x-style ipchains and 2.0.x-style ipfwadm.
 259
 260 PPP
 261 ---
 262
 263 The PPP driver has been restructured to support multilink and to
 264 enable it to operate over diverse media layers.  If you use PPP,
 265 upgrade pppd to at least 2.4.0.
 266
 267 If you are not using udev, you must have the device file /dev/ppp
 268 which can be made by::
 269
 270   mknod /dev/ppp c 108 0
 271
 272 as root.
 273
 274 Isdn4k-utils
 275 ------------
 276
 277 Due to changes in the length of the phone number field, isdn4k-utils
 278 needs to be recompiled or (preferably) upgraded.
 279
 280 NFS-utils
 281 ---------
 282
 283 In ancient (2.4 and earlier) kernels, the nfs server needed to know
 284 about any client that expected to be able to access files via NFS.  This
 285 information would be given to the kernel by ``mountd`` when the client
 286 mounted the filesystem, or by ``exportfs`` at system startup.  exportfs
 287 would take information about active clients from ``/var/lib/nfs/rmtab``.
 288
 289 This approach is quite fragile as it depends on rmtab being correct
 290 which is not always easy, particularly when trying to implement
 291 fail-over.  Even when the system is working well, ``rmtab`` suffers from
 292 getting lots of old entries that never get removed.
 293
 294 With modern kernels we have the option of having the kernel tell mountd
 295 when it gets a request from an unknown host, and mountd can give
 296 appropriate export information to the kernel.  This removes the
 297 dependency on ``rmtab`` and means that the kernel only needs to know about
 298 currently active clients.
 299
 300 To enable this new functionality, you need to::
 301
 302   mount -t nfsd nfsd /proc/fs/nfsd
 303
 304 before running exportfs or mountd.  It is recommended that all NFS
 305 services be protected from the internet-at-large by a firewall where
 306 that is possible.
 307
 308 mcelog
 309 ------
 310
 311 On x86 kernels the mcelog utility is needed to process and log machine check
 312 events when ``CONFIG_X86_MCE`` is enabled. Machine check events are errors
 313 reported by the CPU. Processing them is strongly encouraged.
 314
 315 Kernel documentation
 316 ********************
 317
 318 Sphinx
 319 ------
 320
 321 Please see :ref:`sphinx_install` in ``Documentation/doc-guide/sphinx.rst``
 322 for details about Sphinx requirements.
 323
 324 Getting updated software
 325 ========================
 326
 327 Kernel compilation
 328 ******************
 329
 330 gcc
 331 ---
 332
 333 - <ftp://ftp.gnu.org/gnu/gcc/>
 334
 335 Make
 336 ----
 337
 338 - <ftp://ftp.gnu.org/gnu/make/>
 339
 340 Binutils
 341 --------
 342
 343 - <https://www.kernel.org/pub/linux/devel/binutils/>
 344
 345 Flex
 346 ----
 347
 348 - <https://github.com/westes/flex/releases>
 349
 350 Bison
 351 -----
 352
 353 - <ftp://ftp.gnu.org/gnu/bison/>
 354
 355 OpenSSL
 356 -------
 357
 358 - <https://www.openssl.org/>
 359
 360 System utilities
 361 ****************
 362
 363 Util-linux
 364 ----------
 365
 366 - <https://www.kernel.org/pub/linux/utils/util-linux/>
 367
 368 Kmod
 369 ----
 370
 371 - <https://www.kernel.org/pub/linux/utils/kernel/kmod/>
 372 - <https://git.kernel.org/pub/scm/utils/kernel/kmod/kmod.git>
 373
 374 Ksymoops
 375 --------
 376
 377 - <https://www.kernel.org/pub/linux/utils/kernel/ksymoops/v2.4/>
 378
 379 Mkinitrd
 380 --------
 381
 382 - <https://code.launchpad.net/initrd-tools/main>
 383
 384 E2fsprogs
 385 ---------
 386
 387 - <http://prdownloads.sourceforge.net/e2fsprogs/e2fsprogs-1.29.tar.gz>
 388
 389 JFSutils
 390 --------
 391
 392 - <http://jfs.sourceforge.net/>
 393
 394 Reiserfsprogs
 395 -------------
 396
 397 - <http://www.kernel.org/pub/linux/utils/fs/reiserfs/>
 398
 399 Xfsprogs
 400 --------
 401
 402 - <ftp://oss.sgi.com/projects/xfs/>
 403
 404 Pcmciautils
 405 -----------
 406
 407 - <https://www.kernel.org/pub/linux/utils/kernel/pcmcia/>
 408
 409 Quota-tools
 410 -----------
 411
 412 - <http://sourceforge.net/projects/linuxquota/>
 413
 414
 415 Intel P6 microcode
 416 ------------------
 417
 418 - <https://downloadcenter.intel.com/>
 419
 420 udev
 421 ----
 422
 423 - <http://www.freedesktop.org/software/systemd/man/udev.html>
 424
 425 FUSE
 426 ----
 427
 428 - <https://github.com/libfuse/libfuse/releases>
 429
 430 mcelog
 431 ------
 432
 433 - <http://www.mcelog.org/>
 434
 435 Networking
 436 **********
 437
 438 PPP
 439 ---
 440
 441 - <ftp://ftp.samba.org/pub/ppp/>
 442
 443 Isdn4k-utils
 444 ------------
 445
 446 - <ftp://ftp.isdn4linux.de/pub/isdn4linux/utils/>
 447
 448 NFS-utils
 449 ---------
 450
 451 - <http://sourceforge.net/project/showfiles.php?group_id=14>
 452
 453 Iptables
 454 --------
 455
 456 - <http://www.iptables.org/downloads.html>
 457
 458 Ip-route2
 459 ---------
 460
 461 - <https://www.kernel.org/pub/linux/utils/net/iproute2/>
 462
 463 OProfile
 464 --------
 465
 466 - <http://oprofile.sf.net/download/>
 467
 468 NFS-Utils
 469 ---------
 470
 471 - <http://nfs.sourceforge.net/>
 472
 473 Kernel documentation
 474 ********************
 475
 476 Sphinx
 477 ------
 478
 479 - <http://www.sphinx-doc.org/>