
             ____   ___   ___ _  __  _
            |  _ \ / _ \ / __| |/ / | |   _ _ __  _   _ _  _
            | . _/| | | | |  | '_/  | |  |_| '_ \| | | | \/ |
            | |\ \| |_| | |__| . \  | |__| | | | | `_' |>  <
            |_| \_\ ___/ \___|_|\_\ |____|_|_| |_|\___/|_/\_|
         [============> http://www.rocklinux.org/ <============]

 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 *                                                                         *
 *   ROCK Linux is Copyright (C) 1998 - 2000  Clifford Wolf                *
 *                                                                         *
 *   Read the file 'COPYING' for licensing details.                        *
 *                                                                         *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

BUILD: How to build the Rock Linux distribution.


For installing a precompiled Rock Linux distribution, see the file INSTALL. 
Hopefully you have read the file README already. Developers who would like to
contribute to this project should read and understand the file POLICY in
the developers directory. Finally, if you are building for a host different
from the one you are compiling on, you should read the file BUILD-CROSS.
For trouble-shooting, read the FAQ.
------------------------------------------------------------------------------

1. Why am I here?
If you are reading this file, you have already downloaded the ROCK Linux
"sourcecode". However, make sure you have the latest availabile version from:

   http://www.rocklinux.org/getting.html

If filenames ending with .tar.bz2 or .tbz2 makes you ask questions, you should
consider visiting http://www.linux.com/ and/or http://linuxdoc.org/. Come back
to this file when you find compiling a new kernel less exciting than what
it used to be.


2. Unpack the ROCK Linux sources to a filesystem with at least 720MB free 
space. The downloaded sources takes this much space. This should also prevent
users from trying to download the sources via modem. At 3kB/s, downloading the
sources will take 70+ hours.


3. Get the source packages.
From the root of the ROCK Linux directory, execute the command:
./scripts/Download -all

This command will start downloading the sources, provided that you have an
open network connection. For firewall/proxy considerations, refer to the
FAQ.

Likewise, if you need to customize the download parameters for any
particular package or elliminate one or more packages, refer to the FAQ.
Note: get help for all commands in the ./scripts directory with:
./scripts/Help Command


4. Hopefully, you are now downloading sources and saturating all availabile 
lines, to the dismay of your system administrator/co-workers/husband/girlfriend. 
The script can be interrupted at any time and will continue approximately 
where it was interrupted when restarted. It should complete without user
interaction. However, please read on just a little more before you take a
break.


5. Checking your driver's license and the condition of your vehicle.
In order to build (as in compile) the sources, there are some requirements.

a) First, you must have sufficient tools preinstalled on your system to
compile a new kernel. (This is almost true. If you can explain why this is 
untrue, you know what to do.)

b) Your running kernel (on the host where you intend to compile the packages)
must support devfs. (The Device Filesystem) If it doesn't already, download and
patch the kernelsources of an 2.4.x kernel.

c) You must run a 2.4 kernel to have support for the remount feature used to
mount the rock sources in the chroot environment.

d) Your running kernel must support ramdisks.  

e) /usr/src/linux should match the kernel sources in the ROCK Linux distribution.

When you're devfs-enabled, ready and installed, wait for the download to complete.


6. Verifying the sources.
Quite often, some file is temporarily unavailabile, or the version you have
downloaded has changed slightly. Check if any of the downloaded files have a
-cksum-err suffix to the filename. If this is the case, try to unpack the file 
manually. If this works, you may rename the file back to *.tar.bz2

Re-execute
./scripts/Download -all

This will download the missing files only. Repeat this step until all packages
are downloaded. To verify the sourcepackages, execute:
./scripts/Download -check -all.  


7. Boot the new kernel.
Did you remember to disable Power Management in the BIOS? (You don't want
your computer to start building the distribution and fall asleep at the
wheel after 40 minutes, do you?)


8. Setting up the build environment.
At this point you have all the sources, the kernel is humming a happy tune with
devfs enabled.

Become root. You need to be root for the rest of the instructions to
succeed. Otherwise, some packages won't build correctly.

[ *** much outdated stuff removed ;-) *** ]

Now you need to create the configuration file:

# ./scripts/Config [ text, menu ]

You are ready to compile ROCK Linux.

[ *** You wonder why this section is soo short? In the past you needed to do some
tricks here ;-) But everything get's easier, even ROCK Linux. *** ]
 
9. Build the distribution

    # ./scripts/Build-All 

This command runs for a day. (25-140 (or even more) hours, depending on
hardware.) After it is done you have a complete, packaged ROCK Linux
distribution in the directories ./rock-base-<$VERSION>/. 

<optional>

You can do some sym-link trick - which were strongly needed in the past:

Create the directories '/rock-orig' and '/rock-linux' and mount the sourcecode at
'/rock-orig':

    # mkdir -p /rock-orig /rock-linux
    # mount -t nfs filesrv:/rock-src /rock-orig -o ro

Substitute 'localhost' for 'filesrv', if you are building the distribution
on the host were the sources now are stored. Note that the filesystem where
/rock-linux resides needs to have at least 2.5GB free space in order to build
ROCK Linux, and that even more space is required if the sources are not
nfs-mounted. Do *NOT* nfs-mount /rock-linux. This must be a local filesystem.
You have been warned.

Now you need to create symlinks from '/rock-linux' to '/rock-orig':

    # cd /rock-orig
    # ./scripts/Create-Links /rock-linux
    # cd /rock-linux

Now you need to create the configuration file:

    # cd /rock-linux
    # ./scripts/Config [ text, menu ]

use the menus to select the options for building ROCK Linux.
If you are compiling for an architecture other than the one you are compiling
on, refer to the file BUILD-CROSS now.

</optional>

Note that you want to keep the terminal where you start building ROCK Linux 
open all the time while the build is running. Otherwise, some package may fail
compiling, and the build will abort. This is of course not critical.
[Perl fails in stage 4, complaining that /dev/tty ("current terminal") is
unavailabile.]


10. Continue an aborted build
When you restart a build after it has aborted it will by default start from 
the beginning, deleting everything built so far. If you would like to continue
where it stopped instead, just execute:

    # touch _nodel_

before re-executing "./scripts/Build-All" with whatever option you started it
with.


11. Take a break. 
Visit a friend. Or something. This is going to take a while. OK? 24+
hours.


12. Create a CD image (Optional)
Do:
./scripts/Create-CD <arch> <cd-number>
This will create an image of a bootable CD, from which you can install ROCK
Linux. You will have to write it to a blank CD with a CD-writer.
Otherwise, you can create the bootdiskettes and access the ROCK Linux
packages via NFS, ftp or http  or from a server of your choice.


13.
Read the file INSTALL.
