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

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

BUILD-CROSS: How to build the Rock Linux distribution for an alien system.
[Note: the flow of events and steps outlined here may need some tuning.
Please notify the documentation maintainer of errors and/or omissions.]

When reading this document and performing the steps described here, you should
preferrably have some experience with native builds of ROCK Linux first.


0. Getting sources.

First you need to download the ROCK Linux sources and the package sources, as
described in BUILD, step 1-4 and 6. You do not need an NFS server, because we 
begin with a stage-1-build (the NFS server is only required for stages 2-5). 


1. Setting up the build environment.

We assume that you have the ROCK Linux sources and that you have downloaded
all the source packages. In the example below, everything is located in
/rock-linux, but you may use any other local directory.

Now you need to create the build configuration file:

 murphy:/rock-linux# echo arch=alien          >   Config
 murphy:/rock-linux# echo buildoptpkgs=0      >>  Config
 murphy:/rock-linux# echo buildextpkgs=0      >>  Config
 murphy:/rock-linux# echo crossnative=cross   >>  Config

 (replace 'alien' with the target architecture)

Optionally you can also turn off the 'abort-on-error' feature - so the
build system will continue building the other packages if one package
fails to build. This will not work if a package like glibc fails to build...

 murphy:/rock-linux# echo abortonerror=0      >>  Config


2. Creating a cross compiler

If you have a pre-installed  cross compiler for the alien architecture, 
you need to remove it (only do this if you do not need it anymore or can 
re-install it later). For instance, if your alien box is a PowerPC box:

 murphy:/rock-linux# rm -rf /usr/powerpc-unknown-linux-gnu
 murphy:/rock-linux# rm -rf /usr/bin/powerpc-unknown-linux-gnu-*
 murphy:/rock-linux# rm -rf /usr/lib/gcc-lib/powerpc-unknown-linux-gnu
 murphy:/rock-linux# rm -rf /usr/local/powerpc-unknown-linux-gnu
 murphy:/rock-linux# rm -rf /usr/local/bin/powerpc-unknown-linux-gnu-*
 murphy:/rock-linux# rm -rf /usr/local/lib/gcc-lib/powerpc-unknown-linux-gnu

Now you need to build the cross compiler. That's really easy with ROCK Linux:

 murphy:/rock-linux# ./scripts/Create-CrossCC

This creates a slightly modified cross compiler which contains some references
to your ROCK Linux build tree (in this example /rock-linux). So you need to
rebuild it when/if you change the base directory of the build system.

If you have any files from another cross compiler for the same target
architecture on your build system, the script will ask you to remove them first.


3. Building the system

Now build the system (this will take a while):

 murphy:/rock-linux# ./scripts/Build-All COPY

The 'COPY' parameter will be ignored since we only build a stage 1 system.
After that you will find all packages in  rock-alien-<version>/* .


4. Installing it

If you have another Linux distribution running on the alien architecture,
you can perform the following steps on your *target* machine. 

But if you need to cross-build ROCK Linux you pretty sure do not
have Linux running on your alien box. So we install it in an NFS-exported
directory on the build host (name that directory /alien-root):

 murphy:/rock-linux# mkdir /alien-root
 murphy:/rock-linux# for x in rock-alien-*/base-pkgs/*.tar.bz2
 > do tar xvIf $x -C /alien-root ; done

Now you need to change the lines for 'root' and 'toor' in the new system's
/etc/passwd and /etc/shadow files like this:

/etc/passwd:
 root:x:0:0:root:/root:/bin/sh
 toor:x:0:0:emergency root:/root:/bin/kiss

/etc/shadow:
 root::::::::
 toor::::::::

And we need to create a /bin/sh file because there is no bash yet:

 murphy:/rock-linux# ln -svf sh_pdksh /alien-root/bin/sh

That's it. Export the /alien-root directory using NFS and boot your (NFS-root
enabled, see appendix 1) kernel on the target machine. Now you can create a 
filesystem on your alien host, copy the cross-built system on it, boot from 
the local disks and make a native rebuild. I.e. refer to the file BUILD.


** Appendix 1: Cross-Building a Kernel

Cross-building a linux kernel is pretty easy. We have already built the
cross compiler. All you need to do now is to extract your kernel sources
somewhere and change the 'ARCH := $(shell uname ...' line in the Makefile
to 'ARCH := alien'. Now run 'make menuconfig' and 'make vmlinux' as usual.
See appendix 4 for a list of valid architectures.

Don't forget to enable the devfs and nfs-root drivers.


** Appendix 2: Booting the Linux Kernel on alien systems.

[ FIXME: Someone wants to write this? ]


** Appendix 3: Booting the Linux Kernel with NFS root

Please read  /usr/src/linux/Documentation/nfsroot.txt  for details.


** Appendix 4: Valid architectures.

Simply type './scripts/Config list-arch' for a list of possible architectures.
Not all architectures are classified as stable and some of them are in early
beta development. So some architectures won't build without some hacking ..
