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