[[!meta title="How To: Cross-bootstrap"]]

Cross-bootstrap
===============

These are the steps to cross-bootstrap baserock from one architecture
to another.

1. Select a target architecture to do the cross-bootstrap
---------------------------------------------------------

We only have morphologies to do cross-bootstrapping for `x86_64`,
`ppc64` and `armv7lhf`, so if your target architecture is one of them
you only have to pick one of the morphologies.

On the other hand, if your intention is to do a cross-bootstrap
to another architecture you have to create a new morphology as follows:

*   Create a `cross-bootstrap-system-TARGET_ARCH-generic.morph` file
    (where TARGET_ARCH is the target architecture) and edit it so that
    it contains the following:

        arch: TARGET_ARCH
        description: A system that produces the minimum needed to build a devel system
        kind: system
        name: cross-bootstrap-system-TARGET_ARCH-generic
        strata:
        - morph: build-essential
          ref: master
          repo: baserock:baserock/morphs
        - morph: core
          ref: master
          repo: baserock:baserock/morphs
        - morph: cross-bootstrap
          ref: master
          repo: baserock:baserock/morphs

*   You must **replace** TARGET_ARCH for the target architecture in the
    morphology. The morphology has to be commited and pushed in a git
    repository. For this example we assume the morphology is in
    `baserock:baserock/morphs` repository and in the `master` branch of it.

2. Generate a bootstrap baserock tarball
----------------------------------------

Now is time to Cross-build baserock. We cross-build the
`cross-bootstrap-system-TARGET_ARCH-generic` using the
`cross-bootstrap` command in `morph`. With this command morph generates
a tarball of the system with a script to do finish the building in the
target architecture:

*   Execute `morph cross-bootstrap` for the morphology file created:

        morph cross-bootstrap TARGET_ARCH baserock:baserock/morphs master cross-bootstrap-system-TARGET_ARCH-generic

*   Once `morph` finishes building, it will tell you where the tarball
    is.

3. Native building of the cross-bootstrap process
-------------------------------------------------

This is the second part of the cross-build process and it has to be
done in the target architecture.

*   First of all you have to use the system created. To do that you
    have two options:

    1.  If you have linux running in the target architecture you can
        copy the tarball there, uncompress it and then chroot into it
        with:

            chroot /path/to/uncompressed/tarball /bin/sh

    1.  If you do not have a compatible Linux-based OS for the target
        architecture you can boot the cross-bult system directly (e.g.
        using NFS boot). You will need to build a kernel yourself if
        you take this approach.

*   Once you are into the filesystem created, you have to execute the
    `native-bootstrap` script (located in '/'). This script ends
    building everything.


4. Using the bootstrap system
-----------------------------

With the bootstrap system now we can use `morph` to build systems.
Normally you will want to build a devel-system to start using it
instead of the bootstrap system.

*   First of all you have to use the system created. To do that you
    have two options:

    1.  If you have linux running in the target architecture you can
        copy the tarball there, uncompress it and then chroot into it
        with:

            chroot /path/to/uncompressed/tarball /bin/sh

    1.  If you prefer, you also can boot the system (e.g. with NFS
        boot). The problem to do this is that the system doesn't have
        Kernel.

### 4a. Extra steps with chroot

*   Morph uses `linux-user-chroot` when building, and this does not
    work inside a chroot. There are two options for fixing this:

    1.  Create a bind mount to hide the chroot:
        `cd /path/to/uncompressed/tarball && mount --bind . .`
    1.  Move the bootstrap filesystem to the top level of another disk.
        We haven't investigated why it works.

    To test that this works you should be able to run the following
    **into the chroot environment**.

        linux-user-chroot / /bin/sh

*   Now you have to mount some special filesystems inside the chroot:

        cd /path/to/uncompressed/tarball
        mount -t proc proc proc/
        mount -t sysfs sys sys/
        mount -o bind /dev dev/
        mount -o bind /tmp tmp/

*   And then, you are ready to chroot into it:

        chroot . /bin/sh
        PATH=/bin:/usr/bin:/sbin:/usr/sbin
        LD_LIBRARY_PATH=/lib:/lib64
        ldconfig

### 4b. Extra steps if you booted the cross-bootstrap system directly

*   Mount sysfs and proc.

        mount -t sysfs none /sys
        mount -t proc none /proc

*   To be able to ssh into it:

        /usr/sbin/sshd-keygen
        /usr/sbin/sshd


### 4c. Build a devel system

Now you are ready to start [using baserock], build and deploy a
devel system.

[using baserock]: http://wiki.baserock.org/devel-with/