Adaptation Guide/Step by step

The objective of this phase is to provide a minimal booting image for a device.

Pre-requisites

• a suitable architecture build of Mer (ie armv7, MIPS, x86 etc)
• a bootloader
• a kernel capable of bringing the device to a framebuffer console
• OBS access or platform SDK

Make a kernel package

To package a kernel you need spectacle installed. To build it locally you need osc or the SDK. You will also need an account on the Community OBS. Although this method uses the public OBS you do not need to publish your source code or .config file. To make an image you'll need mic2 installed.

The Community OBS project we will use is: Mer:Sample:HA (draft in home:lbt:Mer:Sample:HA)

• Checkout the sample kernel-adaptation:

 osc co Mer:Sample:HA:kernel-adaptation-sample
 cd Mer:Sample:HA/kernel-adaptation-sample

• Prepare a tarball and patches for your kernel

Git method (preferred):

• Clone an upstream kernel
• Rebase patches onto a mainline tag location

Now to create a tarball, a set of patches and produce a Patches: section for the yaml file.

In the root directory of your kernel git tree create a tarball and patchset using the git2tarball.sh script from the kernel-adaptation package. eg:

/path/to/Mer:Sample:HA/kernel-adaptation-sample/git2tarball.sh /path/to/Mer:Sample:HA/kernel-adaptation-sample 2.6.38.4

The 'version' must correspond to a 'v' kernel tag (eg in this case v2.6.38.4). Then every commit from that tag to HEAD is exported as a patch to the package directory and a Patches: section is printed.

In the Mer:Sample:HA/kernel-adaptation-sample directory, modify the yaml file to include suitable values for Version:, Release: etc. Also include the Patches: section generated by the script. The yaml and spec files contain comments explaining how values are used.

Tarball method:

In the Mer:Sample:HA/kernel-adaptation directory, modify the yaml file to include suitable values for Version:, Release: etc. Also include a Patches: section if you have any patches (see the spectacle page for links to more details).

Copy the kernel tarball to the /path/to/Mer:Sample:HA/kernel-adaptation-sample and ensure that the filename is of the format: kernel-v${VERSION}-src.tar.gz Note that this VERSION string must mach the yaml and the Makefile in the tarball. Also the tarball should unpack the source to a directory such as kernel/*

Additional patches must be handled manually but can be placed in the yaml file Patches: section.

Both methods; build and/or hack on code:

To update the .spec file you must run:

specify kernel-adaptation-sample.yaml

You can now do a local build by running:

osc build <arch> kernel-adaptation-sample.spec

This will send your .spec file (only) to the server to determine what packages need downloading. It will then create a minimal chroot environment and unpack your src locally. Finally it will run rpmbuild to make an rpm of your kernel.

The <arch> value should be i586, armv7el or armv8el (see the section about arch in Mer for more details).

The build environment is accessed using:

osc chroot <arch> kernel-adaptation-sample.spec

This will tell you where the chroot is located (hint, edit your ~/.oscrc to modify this and note that the build user is 'abuild' and the build happens in /home/abuild/rpmbuild/BUILD/ inside the chroot) - so you can edit files there using your desktop editor. You can then do :

cd rpmbuild/BUILD/kernel/
export ARCH=x86 (or whatever you need - note that this is the *KERNEL* arch specification and is differen to the Mer/OBS arch)
make menuconfig/bzImage/modules/...

It is frequently necessary to revisit this step to change the kernel. The steps are:

1. build an image (coming next)
2. image boots but fails to run properly (missing device driver etc)
3. enter kernel chroot
4. change the config
5. build the kernel
6. copy the kernel to the image built in step 1 to avoid rebuilds
7. go to step 2

When the kernel is satisfactory you MUST COPY THE CONFIG OUT OF THE CHROOT to the /path/to/Mer:Sample:HA/kernel-adaptation-sample or it will be lost because the chroot is modified (sources wiped) every time you do an 'osc build'. See the section about osc chroots for more information.

Having copied the config (and any patches) out of the chroot and put them in the package you can build a clean kernel package.

At this point in a full development deployment you would normally send your changes up to a private OBS/BOSS instance to be built and QA'ed. We'll move on to making an image locally to test the device.

Make a bootloader package (if needed for the image)

For devices that need a bootloader in the same image as the OS, a bootloader package is needed.

The Mer:Sample:HA has an example EFI grub bootloader. It simply contains a tar of the required configuration files and the bootloader binary. The Makefile copies these into the /boot partition created by mic (see the next step)

Make an image

This section provides a bare minimum of information to get going; see the mic2 section for more details.

To prepare the bootstrap use:

 mic-create-bootstrap -n trunk -k /var/cache/mic -r http://repo.meego.com/MeeGo/builds/trunk/latest/repos/oss/ia32/packages/ -o /var/cache/meego-bootstrap

The kickstart file for your device needs to prepare a rootfs and setup any needed bootloader. FIXME: Replace this with kickstarter oriented approach

Use the default Mer kickstart as a starting point

mic-image-creator -c mer-core-i586.ks --outdir=images

Typically you'll need to add your kernel HA package and possibly a bootloader package. For devices which need the kernel in a distinct file. mic has an option called --save-kernel which creates a rootfs/kernel pair.

[1]: http://wiki.merproject.org/Image_Creation

Hack image

Once the image boots you should try to login as root using the password "mer"

Boot device and debugging

Hints, tips and tricks:

• The kernel command line: systemd.unit=$SOME.target can be used to specify a specific systemd target. rescue.target should be useful.
• Consider using kernel option "rootwait" if your rootfs device may be slow to appear (eg on a usb stick)