.TH BUILD 8
.SH NAME
build \- compile and install the kernel
.SH SYNOPSIS
.B build
.RI [ compile-options " ...]"
.SH DESCRIPTION
.B Build
compiles the kernel sources found in a subdirectory of
.BR /usr/src ,
(usually
.BR /usr/src/sys )
and installs the resulting kernel image in
.BR /minix .
.B Build
must be called from some subdirectory in the selected kernel source
directory if it is to know what it must compile.  It will use
.B /usr/src/sys
if called from
.BR /usr/src .
.PP
The kernel source tree has the following subdirectories:
.TP
.B kernel
The Minix kernel, the lowest layer of the operating system.  (The word
"kernel" is used both for this part of the operating system, and for the
whole combination.  What is meant is usually clear from context.)
.TP
.B mm
The Memory Manager.
.TP
.B fs
The File System.
.TP
.B task.stubs
Contains an "init" stub routine that calls
.BR /sbin/init .
Init needs not be present in the image at boot time, so it has been replaced
by a small stub.  (It could be put back if so needed.)
.TP
.B inet
The sources of the internetworking task.
.B Build
will not compile this task.  Init and inet are seen as normal commands and
are therefore compiled from the central Makefile.
.TP
.B tools
Contains the central Makefile to compile all the kernel parts and make an
image.  Usually contains the same images as
.B /minix
and all the images created in the last week.  The default action of the
Makefile is to create a kernel image.  Other possible actions are:
.BR "make depend" ,
to generate Makefile dependencies,
.BR "make clean" ,
to clean the source tree of intermediate files, and
.BR "make bootable" ,
to install a new bootstrap and boot code into the root file system.
.TP
.B version
Contains the files
.B version.h
and
.BR revision.c .
The first tells the O.S. release and version strings.  The second is the
revision number of the kernel, it is automatically increased by one each
time you call
.BR build .
The concatenation of release, version and revision numbers is used to name
the image in the
.B tools
directory and
.BR /minix .
.PP
Before
.B build
is called for the first time an important decision must be made.  Do you
want to do the compilation in the source directory, or in a so-called
"build-tree" full of links to the source directory?  The former pollutes
your source directory with
.B .o
files and executables, but the latter requires a lot of discipline to
maintain the links.  If you decide to use a build-tree (see
.BR @build (8)
for more) then use the following commands to create it:
.PP
.RS
.nf
.ft B
cd /usr/src
@clone
.ft P
.fi
.RE
.PP
When executed
.B build
will simply call
.B make
in the
.B tools
directory to make a new image.  There is nothing sinister going on, you
can type
.B make
in the many kernel directories yourself if you want to, all that
.B build
does extra is manage the images in
.B tools
and
.BR /minix .
Any options given to build are attached to the
.B CFLAGS
variable in the many Makefiles using the
.B OPT
environment variable.  (So
.B build \-O
is the same as
.BR "OPT=\-O make" " ...)"
.PP
There are usually two images in
.BR /minix .
One that is known to work, and one experimental.  After build has made a
new image it will ask which one of these to remove.  By default it will
want to remove the experimental (newest) image.  You can use wildcards
(*, ?) in your answer, or 'foo' or anything else if you want to remove
nothing.  No questions are asked if there are no images or just one image in
.BR /minix .
.SS Tuning
The first new kernel you would like to make is one configured for your
system.  The kernel you are running now contains several hard disk drivers
you don't need, so you may want to kick them out to save a few bytes.
In the file
.B config.h
in the kernel directory you can find a number of
.BI ENABLE_ XXX
variables that can be set to
.B 0
to exclude, or
.B 1
to include a particular driver.  Another driver related variable is
.BR DMA_SECTORS .
This variable sets the size of a buffer used by DMA based disk drivers (all
but the floppy, AT, and Adaptec drivers).  Raise its value to greatly
improve throughput, especially writing.  A value of 16 shows good results.
(Has no effect on old interleaved drives.)
.SH OPTIONS
.TP
.B \-newrev
Called from the task makefiles to increase the revision number.  Not
normally called by the user.
.SH FILES
.TP 20
.B /usr/src/sys
Default kernel source directory and associated utilities.
.TP
.B /minix
Image directory.
.SH "SEE ALSO"
.BR make (1),
.BR @build (8),
.BR usage (8).
.SH BUGS
The revision number will only be increased in the kernel, mm, and fs
directories, not on a change in task.stubs for instance.  So be careful
at the "removal" prompt.
.SH AUTHOR
Kees J. Bot (kjb@cs.vu.nl)