root/README

/* */

 [ NOTE! As of linux-0.97.pl5, the linux kernel include-files have
   finally been totally integrated with the normal headers.  That means
   no more "-nostdinc -I$(KERNELHDRS)" in the Makefiles etc, but it
   also means that you /have/ to have the correct /usr/include/linux
   and ../asm symlinks. See "Basic configuration 2" ]

        VERY QUICK AND DIRTY README
            by Lars Wirzenius

This is the README for the Linux kernel sources.  It tells a few small
things about kernel configuration and other things that can perhaps be
useful if you want to compile the kernel from scratch.  It leaves out a
lot as well, probably because the person who wrote it doesn't understand
very much about operating systems.  Linus did his best to help, but all
problems this causes are my fault. 

In order to compile this version of the kernel you need GCC 2.2.2 or
newer.  Some makefile targets require special commands which may not be
available on all machines (see below).  Normal utilities like ls etc are
not explicitly listed, they are assumed to be available on all systems. 

Kernel sources are usually kept in /usr/src/linux.  If you have them
elsewhere, you will have to change path names in a few places. 
Filenames that aren't absolute are supposed to be relative to the
toplevel kernel source directory. 


* Basic configuration

1.  Edit Makefile: Check the definitions of macros ROOTDEV, KEYBOARD,
MATH_EMULATION, RAMDISK and SVGA_MODE before you run make.  They are
explained in the Makefile.  MATH_EMULATION does not hurt much even if
you have an FPU (387 or a 486 with a built in FPU), since Linux uses
the FPU if it finds one, even with MATH_EMULATION defined.  The kernel
will be slightly bigger.  It is probably not worth it to recompile the
kernel just to get rid of the emulation.

2.  Create the symlinks:

        ln -fs /usr/src/linux/include/linux /usr/include/linux 
        ln -fs /usr/src/linux/include/asm /usr/include/asm

This is required so that the linux sources will correctly find their
header files - it is also used by the normal user-level header files to
get some system-specific information.

[ Linus' note2: This is automatically done by the gcc-2.2.2d and newer
  installation script, so if you have the new compiler, you should
  already have these links ]

* Things you may want to get rid of

3.  To remove SCSI drivers, do this:

        - remove kernel/blk_drv/scsi/scsi.a from DRIVERS in the Makefile
        - remove the commands for the subdirs dependency in
          kernel/blk_drv/Makefile
        - add "#undef CONFIG_SCSI" to the end of include/linux/config.h

The SCSI drivers take a bit of memory, and also slow the bootup a bit,
so you may want to get rid of them if you don't have an SCSI drive.

4.  The kernel contains code for the extended filesystem (extfs),
MS-DOS filesystem (dosfs) and proc-fs (proc), all of which are in
testing phases and are not recommended for real use yet.  If you don't
want to include these in the kernel, do the following:

        - remove references to these in the FILESYSTEMS macro in the
          root Makefile 
        - remove directory names from the SUBDIRS macro in fs/Makefile
        - remove the corresponding lines in the initialization of
          file_systems in fs/super.c.

5.  The TCP/IP code is in the standard sources as of version 0.98, but
it is not compiled into the normal binary. To get TCP/IP working, you
have to:

        - edit 'net/Makefile', defining the SUBDIRS and SOCK_FLAGS
          variables correctly (currently commented out).  Likewise, you
          have to edit the rule for linking net.o in the Makefile (again
          removing a '#' to make tcp/tcpip.o active)
        - make sure you have the /usr/include/netinet/protocols.h header
          file.  If you don't have it, you should be able to find it at
          the same place you got the kernel, or with a newer compiler
          version.
        - remove all object (*.o) files in the net/ subdirectory, making
          sure that they are recompiled with the correct Makefile
          definitions.
        - Additionally, you obviously need the tcp/ip programs to make any
          use of the kernel feature.  If you haven't joined the TCP/IP
          mailing list, do so. 


* Running make

[ Linus' note3: if you have problems with make not working correctly,
  get a new copy of GNU make. pmake may or may not work due to the
  macro inheritation assumptions etc ]

Unless you know what you're doing, don't ever run the makefiles in
subdirectories by hand.  There is a bit of interaction between the
various makefiles, e.g. in the form of inherited macros and the like.

The following targets all apply for the makefile at the root of the
kernel source tree.

"make" or "make all" compiles everything.

"make Image" is like "make all", but it doesn't bump the number in
.version, which tells how many times this version has been compiled
(helps you differentiate between different configurations etc).

"make disk" is like "make Image", but it additionally writes out a copy
of the boot image to a floppy in your first floppy drive (/dev/fd0;
change the filename if you want a different floppy).  You need to have
a formatted, overwritable floppy in that drive when it is time to do the
copy.  This requires dd.

"make dep" updates all dependencies.  This requires sed.  It modifies
the makefiles directly (the end of them, starting at the ###Dependencies
-line at the end).  "make dep" is required after patching, or the kernel
may not compile cleanly. 

"make clean" will remove all object files and other files created by the
compilation.  This requires basename.

You may wish to redirect compiler error messages to a file so that you
can review them later and to ease problem fixing.  You can do this with
Bash with:

        make something 2>&1 | tee make.out

The tee part is so that you can check what is going on while the
compilation runs.  If you have GNU emacs and use M-x compile you don't
need this, of course.

                Lars Wirzenius

/* */