OpenEmbedded provides patches and Bitbake Recipes, that are similar to .spec files to build RPM packages. Bitbake is used to process recipes and obtain packages and FS images. For example, bitbake can fetch sources, apply patches, configure, make and install compiled sources. Other steps are user definable, but this is not the scope of this tutorial.

OpenEmbedded provides patches and Bitbake Recipes, that are similar to .spec files to build RPM packages. Bitbake is used to process recipes and obtain packages and FS images. For example, bitbake can fetch sources, apply patches, configure, make and install compiled sources. Other steps are user definable, but this is not the scope of this tutorial.

Line 8:

Line 9:

A standard use of bitbake is to download an existing "vanilla" package, ie "gcc" or "binutils" or "linux kernel", apply platform patches (adding bugfixes, porting fixes, drivers, etc...) then compile and package the resulting binaries.

A standard use of bitbake is to download an existing "vanilla" package, ie "gcc" or "binutils" or "linux kernel", apply platform patches (adding bugfixes, porting fixes, drivers, etc...) then compile and package the resulting binaries.

−

==Software versionning==

+

==Software versioning==

−

Versions management is a very wide topic, there are tons of different opinions about it, I'll try to be quick.

+

Software versioning and configuration management is a very wide topic, there are tons of different opinions about it, I'll try to be quick.

Packages versions are important in a distribution building mechanism, and package versions are a complete part of the full package name. They are obviously used to track important changes made to your package, and isolate each version. Here we must be a little aware of basic version management.

Packages versions are important in a distribution building mechanism, and package versions are a complete part of the full package name. They are obviously used to track important changes made to your package, and isolate each version. Here we must be a little aware of basic version management.

Line 25:

Line 26:

===Prerequisites===

===Prerequisites===

−

You need a configured openmoko development tree. All details are in [[Building OpenMoko from scratch]]

+

You need a configured openmoko development tree. All details are in [[Building Openmoko from scratch]]

+

+

You may also do this with [[MokoMakefile]], see instructions at the bottom.

The following commands will give you one, they are copied from the above page. Just copy and paste in a shell.

The following commands will give you one, they are copied from the above page. Just copy and paste in a shell.

You're now all set to start building. Remember to run the setup-env command for each time you open a terminal. This sets your environment variables, however it is easier to include them in the rc file of your shell.

+

+

===Proposed directory layout for our new packages===

Bitbake recipes are single files describing how to build a package. I recommend to have a recipe for each package version (myprogram-1.0.bb, myprogram-1.1.bb, etc.) all stored in a directory named "myprogram"

Bitbake recipes are single files describing how to build a package. I recommend to have a recipe for each package version (myprogram-1.0.bb, myprogram-1.1.bb, etc.) all stored in a directory named "myprogram"

+

+

Our personal tree can be everywhere else:

+

<pre>

+

$HOME

+

+- $OMDIR (contains the official openmoko tree)

+

| +- ...

+

+- My_personal_Openmoko_Packages

+

| +- packages

+

| +- myhello

+

| +- myhello-1.0.bb

+

+- My_Personal_Projects_Folder

+

+- myhello

+

+- myhello-1.0

+

+- configure.ac

+

+- Makefile.am

+

+- ...

+

</pre>

+

+

To do a simple test, pack your sources in a tar, and put this tar on a web server:

+

<pre>

+

cd My_personal_Projects_Folder/myhello

+

tar cvfz myhello-1.0.tar.gz myhello-1.0/

+

</pre>

+

This is correct, ie the tarball will have a NAME-VERSION subdirectory, that's what we need.

===The recipe===

===The recipe===

Line 70:

Line 134:

* a source URI, I'll give details later

* a source URI, I'll give details later

* a source version, to checkout a particular revision of versionned trees

* a source version, to checkout a particular revision of versionned trees

+

* Please see the [http://www.openembedded.org/wiki/StyleGuide Open Embedded StyleGuide] which should answer most if not all questions about .bb file conventions.

#choose a stable date and stick with it that way when you distribute your recipe

+

#you don't have all sorts of versions getting built out in the wild.

+

SRCDATE_${PN} = "now"

+

SRC_URI = "svn://repo/path/myhello;proto=https;module=${PN}-${PV}"

#for a tarball use:

#for a tarball use:

−

#SRC_URI=http://server/path/package/${PN}-{$PV}.tar.gz

+

#SRC_URI = "http://server/path/package/${PN}-${PV}.tar.gz"

#include standard rules to build a autoconf/automake package

#include standard rules to build a autoconf/automake package

Line 101:

Line 170:

All of this is explained in the [http://bitbake.berlios.de/manual/ bitbake manual], particulary [http://bitbake.berlios.de/manual/ch03.html#id869590 here].

All of this is explained in the [http://bitbake.berlios.de/manual/ bitbake manual], particulary [http://bitbake.berlios.de/manual/ch03.html#id869590 here].

−

The "build" directory, the one where bitbake will run "configure" et al, MUST have the name template: "PACKAGE_NAME-PACKAGE_VERSION", so

+

The package build directory, the one where bitbake will run "configure" et al, will follow the name template: "PACKAGE_NAME-PACKAGE_VERSION", so

* tarballs must extract to a subdirectory with this name

* tarballs must extract to a subdirectory with this name

Line 109:

Line 178:

===Tell bitbake to build our package===

===Tell bitbake to build our package===

−

After this, we have to inform bitbake that we have a file for it.

+

The only and one thing to do is edit $OMDIR/build/local.conf to tell bitbake to search our folders for .bb files:

−

I assume a standard Openmoko directory tree with:

+

<pre>

<pre>

−

$OMDIR

+

BBFILES+="${HOME}/MypersonalOpenmokoPackages/packages/*/*.bb"

−

+- build

+

−

| +- conf

+

−

| | +- local.conf

+

−

| +- tmp

+

−

+- openmoko

+

−

+- openembedded

+

−

+- sources

+

</pre>

</pre>

−

etc...

+

There is no need to change BBPATH or something else, this is only needed to add new configuration files, not recipes.

−

Our personal tree can be everywhere else:

+

Running

−

<pre>

+

−

$HOME

+

−

+- $OMDIR

+

−

| +- ...

+

−

+- MypersonalOpenMokoPackages

+

−

+- packages

+

−

| +- myhello

+

−

| +- myhello-1.0.bb

+

−

+- sources

+

−

+- myhello

+

−

+- myhello-1.0

+

−

+- configure

+

−

+- Makefile.am

+

−

+- ...

+

−

</pre>

+

−

The only thing to do is edit $OMDIR/build/local.conf to tell bitbake to search our folders for .bb files:

+

−

<pre>

+

−

BBFILES+="${HOME}/MypersonalOpenMokoPackages/packages/*/*.bb"

+

−

</pre>

+

−

+

−

And then, running

+

<pre>

<pre>

$ cd $OMDIR/build

$ cd $OMDIR/build

Line 216:

Line 256:

===Get this package included in the rootfs image===

===Get this package included in the rootfs image===

−

bitbake openmoko-devel-image does not include your new package in the rootfs image.

+

<blockquote>

+

{| border="1" cellspacing="0" cellpadding="5" align="center"

+

|*This method is not a standard or normal way to include a package. The proper method follows the improper method.

+

|}

+

</blockquote>

+

bitbake openmoko-devel-image is used to build the entire distribution, but it does not include your new package in the rootfs image.

To do this, use:

To do this, use:

Line 224:

Line 269:

This will actually rebuild the rootfs, including your new packages.

This will actually rebuild the rootfs, including your new packages.

−

[[Category:Applications]]

+

<blockquote>

−

[[Category:Platform]]

+

{| border="1" cellspacing="0" cellpadding="5" align="center"

+

|*The suggested method follows below.

+

|}

+

</blockquote>

+

+

To include the package in the image there are two steps.

+

+

First: Modify your local.conf. $OMDIR/build/conf/local.conf

+

<pre>

+

DISTRO_EXTRA_RDEPENDS += "<app name>"

+

</pre>

+

This adds your application as a dependency for building the distro.

+

+

Second: Update the task-base.

+

<pre>

+

bitbake task-base -crebuild

+

</pre>

+

When you update the task base it re-builds and ipk file which will: "Merge machine and distro options to create a basic machine task/package"

+

+

You could also add your package by modifying the openmoko/trunk/oe/packages/tasks/task-openmoko.bb and adding your application name with the trailing backslash right before the update-alternatives line.

+

<pre>

+

modutils-initscripts \

+

module-init-tools-depmod \

+

udev \

+

rsync \

+

screen \

+

<My application Name> \

+

# update-alternatives \

+

</pre>

+

+

Then to test this out (if you're using the [[MokoMakefile]]) it's pretty simple.

+

<pre>

+

make openmoko-devel-image

+

make build-qemu

+

make flash-qemu-local

+

</pre>

+

And now you're running qemu with that fancy new image you just made!

+

+

If you are really lazy this script should do all the above stuff. This is just a small shell hack which uses the power of sed to inject packages into the the final image. Use at your own risk and please don't flame the author =D..

+

+

<pre>

+

#!/bin/bash

+

# Sudharshan "Sup3rkiddo" S

+

# inject, script that injects packages into the Openmoko standard,

+

# The sed line does all the stuff, nothing elite...

+

# The package is grouped under TASK_OPENMOKO_LINUX..after rsync

+

# The bitbake recipes should be present in the proper place. OE docs for info

+

+

ARGS=1

+

E_BADARGS=65

+

+

if [ $# -ne "$ARGS" ]

+

then

+

echo "Usage: inject <packagename>"

+

exit $E_BADARGS

+

fi

+

+

make update

+

make setup

+

cd openmoko/trunk/oe/packages/tasks

+

mv task-openmoko.bb task-openmoko.bb_bakup

+

# search for rsync and append the package name after it..[KIDDISH HACK]

OpenEmbedded provides patches and Bitbake Recipes, that are similar to .spec files to build RPM packages. Bitbake is used to process recipes and obtain packages and FS images. For example, bitbake can fetch sources, apply patches, configure, make and install compiled sources. Other steps are user definable, but this is not the scope of this tutorial.

A standard use of bitbake is to download an existing "vanilla" package, ie "gcc" or "binutils" or "linux kernel", apply platform patches (adding bugfixes, porting fixes, drivers, etc...) then compile and package the resulting binaries.

Software versioning and configuration management is a very wide topic, there are tons of different opinions about it, I'll try to be quick.

Packages versions are important in a distribution building mechanism, and package versions are a complete part of the full package name. They are obviously used to track important changes made to your package, and isolate each version. Here we must be a little aware of basic version management.
Current (most advanced) version is named the "trunk". Additions, fixes, etc. are done to the trunk.

Once a certain level of functionality is achieved, a copy of the trunk (a "snapshot") is taken, and named with a version number. As a result, current development continues on the trunk, but users can download well defined "releases", with known bugs and functionnality level. This is called "branching". If version specific bugs are found in version a.b, then we can update this branch independently.

In bitbake, we must specify which release of our software we are going to package. This may not be an habit, especially if you only develop small programs, not maintained by more than one or two person. If your software is named "myprogram" but has no real version number attached, you can just rename your project directory to "myprogram-1.0".

This is a good practice; If you are packaging a software, then it will be used by other people, so when you modify it next time, put it in a folder named "myprogram-1.1" :) This brings clarity to users, ease of management to you, and ability to plan future releases to your team.

Say you have a working software package, ie a file system directory with sources, Makefile, etc...
Because this is a common method, I will base my presentation on a project generated using autotools. This implies that the software can be installed somewhere by following the magical steps ./configure && make && make install.

Follow the link to MokoMakefile and follow the instructions.
You're now all set to start building. Remember to run the setup-env command for each time you open a terminal. This sets your environment variables, however it is easier to include them in the rc file of your shell.

Bitbake recipes are single files describing how to build a package. I recommend to have a recipe for each package version (myprogram-1.0.bb, myprogram-1.1.bb, etc.) all stored in a directory named "myprogram"

#package description
DESCRIPTION = "An example application for openmoko, depending on a custom source repository"
SECTION = "squalyl/myhello"
#this is optional
LICENSE = "GPLv2"
PN = "myhello"
PV = "1.0"
#use "now" to force svn updates at each build
#Using now is a very dangerous way to do it. ONLY use this in your
#personal recipes when you're doing heavy testing, otherwise
#choose a stable date and stick with it that way when you distribute your recipe
#you don't have all sorts of versions getting built out in the wild.
SRCDATE_${PN} = "now"
SRC_URI = "svn://repo/path/myhello;proto=https;module=${PN}-${PV}"
#for a tarball use:
#SRC_URI = "http://server/path/package/${PN}-${PV}.tar.gz"
#include standard rules to build a autoconf/automake package
inherit autotools

Expressions starting by ${} are substituted, this allows you to download a tarball named "mypackage-1.0.tar.gz" for example

*This method is not a standard or normal way to include a package. The proper method follows the improper method.

bitbake openmoko-devel-image is used to build the entire distribution, but it does not include your new package in the rootfs image.

To do this, use:

bitbake openmoko-devel-image -crebuild

This will actually rebuild the rootfs, including your new packages.

*The suggested method follows below.

To include the package in the image there are two steps.

First: Modify your local.conf. $OMDIR/build/conf/local.conf

DISTRO_EXTRA_RDEPENDS += "<app name>"

This adds your application as a dependency for building the distro.

Second: Update the task-base.

bitbake task-base -crebuild

When you update the task base it re-builds and ipk file which will: "Merge machine and distro options to create a basic machine task/package"

You could also add your package by modifying the openmoko/trunk/oe/packages/tasks/task-openmoko.bb and adding your application name with the trailing backslash right before the update-alternatives line.

Then to test this out (if you're using the MokoMakefile) it's pretty simple.

make openmoko-devel-image
make build-qemu
make flash-qemu-local

And now you're running qemu with that fancy new image you just made!

If you are really lazy this script should do all the above stuff. This is just a small shell hack which uses the power of sed to inject packages into the the final image. Use at your own risk and please don't flame the author =D..

Views

Personal tools

This is a small tutorial to help people that want to write new software for Openmoko, eg. to port existing programs.

Theory

OpenMoko uses OpenEmbedded, a package and root image build system.

OpenEmbedded provides patches and Bitbake Recipes, that are similar to .spec files to build RPM packages. Bitbake is used to process recipes and obtain packages and FS images. For example, bitbake can fetch sources, apply patches, configure, make and install compiled sources. Other steps are user definable, but this is not the scope of this tutorial.

A standard use of bitbake is to download an existing "vanilla" package, ie "gcc" or "binutils" or "linux kernel", apply platform patches (adding bugfixes, porting fixes, drivers, etc...) then compile and package the resulting binaries.

Software versionning

Versions management is a very wide topic, there are tons of different opinions about it, I'll try to be quick.

Packages versions are important in a distribution building mechanism, and package versions are a complete part of the full package name. They are obviously used to track important changes made to your package, and isolate each version. Here we must be a little aware of basic version management.
Current (most advanced) version is named the "trunk". Additions, fixes, etc. are done to the trunk.

Once a certain level of functionality is achieved, a copy of the trunk (a "snapshot") is taken, and named with a version number. As a result, current development continues on the trunk, but users can download well defined "releases", with known bugs and functionnality level. This is called "branching". If version specific bugs are found in version a.b, then we can update this branch independently.

In bitbake, we must specify which release of our software we are going to package. This may not be an habit, especially if you only develop small programs, not maintained by more than one or two person. If your software is named "myprogram" but has no real version number attached, you can just rename your project directory to "myprogram-1.0".

This is a good practice; If you are packaging a software, then it will be used by other people, so when you modify it next time, put it in a folder named "myprogram-1.1" :) This brings clarity to users, ease of management to you, and ability to plan future releases to your team.

Example

Say you have a working software package, ie a file system directory with sources, Makefile, etc...
Because this is a common method, I will base my presentation on a project generated using autotools. This implies that the software can be installed somewhere by following the magical steps ./configure && make && make install.

Proposed directory layout

Bitbake recipes are single files describing how to build a package. I recommend to have a recipe for each package version (myprogram-1.0.bb, myprogram-1.1.bb, etc.) all stored in a directory named "myprogram"

The recipe

In the bitbake file, you need to give

a description for your package, variable name is DESCRIPTION

a package name (PN)

a package version (PV)

a source URI, I'll give details later

a source version, to checkout a particular revision of versionned trees