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