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