[[!meta title="How To: Porting to a new architecture"]]

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

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


1. Modify morph and build-essential
-----------------------------------

This is **only neccessary** if you are trying to cross-bootstrap to a new
architecture.

Mainly you have to include the new architecture in morph as a valid
architecture (FIXME: explain how to, and where)

Also you have to modify linux (git://git.baserock.org/delta/linux.git).
There is a file in the `baserock/build-essential` branch called
`morph-arch`. You have to include changes for the new architecture.



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

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 o be commited and pushed in a git repository. For this
example we assume the morphology is in `baserock:baserock/morphs` and
in the `master` branch.

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

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

Fix any problems if it fails, and execute `morph cross-bootstrap` again.


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

Once you have the tarball you have two options:

1. If you have running linux in the target architecture you can copy
   the tarball there and then chroot into it with `chroot rootfs
   /bin/sh`
1. Nfs boot to the tarball's filesystem.

Once you are into the filesystem created, you have to execute the
`native-bootstrap` script. This script ends building everything. Fix any
problem executing this script and regenerate the tarball. (You also can
try to fix the problems without regenerating the tarbal to save time,
but is not recommendable).


4. Prepare the bootstrap system
-------------------------------

When the `native-crossbootstrap` ends, you have to merge all the build
results into one directory

    cp *.inst/* NEW_DIR/

Now you have in the NEW_DIR all the bootstrap filesystem.


5. Using the bootstrap system
-----------------------------

To avoid problems using `morph build` running chroot the bootstrap
system you have two possible solutions ($path is the path to the
bootstrap filesysyem

1. `cd $path && mount --bind . . `
1. move the filesystem to another disk.

After that you have to go to che $path folder and run:

    mount -t proc proc proc/
    mount -t sysfs sys sys/
    mount -o bind /dev dev/

This is important because morph won't work without it. After that
you are ready to chroot into it:

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

Sometimes you have to run the following to be able to ping URL's

    echo "nameserver 8.8.8.8" > /etc/resolv.conf



<pedroalvarez> mtix: oh, just tell me what needs more explanation
<pedroalvarez> I'll improve it
<mtix> everything!
<mtix> i may be a lost cause
<pedroalvarez> maybe is because the tutorial doesn't explain what it does
<pedroalvarez> juist how to do it
<mtix> def need tutoring on what each step means
<pedroalvarez> 1: is only modify the morph tool in baserock to allow morph to work in the new architecture
<pedroalvarez> 2: is Cross-build baserock. We cross-build a tiny devel system called cross-bootstrap-system
<pedroalvarez> 3: is the second part of the cross-build. It has to be done in the target architecture
<pedroalvarez> In the 2nd and 3rd step is usual to have problems due you are building to a new architecture. The main work in this steps is to fix this problems.
<pedroalvarez> 4: this step is only the final step of the cross-build of baserock. Put the things together
<pedroalvarez> 5: is an explanation of how to use the cross-built system
<pedroalvarez> After this tutorial you have a cross built baserock, and you can use it to build the system you want
<pedroalvarez> Building a devel system, for example, will include more things than the tiny system we have cross-built, so more problems will happen building from here
<pedroalvarez> Problems in some chunks in baserock, which need some changes to work in the new architecture
<mtix> i see morph has a command called cross-bootstrap
<mtix> what does that command do?
<pedroalvarez> it creates a tarball of a system with a few things cross-compiled
<pedroalvarez> is the tarball you have to use in the step 3
<pedroalvarez> with this system you finish building the tiny baserock (bootstrap baserock) natively