Introduction
------------

This document is a supplement to INSTALL. It describes how to build most 
RPMs required by section 2 of INSTALL. It also describes how to build
an individual RPM and how to generate a complete kernel source tree.
All commands for building RPMs should be run as root.

You should install the mknbi RPM from the latest binary release. It is not 
built as part of these instructions.

First be sure you install the glib-devel package from your Fedora CDs:
	# rpm -Uhv glib-devel-*
	# rpm -Uhv dietlibc-*

Building the devfsd RPM requires that /usr/src/linux-2.4 contains a kernel 
tree. If it does not exist, make it a symlink:
	# ln -s linux-<kernel_version> /usr/src/linux-2.4

If /usr/src/linux-<kernel_version> also does not exist, then install the 
kernel-source RPM from your distro's installation CDs, or download the 
kernel-ssi-source RPM from OpenSSI.org.

Now checkout the sandboxes you need (if you are reading this document,
you probably checked out an openssi sandbox already). Do _not_ do these
checkouts in /usr/src:
	# CIREP=:ext:<username>@cvs.openssi.org:/cvsroot/ci-linux
	# cvs -d $CIREP co -r OPENSSI-FC ci
	# SSIREP=:ext:<username>@cvs.openssi.org:/cvsroot/ssic-linux
	# cvs -d $SSIREP co -r OPENSSI-FC openssi
	# cvs -d $SSIREP co -r OPENSSI-FC srpms

You need to get the kernel code from the OPENSSI-RH branch:
	# cd ci 
	# cvs up -dPr OPENSSI-RH kernel
	# cd ../openssi
	# cvs up -dPr OPENSSI-RH kernel kernel.patches kernel.configs
	# cvs up -dPr OPENSSI-RH specs/kernel-2.4.spec
	# cd ..

Install the base source RPMs:
	# rpm -ihv srpms/*.rpm

Extract the base kernel source:
	# tar jxf srpms/linux-fc-2.4.22-1.2199.nptl.tar.bz2

Your directory should contain the following:
	# ls
	ci  linux  openssi  srpms

One last thing you should do is move aside any other RPMs you might have
built in the past, since they could be easily confused with the plethora
of OpenSSI RPMs you are about to build. These old RPMs (if any) can be
found in the /usr/src/redhat/RPMS/* directories.

Now you are ready to actually build RPMs.


Building all RPMs
-----------------

First build a cluster-tools RPM:
	# cd ci
	# make rpms

Install the freshly built cluster-tools RPM. It is needed to build some
of the other RPMs:
	# RPMDIR=/usr/src/redhat/RPMS
	# rpm -Uhv $RPMDIR/i386/cluster-tools-<latest version>.i386.rpm

If you already have a version of cluster-tools installed, it's possible 
that the new package will conflict with it. This would happen if the 
package you built has the same version/release number as what is already 
installed. One solution would be to increment the SSI release number in
the cluster-tools specfile before building the RPM, but how to do this is 
beyond the scope of this document. An easier solution is to use the --force 
option with the `rpm -Uhv ...' command above.

Next build the OpenSSI RPMs:
	# cd ../openssi
	# make rpms

The kernel build in particular should take awhile. Once it is done, you will 
find the RPMs you need under /usr/src/redhat/RPMS. The various utilities are
in the i386 subdirectory. The new kernel RPM is in the i686 subdirectory.

You can delete the *-debuginfo-* RPMs. You can also delete e2fsprogs-devel, 
losetup and ntsysv, since no code is modified in these RPMs.

The rest of this section tells you how to install these RPMs as if you
were installing an official OpenSSI release. The instructions assume that
you do not already have OpenSSI installed.

Create some subdirectories in your openssi sandbox:
	# mkdir -p RPMS/base
	# mkdir -p RPMS/ssi

Move your new kernel RPM from /usr/src/redhat/RPMS/i686 into openssi/RPMS. 
Move the rest of the OpenSSI RPMs from /usr/src/redhat/RPMS/i386 into
openssi/RPMS/ssi. The openssi/RPMS/base does not need anything in it.

Continue following the instructions in section 2 of INSTALL, starting with
the ./install script.


Building Individual RPMs
------------------------

You can also build individual RPMs. For example:
	# cd ci; make cluster-tools.rpm
		-- or --
	# cd openssi; make kernel.rpm
		-- or --
	# cd openssi; make openssi-tools.rpm
		-- or --
	# cd openssi; make sysvinit.rpm
		-- etc. --

The only RPMs you can build in the ci directory is cluster-tools and the
CI kernel (not needed for OpenSSI). To find out what RPMs can be built in 
the openssi directory, look at the the rpms and utilrpms rules at the bottom 
of openssi/Makefile.


Generating a kernel source tree
-------------------------------

You do not need to be the root user for these instructions. 

Generate a linux-ssi directory with the complete kernel source with:
	$ cd openssi
	$ make kern
	   -- or --
	$ make fullkern

The difference between the two rules is that 'make kern' only applies
the OpenSSI changes to the base Fedora kernel source, whereas
'make fullkern' also applies a set of third-party patches, including
SGI's kernel debugger, Linux Virtual Server, modifications needed for
Lustre, etc. At present, some of these patches are required for building
an OpenSSI kernel, so the 'make kern' rule does not generate a buildable 
source tree. Only 'make fullkern' does this.

To browse the source, it is useful to have a tool such as cscope:
	http://cscope.sourceforge.net/

It requires an list of all files to index, which the following command
can generate for you:
	$ cd linux-ssi
	$ find \
	    ! -path './arch/i386*' -path './arch/*' -prune -o \
	    ! -path './include/asm-i386*' -path './include/asm*' -prune -o \
	    \( -name '*.[chxsS]' -o -name '*.svc' \) -print \
		>cscope.files

Finally, index everything with:
	$ cscope -k

Now you can use cscope to easily find definitions for functions, structures, 
etc. Also, the vim command has integrated support for cscope, which lets
you use Ctrl-] to find the definition for a symbol and Ctrl-t to pop back
to where you came from.


Building a kernel source tree
-----------------------------

To build an OpenSSI kernel, you should start with one of the 
pre-defined kernel config files in openssi/kernel.configs. The 
kernel-2.4.22-i586-ssi.config and kernel-2.4.22-i686-ssi.config files
are derived from Fedora's kernel-2.4.22-ix86-smp.config files.
The kernel-2.4.22-i686-ssi.config file is what is used to generate the
kernel RPM for releases. You can also use config.i586 or config.i686, 
which is a stripped-down config file used by many developers because 
it builds much more quickly.

If you want to customize one of these config files, you must at a minimum
say Y to initial ramdisk support and the /dev filesystem in order to
enable SSI clustering. You must also set the default RAM disk size to 9000.
Also, you should statically compile (y, not m) IPVS and Unix domain sockets.
There might be other kernel features that are necessary, as well. If you 
determine something else that is required, please send an e-mail to 
ssic-linux-devel@lists.sf.net.

Building the kernel is the same as usual:
	$ cd linux-ssi
	$ cp ../openssi/kernel.configs/kernel-2.4.22-i686-ssi.config .config
	$ make oldconfig
	$ make dep
	$ make bzImage
	$ make modules

Installation is similar to the usual procedure, although not identical. 
You must use the --cfs option to mkinitrd, or your kernel will not be
able to join the cluster.

Do the following as root (x is a kernel revision number that changes with 
each release):
	# make modules_install
	# cp arch/i386/boot/bzImage /boot/vmlinuz-2.4.22-1.2199.nptl_ssi_x
	# mkinitrd --cfs /boot/initrd-2.4.22-1.2199.nptl_ssi_x.img \
		2.4.22-1.2199.nptl_ssi_x

Add a stanza to /etc/grub.conf for your new kernel and initrd, and set 
it as the default. In addition, run the ssi-ksync command to update the 
/tftpboot directory with a copy of the new default kernel and initrd, so 
that network booting nodes can find it. The ssi-ksync command also 
distributes copies of all kernels and initrds in /etc/grub.conf to nodes 
with local boot partitions. All nodes with local boot partitions must be 
up at the time to receive the updates. If such a node is not up and it 
misses the update, it would be safest to network boot it next time, then run 
ssi-ksync again after it has joined the cluster.

Finally, reboot the cluster. If all goes well, you should be running your 
custom-built kernel.