Annotation of linux/README, revision

1.1       root        1: 
                      2:  [ NOTE! As of linux-0.97.pl5, the linux kernel include-files have
                      3:    finally been totally integrated with the normal headers.  That means
                      4:    no more "-nostdinc -I$(KERNELHDRS)" in the Makefiles etc, but it
                      5:    also means that you /have/ to have the correct /usr/include/linux
                      6:    and ../asm symlinks. See "Basic configuration 2" ]
                      8:        VERY QUICK AND DIRTY README
                      9:            by Lars Wirzenius
                     11: This is the README for the Linux kernel sources.  It tells a few small
                     12: things about kernel configuration and other things that can perhaps be
                     13: useful if you want to compile the kernel from scratch.  It leaves out a
                     14: lot as well, probably because the person who wrote it doesn't understand
                     15: very much about operating systems.  Linus did his best to help, but all
                     16: problems this causes are my fault. 
                     18: In order to compile this version of the kernel you need GCC 2.2.2 or
                     19: newer.  Some makefile targets require special commands which may not be
                     20: available on all machines (see below).  Normal utilities like ls etc are
                     21: not explicitly listed, they are assumed to be available on all systems. 
                     23: Kernel sources are usually kept in /usr/src/linux.  If you have them
                     24: elsewhere, you will have to change path names in a few places. 
                     25: Filenames that aren't absolute are supposed to be relative to the
                     26: toplevel kernel source directory. 
                     29: * Basic configuration
                     31: 1.  Edit Makefile: Check the definitions of macros ROOTDEV, KEYBOARD,
                     32: MATH_EMULATION, RAMDISK and SVGA_MODE before you run make.  They are
                     33: explained in the Makefile.  MATH_EMULATION does not hurt much even if
                     34: you have an FPU (387 or a 486 with a built in FPU), since Linux uses
                     35: the FPU if it finds one, even with MATH_EMULATION defined.  The kernel
                     36: will be slightly bigger.  It is probably not worth it to recompile the
                     37: kernel just to get rid of the emulation.
                     39: 2.  Create the symlinks:
                     41:        ln -fs /usr/src/linux/include/linux /usr/include/linux 
                     42:        ln -fs /usr/src/linux/include/asm /usr/include/asm
                     44: This is required so that the linux sources will correctly find their
                     45: header files - it is also used by the normal user-level header files to
                     46: get some system-specific information.
                     48: [ Linus' note2: This is automatically done by the gcc-2.2.2d and newer
                     49:   installation script, so if you have the new compiler, you should
                     50:   already have these links ]
                     52: * Things you may want to get rid of
                     54: 3.  To remove SCSI drivers, do this:
                     56:        - remove kernel/blk_drv/scsi/scsi.a from DRIVERS in the Makefile
                     57:        - remove the commands for the subdirs dependency in
                     58:          kernel/blk_drv/Makefile
                     59:        - add "#undef CONFIG_SCSI" to the end of include/linux/config.h
                     61: The SCSI drivers take a bit of memory, and also slow the bootup a bit,
                     62: so you may want to get rid of them if you don't have an SCSI drive.
                     64: 4.  The kernel contains code for the extended filesystem (extfs),
                     65: MS-DOS filesystem (dosfs) and proc-fs (proc), all of which are in
                     66: testing phases and are not recommended for real use yet.  If you don't
                     67: want to include these in the kernel, do the following:
                     69:        - remove references to these in the FILESYSTEMS macro in the
                     70:          root Makefile 
                     71:        - remove directory names from the SUBDIRS macro in fs/Makefile
                     72:        - remove the corresponding lines in the initialization of
                     73:          file_systems in fs/super.c.
                     75: 5.  The TCP/IP code is in the standard sources as of version 0.98, but
                     76: it is not compiled into the normal binary. To get TCP/IP working, you
                     77: have to:
                     79:        - edit 'net/Makefile', defining the SUBDIRS and SOCK_FLAGS
                     80:          variables correctly (currently commented out).  Likewise, you
                     81:          have to edit the rule for linking net.o in the Makefile (again
                     82:          removing a '#' to make tcp/tcpip.o active)
                     83:        - make sure you have the /usr/include/netinet/protocols.h header
                     84:          file.  If you don't have it, you should be able to find it at
                     85:          the same place you got the kernel, or with a newer compiler
                     86:          version.
                     87:        - remove all object (*.o) files in the net/ subdirectory, making
                     88:          sure that they are recompiled with the correct Makefile
                     89:          definitions.
                     90:        - Additionally, you obviously need the tcp/ip programs to make any
                     91:          use of the kernel feature.  If you haven't joined the TCP/IP
                     92:          mailing list, do so. 
                     95: * Running make
                     97: [ Linus' note3: if you have problems with make not working correctly,
                     98:   get a new copy of GNU make. pmake may or may not work due to the
                     99:   macro inheritation assumptions etc ]
                    101: Unless you know what you're doing, don't ever run the makefiles in
                    102: subdirectories by hand.  There is a bit of interaction between the
                    103: various makefiles, e.g. in the form of inherited macros and the like.
                    105: The following targets all apply for the makefile at the root of the
                    106: kernel source tree.
                    108: "make" or "make all" compiles everything.
                    110: "make Image" is like "make all", but it doesn't bump the number in
                    111: .version, which tells how many times this version has been compiled
                    112: (helps you differentiate between different configurations etc).
                    114: "make disk" is like "make Image", but it additionally writes out a copy
                    115: of the boot image to a floppy in your first floppy drive (/dev/fd0;
                    116: change the filename if you want a different floppy).  You need to have
                    117: a formatted, overwritable floppy in that drive when it is time to do the
                    118: copy.  This requires dd.
                    120: "make dep" updates all dependencies.  This requires sed.  It modifies
                    121: the makefiles directly (the end of them, starting at the ###Dependencies
                    122: -line at the end).  "make dep" is required after patching, or the kernel
                    123: may not compile cleanly. 
                    125: "make clean" will remove all object files and other files created by the
                    126: compilation.  This requires basename.
                    128: You may wish to redirect compiler error messages to a file so that you
                    129: can review them later and to ease problem fixing.  You can do this with
                    130: Bash with:
                    132:        make something 2>&1 | tee make.out
                    134: The tee part is so that you can check what is going on while the
                    135: compilation runs.  If you have GNU emacs and use M-x compile you don't
                    136: need this, of course.
                    138:                Lars Wirzenius