Openmoko - User contributions [en]

OpenEmbedded Torrent Instructions

2009-02-14T21:27:35Z

Cfriedt:

After downloading an [[OpenEmbedded Torrent]], there are two variables that need to be exported in the shell environment. The MACHINE and OE_HOME. Examples are used below, but please set the variables appropriately for your scenario. Also, please ensure that there are several gigabytes of disk space available in OE_HOME.

<pre>
export MACHINE=om-gta02
export OE_HOME=${HOME}/oe
</pre>

The following three variables are set here for the purpose of generality. They should be included in the name of your torrent file.

DISTRO=angstrom-2008.1
ARCH=x86_64-linux
TIMESTAMP=20090214
TARBALL_LOC=${HOME}

Please follow the following instructions for preparing the pre-compiled OpenEmbedded build environment.

<pre>
mkdir -p ${OE_HOME}
tar xpjf ${TARBALL_LOC}/openmoko-${MACHINE}-${DISTRO}-${ARCH}-${TIMESTAMP}.tar.bz2 -C ${OE_HOME}
cd ${OE_HOME}
echo ${OE_HOME}/build-${MACHINE}/tmp > ${OE_HOME}/build-${MACHINE}/tmp
source setup-env
</pre>

The next step is to rebuild non-portable packages required for native and cross compilation. All of such packages are pulled in as dependencies, when building the 'console-image' recipe.

bitbake console-image

That's it! You are now ready to do system development or application development to your heart's content!

OpenEmbedded Torrent

2009-02-14T21:14:13Z

Cfriedt: /* FAQ */

The following links are in place to provide developers with a pre-compiled [[OpenEmbedded]] build environment tailored to their workstation's architecture. In order to use BitTorrent files, it is necessary to install a [http://en.wikipedia.org/wiki/BitTorrent_client BitTorrent client].

The reason that these torrents are provided, is to decrease the amount of time it takes for system developers to have a fully functional build environment, allowing them to focus on more important tasks.

{{Note|A pre-compiled OE environment is several gigabytes in size. For example, the compressed environment could be 3GB of data to download, but it might require another 16 GB to uncompress. '''It is suggested to have approximately 25GB of free disk space before continuing'''.}}

Once the environment is downloaded via [http://en.wikipedia.org/wiki/BitTorrent BitTorrent], just follow these [http://wiki.openmoko.org/wiki/OpenEmbedded_Torrent_Instructions instructions], and go! See the list below for available torrents.

== Available Torrents ==

=== Linux Users ===

Torrents for Linux users

(There are no torrents at this time)

=== Mac OS X Users ===

Torrents for Mac OS X users

(There are no torrents at this time)

=== FreeBSD Users ===

Torrents for FreeBSD users

(There are no torrents at this time)

== FAQ ==

* '''How can I contribute a torrent of my OE environment, to help future OpenMoko developers jump-start their work?'''

That is a very excellent question, and we are very happy that you asked! Please see [[OpenEmbedded Torrent Submission]] for more details.

* '''Why does my environment rebuild gcc-cross, binutils-cross, libtool-native, ... ?'''

If every end-user had the same username and the same OE_HOME, then the cross-toolchain would be completely portable. However, that is generally not the case. The toolchain has compiled-in paths that contain system libraries and headers. If those paths change, then there is a very high probability that [http://en.wikipedia.org/wiki/Gremlin gremlins] might attack you, your loved ones, and your town, possibly ruining Christmas for everyone.

== Contributing to the Pool of Torrents ==

If you have noticed that the available torrents for your architecture, machine, and distro are few (or none), then we would love it if you would share your build environment for other OpenMoko developers to get up-to-speed fast!

Please see [[OpenEmbedded Torrent Submission]] for more details.

[[Category:Application Developer]]
[[Category:System Developers]]

OpenEmbedded Torrent

2009-02-14T21:10:46Z

Cfriedt: /* FAQ */

The following links are in place to provide developers with a pre-compiled [[OpenEmbedded]] build environment tailored to their workstation's architecture. In order to use BitTorrent files, it is necessary to install a [http://en.wikipedia.org/wiki/BitTorrent_client BitTorrent client].

The reason that these torrents are provided, is to decrease the amount of time it takes for system developers to have a fully functional build environment, allowing them to focus on more important tasks.

{{Note|A pre-compiled OE environment is several gigabytes in size. For example, the compressed environment could be 3GB of data to download, but it might require another 16 GB to uncompress. '''It is suggested to have approximately 25GB of free disk space before continuing'''.}}

Once the environment is downloaded via [http://en.wikipedia.org/wiki/BitTorrent BitTorrent], just follow these [http://wiki.openmoko.org/wiki/OpenEmbedded_Torrent_Instructions instructions], and go! See the list below for available torrents.

== Available Torrents ==

=== Linux Users ===

Torrents for Linux users

(There are no torrents at this time)

=== Mac OS X Users ===

Torrents for Mac OS X users

(There are no torrents at this time)

=== FreeBSD Users ===

Torrents for FreeBSD users

(There are no torrents at this time)

== FAQ ==

* '''How can I contribute a torrent of my OE environment, to help future OpenMoko developers jump-start their work?'''

That is a very excellent question, and we are very happy that you asked! Please see [[OpenEmbedded Torrent Submission]] for more details.

* '''Why does my environment rebuild gcc-cross, binutils-cross, libtool-native, ... ?'''

If every end-user had the same username and the same OE_HOME, then the cross-toolchain would be completely portable. However, that is generally not the case. The toolchain has compiled-in paths that contain system libraries and headers. If those paths change, then there is a very high probability that [http://en.wikipedia.org/wiki/Gremlin gremlins] might attack you, your loved ones, and your town, possibly ruining Christmas for everyone.

[[Category:Application Developer]]
[[Category:System Developers]]

OpenEmbedded Torrent

2009-02-14T21:09:06Z

Cfriedt: /* Available Torrents */

The following links are in place to provide developers with a pre-compiled [[OpenEmbedded]] build environment tailored to their workstation's architecture. In order to use BitTorrent files, it is necessary to install a [http://en.wikipedia.org/wiki/BitTorrent_client BitTorrent client].

The reason that these torrents are provided, is to decrease the amount of time it takes for system developers to have a fully functional build environment, allowing them to focus on more important tasks.

{{Note|A pre-compiled OE environment is several gigabytes in size. For example, the compressed environment could be 3GB of data to download, but it might require another 16 GB to uncompress. '''It is suggested to have approximately 25GB of free disk space before continuing'''.}}

Once the environment is downloaded via [http://en.wikipedia.org/wiki/BitTorrent BitTorrent], just follow these [http://wiki.openmoko.org/wiki/OpenEmbedded_Torrent_Instructions instructions], and go! See the list below for available torrents.

== Available Torrents ==

=== Linux Users ===

Torrents for Linux users

(There are no torrents at this time)

=== Mac OS X Users ===

Torrents for Mac OS X users

(There are no torrents at this time)

=== FreeBSD Users ===

Torrents for FreeBSD users

(There are no torrents at this time)

== FAQ ==

* '''Why does my environment rebuild gcc-cross, binutils-cross, libtool-native, ... ?'''

If every end-user had the same username and the same OE_HOME, then the cross-toolchain would be completely portable. However, that is generally not the case. The toolchain has compiled-in paths that contain system libraries and headers. If those paths change, then there is a very high probability that [http://en.wikipedia.org/wiki/Gremlin gremlins] might attack you, your loved ones, and your town, possibly ruining Christmas for everyone.

[[Category:Application Developer]]
[[Category:System Developers]]

OpenEmbedded Torrent

2009-02-14T21:07:30Z

Cfriedt:

The following links are in place to provide developers with a pre-compiled [[OpenEmbedded]] build environment tailored to their workstation's architecture. In order to use BitTorrent files, it is necessary to install a [http://en.wikipedia.org/wiki/BitTorrent_client BitTorrent client].

The reason that these torrents are provided, is to decrease the amount of time it takes for system developers to have a fully functional build environment, allowing them to focus on more important tasks.

{{Note|A pre-compiled OE environment is several gigabytes in size. For example, the compressed environment could be 3GB of data to download, but it might require another 16 GB to uncompress. '''It is suggested to have approximately 25GB of free disk space before continuing'''.}}

Once the environment is downloaded via [http://en.wikipedia.org/wiki/BitTorrent BitTorrent], just follow these [http://wiki.openmoko.org/wiki/OpenEmbedded_Torrent_Instructions instructions], and go! See the list below for available torrents.

== Available Torrents ==

=== Linux Users ===

Torrents for Linux users

=== Mac OS X Users ===

Torrents for Mac OS X users

=== FreeBSD Users ===

Torrents for FreeBSD users

== FAQ ==

* '''Why does my environment rebuild gcc-cross, binutils-cross, libtool-native, ... ?'''

If every end-user had the same username and the same OE_HOME, then the cross-toolchain would be completely portable. However, that is generally not the case. The toolchain has compiled-in paths that contain system libraries and headers. If those paths change, then there is a very high probability that [http://en.wikipedia.org/wiki/Gremlin gremlins] might attack you, your loved ones, and your town, possibly ruining Christmas for everyone.

[[Category:Application Developer]]
[[Category:System Developers]]

OpenEmbedded Torrent

2009-02-14T21:06:58Z

Cfriedt:

The following links are in place to provide developers with a pre-compiled [[OpenEmbedded]] build environment tailored to their workstation's architecture. In order to use BitTorrent files, it is necessary to install a [http://en.wikipedia.org/wiki/BitTorrent_client BitTorrent client].

The reason that these torrents are provided, is to decrease the amount of time it takes for system developers to have a fully functional build environment, allowing them to focus on more important tasks.

{{Note|A pre-compiled OE environment is several gigabytes in size. For example, the compressed environment could be 3GB of data to download, but it might require another 16 GB to uncompress. It is suggested to have approximately 25GB of free disk space before continuing.}}

Once the environment is downloaded via [http://en.wikipedia.org/wiki/BitTorrent BitTorrent], just follow these [http://wiki.openmoko.org/wiki/OpenEmbedded_Torrent_Instructions instructions], and go! See the list below for available torrents.

== Available Torrents ==

=== Linux Users ===

Torrents for Linux users

=== Mac OS X Users ===

Torrents for Mac OS X users

=== FreeBSD Users ===

Torrents for FreeBSD users

== FAQ ==

* '''Why does my environment rebuild gcc-cross, binutils-cross, libtool-native, ... ?'''

If every end-user had the same username and the same OE_HOME, then the cross-toolchain would be completely portable. However, that is generally not the case. The toolchain has compiled-in paths that contain system libraries and headers. If those paths change, then there is a very high probability that [http://en.wikipedia.org/wiki/Gremlin gremlins] might attack you, your loved ones, and your town, possibly ruining Christmas for everyone.

[[Category:Application Developer]]
[[Category:System Developers]]

OpenEmbedded Torrent

2009-02-14T21:05:43Z

Cfriedt:

OpenEmbedded Torrent Instructions

2009-02-14T21:04:00Z

Cfriedt:

After downloading an [[OpenEmbedded Torrent]], there are two variables that need to be exported in the shell environment. The MACHINE and OE_HOME. Examples are used below, but please set the variables appropriately for your scenario. Also, please ensure that there are several gigabytes of disk space available in OE_HOME.

<pre>
export MACHINE=om-gta02
export OE_HOME=${HOME}/oe
</pre>

The following three variables are set here for the purpose of generality. They should be included in the name of your torrent file.

DISTRO=angstrom-2008.1
ARCH=x86_64-linux
TIMESTAMP=20090214
TARBALL_LOC=${HOME}

Please follow the following instructions for preparing the pre-compiled OpenEmbedded build environment.

<pre>
mkdir -p ${OE_HOME}
tar xpjf ${TARBALL_LOC}/openmoko-${MACHINE}-${DISTRO}-${ARCH}-${TIMESTAMP}.tar.bz2 -C ${OE_HOME}
cd ${OE_HOME}
echo ${OE_HOME}/build-${MACHINE}/tmp > ${OE_HOME}/build-${MACHINE}/tmp
source setup-env
</pre>

The next step is to rebuild non-portable packages required for native and cross compilation. All of such packages are pulled in via dependency, when building the 'console-image' recipe.

bitbake console-image

That's it! You are now ready to do system development or application development to your heart's content!

OpenEmbedded Torrent Instructions

2009-02-14T21:01:58Z

Cfriedt:

After downloading an [[OpenEmbedded Torrent]], there are two variables that need to be exported in the shell environment.

<pre>
export MACHINE=om-gta02
export OE_HOME=${HOME}/oe
</pre>

The following three variables are set here for the purpose of generality. They should be included in the name of your torrent file.

DISTRO=angstrom-2008.1
ARCH=x86_64-linux
TIMESTAMP=20090214
TARBALL_LOC=${HOME}

Please follow the following instructions for preparing the pre-compiled OpenEmbedded build environment.

<pre>
mkdir -p ${OE_HOME}
tar xpjf ${TARBALL_LOC}/openmoko-${MACHINE}-${DISTRO}-${ARCH}-${TIMESTAMP}.tar.bz2 -C ${OE_HOME}
cd ${OE_HOME}
echo ${OE_HOME}/build-${MACHINE}/tmp > ${OE_HOME}/build-${MACHINE}/tmp
source setup-env
</pre>

The next step is to rebuild non-portable packages required for native and cross compilation. All of such packages are pulled in via dependency, when building the 'console-image' recipe.

bitbake console-image

That's it! You are now ready to do system development or application development to your heart's content!

OpenEmbedded Torrent Instructions

2009-02-14T20:54:10Z

Cfriedt:

{{Note|Tcsh users should use "setenv VAR val" instead of "export VAR=val", and ". file" instead of 'source file'.}}

After downloading an [[OpenEmbedded Torrent]], there are two variables that need to be exported in the shell environment.

<pre>
export MACHINE=om-gta02
export OE_HOME=${HOME}/oe
</pre>

The following three variables are set here for the purpose of generality. They should be included in the name of your torrent file.

DISTRO=angstrom-2008.1
ARCH=x86_64-linux
TIMESTAMP=20090214
TARBALL_LOC=${HOME}

Please follow the following instructions for preparing the pre-compiled OpenEmbedded build environment.

<pre>
mkdir -p ${OE_HOME}
tar xpjf ${TARBALL_LOC}/openmoko-${MACHINE}-${DISTRO}-${ARCH}-${TIMESTAMP}.tar.bz2 -C ${OE_HOME}
cd ${OE_HOME}
echo ${OE_HOME}/build-${MACHINE}/tmp > ${OE_HOME}/build-${MACHINE}/tmp
source setup-env
</pre>

The next step is to rebuild non-portable packages required for native and cross compilation. All of such packages are pulled in via dependency, when building the 'console-image' recipe.

bitbake console-image

That's it! You are now ready to do system development or application development to your heart's content!

OpenEmbedded Torrent Instructions

2009-02-14T20:53:23Z

Cfriedt: New page: {{Note|Tcsh users should use 'setenv VAR val' instead of 'export VAR=val', and '. file' instead of 'source file'.}} After downloading an OpenEmbedded Torrent, there are two variables ...

{{Note|Tcsh users should use 'setenv VAR val' instead of 'export VAR=val', and '. file' instead of 'source file'.}}

After downloading an [[OpenEmbedded Torrent]], there are two variables that need to be exported in the shell environment.

<pre>
export MACHINE=om-gta02
export OE_HOME=${HOME}/oe
</pre>

The following three variables are set here for the purpose of generality. They should be included in the name of your torrent file.

DISTRO=angstrom-2008.1
ARCH=x86_64-linux
TIMESTAMP=20090214
TARBALL_LOC=${HOME}

Please follow the following instructions for preparing the pre-compiled OpenEmbedded build environment.

<pre>
mkdir -p ${OE_HOME}
tar xpjf ${TARBALL_LOC}/openmoko-${MACHINE}-${DISTRO}-${ARCH}-${TIMESTAMP}.tar.bz2 -C ${OE_HOME}
cd ${OE_HOME}
echo ${OE_HOME}/build-${MACHINE}/tmp > ${OE_HOME}/build-${MACHINE}/tmp
source setup-env
</pre>

The next step is to rebuild non-portable packages required for native and cross compilation. All of such packages are pulled in via dependency, when building the 'console-image' recipe.

bitbake console-image

That's it! You are now ready to do system development or application development to your heart's content!

OpenEmbedded Torrent

2009-02-14T20:33:59Z

Cfriedt: /* FAQ */

The following links are in place to provide developers with a pre-compiled [[OpenEmbedded]] build environment tailored to their workstation's architecture. In order to use BitTorrent files, it is necessary to install a [http://en.wikipedia.org/wiki/BitTorrent_client BitTorrent client].

The reason that these torrents are provided, is to decrease the amount of time it takes for system developers to have a fully functional build environment, allowing them to focus on more important tasks.

{{Note|A pre-compiled OE environment is several gigabytes in size. For example, an environment may be require 8GB to download and store, but it might require another 16 GB to uncompress. Please ensure that you have enough disk space before continuing.}}

Once the environment is downloaded via [http://en.wikipedia.org/wiki/BitTorrent BitTorrent], just follow these [http://wiki.openmoko.org/wiki/OpenEmbedded_Torrent_Instructions instructions], and go! See the list below for available torrents.

== Available Torrents ==

=== Linux Users ===

Torrents for Linux users

=== Mac OS X Users ===

Torrents for Mac OS X users

=== FreeBSD Users ===

Torrents for FreeBSD users

== FAQ ==

* '''Why does my environment rebuild gcc-cross, binutils-cross, libtool-native, ... ?'''

If every end-user had the same username and the same OE_HOME, then the cross-toolchain would be completely portable. However, that is generally not the case. The toolchain has compiled-in paths that contain system libraries and headers. If those paths change, then there is a very high probability that [http://en.wikipedia.org/wiki/Gremlin gremlins] might attack you, your loved ones, and your town, possibly ruining Christmas for everyone.

[[Category:Application Developer]]
[[Category:System Developers]]

OpenEmbedded Torrent

2009-02-14T20:33:10Z

Cfriedt: /* FAQ */

The following links are in place to provide developers with a pre-compiled [[OpenEmbedded]] build environment tailored to their workstation's architecture. In order to use BitTorrent files, it is necessary to install a [http://en.wikipedia.org/wiki/BitTorrent_client BitTorrent client].

The reason that these torrents are provided, is to decrease the amount of time it takes for system developers to have a fully functional build environment, allowing them to focus on more important tasks.

{{Note|A pre-compiled OE environment is several gigabytes in size. For example, an environment may be require 8GB to download and store, but it might require another 16 GB to uncompress. Please ensure that you have enough disk space before continuing.}}

Once the environment is downloaded via [http://en.wikipedia.org/wiki/BitTorrent BitTorrent], just follow these [http://wiki.openmoko.org/wiki/OpenEmbedded_Torrent_Instructions instructions], and go! See the list below for available torrents.

== Available Torrents ==

=== Linux Users ===

Torrents for Linux users

=== Mac OS X Users ===

Torrents for Mac OS X users

=== FreeBSD Users ===

Torrents for FreeBSD users

== FAQ ==

* '''Why does my environment rebuild gcc-cross, binutils-cross, and libtool-cross?'''

If every end-user had the same username and the same OE_HOME, then the cross-toolchain would be completely portable. However, that is generally not the case. The toolchain has compiled-in paths that contain system libraries and headers. If those paths change, then there is a very high probability that [http://en.wikipedia.org/wiki/Gremlin gremlins] might attack you, your loved ones, and your town, possibly ruining Christmas for everyone.

[[Category:Application Developer]]
[[Category:System Developers]]

OpenEmbedded Torrent

2009-02-14T20:32:27Z

Cfriedt:

The following links are in place to provide developers with a pre-compiled [[OpenEmbedded]] build environment tailored to their workstation's architecture. In order to use BitTorrent files, it is necessary to install a [http://en.wikipedia.org/wiki/BitTorrent_client BitTorrent client].

The reason that these torrents are provided, is to decrease the amount of time it takes for system developers to have a fully functional build environment, allowing them to focus on more important tasks.

{{Note|A pre-compiled OE environment is several gigabytes in size. For example, an environment may be require 8GB to download and store, but it might require another 16 GB to uncompress. Please ensure that you have enough disk space before continuing.}}

Once the environment is downloaded via [http://en.wikipedia.org/wiki/BitTorrent BitTorrent], just follow these [http://wiki.openmoko.org/wiki/OpenEmbedded_Torrent_Instructions instructions], and go! See the list below for available torrents.

== Available Torrents ==

=== Linux Users ===

Torrents for Linux users

=== Mac OS X Users ===

Torrents for Mac OS X users

=== FreeBSD Users ===

Torrents for FreeBSD users

== FAQ ==

Why does my environment rebuild gcc-cross, binutils-cross, and libtool-cross

If every end-user had the same username and the same OE_HOME, then the cross-toolchain would be completely portable. However, that is generally not the case. The toolchain has compiled-in paths that contain system libraries and headers. If those paths change, then there is a very high probability that [http://en.wikipedia.org/wiki/Gremlin gremlins] might attack you, your loved ones, and your town, possibly ruining Christmas for everyone.

[[Category:Application Developer]]
[[Category:System Developers]]

OpenEmbedded Torrent

2009-02-14T20:21:13Z

Cfriedt:

OpenEmbedded Torrent

2009-02-14T20:20:43Z

Cfriedt:

OpenEmbedded Torrent

2009-02-14T20:20:21Z

Cfriedt:

OpenEmbedded Torrent

2009-02-14T20:20:00Z

Cfriedt:

OpenEmbedded Torrent

2009-02-14T20:17:11Z

Cfriedt: /* Available Torrents */

OpenEmbedded Torrent

2009-02-14T20:15:02Z

Cfriedt:

OpenEmbedded

2009-02-10T19:57:30Z

Cfriedt: /* BitBake Overlays */

{{Languages|OpenEmbedded}}

Openmoko, our distribution, is built using OpenEmbedded. OpenEmbedded will:

* Generate (cross-compile) software packages for multiple embedded targets.
* Handle different hardware architectures, and support multiple releases across those architectures.

For more information please see the [http://www.openembedded.org/ Open Embedded] website.

== Building the OpenMoko Distribution with OpenEmbedded ==

'''Note:''' If you are an application developer, you probably do not want to build OpenEmbedded from scratch. For compiling simple applications with few library dependencies (including boot-loader and kernel), consider using our prebuilt [[Toolchain]]. For more complex applications with many library dependencies, download a prebuilt [[OpenEmbedded Torrent]].

Building OpenMoko from scratch is a time-, cpu- and diskspace-consuming process which should only be done if you are a system integrator and want to customize your OpenMoko distribution.

=== Simplified Instructions: MokoMakefile ===

For beginners who wish to customize their OpenMoko distribution, the facility called [[MokoMakefile]] simplifies building OpenEmbedded.

=== Quick Start: OpenEmbedded Torrent ===

If you are a system developer and would like to get up-to-speed as quickly as possible, then download an [[OpenEmbedded Torrent]].

== From Scratch: OpenEmbedded ==

Beginner OpenMoko developers who would prefer to have full control over their OpenEmbedded build environment should follow the instructions below.

=== Preparations ===

Several prerequisite software components are necessary in order to have a fully functional OpenEmbedded build environment. However, setup and installation varies depending on the operating system installed on your workstation. The [http://wiki.openembedded.net/index.php OpenEmbedded Wiki] provides [http://wiki.openembedded.net/index.php/OEandYourDistro setup instructions] for FreeBSD, Mac OS X, and most major Linux distributions, of course.

For OpenEmbedded installation instructions please refer to [http://wiki.openembedded.net/index.php/OEandYourDistro OEandYourDistro].

=== ${OE_HOME} ===

Assuming that you have installed all prerequisite software, you are now ready to create a directory for all of your OpenEmbedded (OE) related work. We will refer to OE_HOME in a generic way, but for argument's sake, assume that it is equal to ${HOME}/oe. You should expect ${OE_HOME} to grow tremendously in size, up to approximately 8GB or larger in some cases. Also be aware, that a full OE build could require several hours of constant building, which may inhibit the performance of your computer while performing other tasks. Replace ${HOME}/oe with your preferred location.

For Bash users:
export OE_HOME=${HOME}/oe

For Tcsh users:
setenv OE_HOME ${HOME}/oe

Next, run 'mkdir -p ${OE_HOME}' to create the directory.

=== Synchronizing OpenEmbedded With Git ===

Just like any tree, OpenEmbedded has several branches. In this case they are called 'development branches'. Some noteworthy ones include org.openembedded.dev (the default) and org.openembedded.stable .

To syncronize the OpenEmbedded tree, run
<pre>
git clone git://git.openembedded.net/openembedded ${OE_HOME}/org.openembedded.dev
</pre>

Note that last argument could be any directory name (git will create the directory if it doesn't exist). Sticking to 'good convention', the directory name was chosen to reflect the default development branch, org.openembedded.dev . See the [http://wiki.openembedded.net/index.php/GitPhraseBook OE GitPhraseBook] for more info on checking out different branches.

To update the tree, run
<pre>
cd ${OE_HOME}/org.openembedded.dev
git pull
</pre>

For further information on Git, see [http://git-scm.com The Git Homepage].

Also, please explore the directory structure of the OpenEmbedded build tree. Take a few moments to inspect the different types of BitBake files (.bbclass, .bb, .inc, etc). This helps one to become familiar with recipe syntax and the inheritance system. Of particular note, please read the file 'local.conf.sample'.
<pre>
org.openembedded.dev
|-- classes
| |-- rootfs_ipk.bbclass
| `-- xorg-module.bbclass
|-- conf
| `-- local.conf.sample
| |-- distro
| | `-- angstrom-2008.1.conf
| |-- machine
| | |-- om-gta01.conf
| | `-- om-gta02.conf
`-- packages
|-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- images
|-- console-image.bb
|-- fso-console-image.bb
|-- fso-image.bb
|-- openmoko-image.bb
|-- opie-image.bb
`-- x11-image.bb
</pre>

=== local.conf ===

If you explored local.conf.example, then you would be aware that there are some very important variables to be set like MACHINE, DISTRO, and BBFILES, among many others. This is done in a configuration file (local.conf) inside the build directory.

'''Note:''' Using BitBake and OE for cross-compilation require that each target-distro combination is built in a separate directory, so that no version collisions occur. Concurrent builds may safely share the same DL_DIR though. This would suggest that a safe name for build directories is of the form ${OE_HOME}/build-${MACHINE}-${DISTRO}. Of course, if you don't plan on building for more than one machine-distro combination, then the naming of this directory is arbitrary. For the purpose of this example, we will use the convention ${OE_HOME}/build-${MACHINE} .

Now, create the 'local.conf' configuration file. Notice that the CACHE and TMPDIR variables are neatly kept within the build directory while the DL_DIR variable is outside of the build directory, so that concurrent builds may reuse the same source packages.
<pre>
OE_HOME ?= "${HOME}/oe"

MACHINE = "om-gta02"
DISTRO = "angstrom-2008.1"

DL_DIR = "${OE_HOME}/downloads"

BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"

BBMASK = ""

TMPDIR = "${OE_HOME}/build-${MACHINE}/tmp"
CACHE = "${TMPDIR}/cache"

IMAGE_FSTYPES = "jffs2 tar.gz"

ENABLE_BINARY_LOCALE_GENERATION = "0"
</pre>

The BBFILES variable is also of prime importance! It tells bitbake where to locate all available recipes for a build. The OpenEmbedded build environment is almost completely ready to go, with just one more minor step left.

=== setup-env ===

For quick and easy initialization of the OpenEmbedded build environment, it is often suggested that the developer create a 'setup-env' script to source from the command line. This script can be called to initialize the most important of environment variables. Below is a very basic example of a setup-env script.

setup-env for Bash users:
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02
export BBPATH=${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
setup-env for Tcsh users:
<pre>
[[ -z ${OE_HOME} ]] && setenv OE_HOME ${HOME}/oe
[[ -z ${MACHINE} ]] && setenv MACHINE om-gta02
setenv BBPATH ${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
To invoke the setup-env script in bash, run 'source setup-env'. In tcsh, run '. setup-env'.

See the section entitled [http://wiki.openmoko.org/wiki/OpenEmbedded#BitBake_Overlays BitBake Overlays] for an example of a more complicated setup-env script.

=== Testing the OE Build Environment ===

That's it! Now you should be prepared to bake your first BitBake recipe.

bitbake helloworld

=== Building an Image ===

There are several full filesystem images which can be built directly with OpenEmbedded using a single command. These include openmoko-image, fso-image, and so on. The image definitions can be found under ${OE_HOME}/org.openembedded.dev/packages/images

A good place to start is with

bitbake fso-image

That concludes this introduction to BitBake and OpenEmbedded. Good luck!

=== Other References ===

Please feel free to refer to other online sources of information for [http://bitbake.berlios.de BitBake], [http://www.openembedded.org OpenEmbedded], and the [http://www.angstrom-distribution.org Angstrom Distribution] to name a few.

== Broken Builds and Bug Reporting ==

Using the org.openembedded.dev branch can often result in broken builds. For that reason, it is usually a good idea to limit synchronizing with the repository only after successfully building an image. Some may even want to archive the tree and build directory after an image is built.

Now in the case that an image does not successfully build, it is not always necessarily a bug or a new bug. The problem might have to do with some conflicting software on the workstation, and it could be a bug that is already know and being fixed.

Below are a few useful steps to follow when a build does not successfully complete:

* Identify the package that failed to build
** Find a line near the bottom of your output that matches "ERROR: ... failed" or "NOTE: ... failed". The name of the package should be contained in the '...'
* If there is a similar, more stable version in ${OE_HOME}/org.openembedded.dev/packages, then try to use that instead
** bitbake -c clean somepackage && bitbake -b ${OE_HOME}/org.openembedded.dev/packages/somepackage/somepackage_0.1.bb
** add PREFERRED_VERSION_somepackage = "0.1" to local.conf
* Read the BitBake log, as well as config.log if it exists
** Find the log file. There should be a line near the bottom of your output that matches "ERROR: see log in ...", where '...' contains the log file name. These are usually of the form log.do_compile.12345 or log.do_configure.12345, etc.
* Try to identify the root cause of the error
** In many cases, if one examines log.do_configure, only the error is reported, but not the cause of the error
** Most packages that build with autotools will also have a config.log file that contains the exact cause of the error
* If you can fix the error, and the error is local to your workstation, and not really a bug, then fix the error yourself.
* Otherwise, check the [http://bugs.openembedded.net OpenEmbedded Bugzilla] to see if the error is known.
* If a solution is already available, then try it out. If you can fix the error, then do so. If your solution is correct, please post all relevent patches to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

=== Where to Report Bugs ===

Authentic bugs should be reported to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

== Tips & Tricks ==

=== Setting the PREFERRED_VERSION for a package ===

If a certain package is known to not build, and there is a less recent / more stable version of that package, then a good way to avoid repetitive encounters with known build failures is to use preferred versions of packages.

For example, if building gcc-4.2.4 constantly failed, then it would be wise to edit local.conf and set PREFERRED_VERSION_gcc = "4.1.2".

=== Screen is Your Friend ===

If you happen to be building all of your packages remotely on a server, using an ssh session, the session might occasionally be interrupted and the connection could be terminated. A similar event could occur if your X server suddenly craches. If in the process of building an image with bitbake, this means that the build process will terminate as well.

In order to ensure that a build continues in the presence of communication failures, it is advisable to use the [http://www.gnu.org/software/screen GNU Screen] utility. Screen is also very useful when performing several concurrent OpenEmbedded builds for different machine-distro combinations.

Screen installation varies with your OS and distribution.

=== BitBake Overlays ===

Bitbake overlays are useful for OpenEmbedded developers to eliminate bugs or package software without disturbiing the OpenEmbedded tree itself. Overlays are very similar in structure to the OpenEmbedded tree, but are usually only sparsely populated. Non-sparsely poplulated overlays are actually more closely related to separate development branches. Good convention would suggest to always name the overlay appropriately.

Below is an example of two overlays, three build directories, a setup-env script, and a local.conf where the developer has multiple build targets as well as multiple BitBake overlays.
<pre>
oe
|-- build-beagleboard
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-om-gta02
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-ts72xx
| |-- conf
| | `-- local.conf
| `-- tmp
|-- com.somecompany.dev
| |-- conf
| | `-- machine
| `-- packages
| |-- images
| | `-- console-image.bb
| `-- rxtx
| |-- files
| |-- rxtx-fixes-from-debian.patch
| `-- rxtx_2.1-7r2.bb
|-- org.openembedded.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- images
|-- org.openmoko.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- setup-env
</pre>

An example of the setup-env script with multiple overlays and multiple build targets is below.

<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02

unset BBPATH

case "${MACHINE}" in
"beagleboard" | "ts72xx" )
BBPATH="${OE_HOME}/com.somecompany.dev"
;;
"om-gta02")
BBPATH="${OE_HOME}/org.openmoko.dev"
;;
*)
echo -e "error: unsupported machine"
exit -1
;;
esac

export BBPATH=${BBPATH}:${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>

Note that the overlay-specific BBPATH entry ''precedes'' the default BBPATH entries.

Next, observe the changes necessary for local.conf in order to use a specific overlay (in this case org.openmoko.dev).

<pre>
...
BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"
BBFILES += " ${OE_HOME}/org.openmoko.dev/packages/*/*.bb"

BBFILE_COLLECTIONS = "upstream moko"
BBFILE_PATTERN_upstream = "${OE_HOME}/org.openembedded.dev"
BBFILE_PRIORITY_upstream = "0"
BBFILE_PATTERN_moko = "${OE_HOME}/org.openmoko.dev"
BBFILE_PRIORITY_moko = "1"
...
</pre>

In order for the overlay to be detected by BitBake, the above variables need to be defined in the local.conf file. It is possible to include more than one overlay. For each overlay, add a separate BBFILES += statement, an entry in BBFILE_COLLECTIONS, a BBFILE_PATTERN, and BBFILE_PRIORITY. Remember to include at least one space (' ') between each BBFILES entry.

=== Useful BitBake Commands ===

<pre>
# list all of the tasks defined for a given package_name
bitbake -c listtasks <package_name>

# clean the work directory for a specific package
bitbake -c clean <package_name>

# build a specific recipe
bitbake -b <path/to/some/recipe.bb>
</pre>

[[Category:Application Developer]]
[[Category:System Developers]]

OpenEmbedded

2009-02-10T19:51:52Z

Cfriedt: /* BitBake Overlays */

{{Languages|OpenEmbedded}}

Openmoko, our distribution, is built using OpenEmbedded. OpenEmbedded will:

* Generate (cross-compile) software packages for multiple embedded targets.
* Handle different hardware architectures, and support multiple releases across those architectures.

For more information please see the [http://www.openembedded.org/ Open Embedded] website.

== Building the OpenMoko Distribution with OpenEmbedded ==

'''Note:''' If you are an application developer, you probably do not want to build OpenEmbedded from scratch. For compiling simple applications with few library dependencies (including boot-loader and kernel), consider using our prebuilt [[Toolchain]]. For more complex applications with many library dependencies, download a prebuilt [[OpenEmbedded Torrent]].

Building OpenMoko from scratch is a time-, cpu- and diskspace-consuming process which should only be done if you are a system integrator and want to customize your OpenMoko distribution.

=== Simplified Instructions: MokoMakefile ===

For beginners who wish to customize their OpenMoko distribution, the facility called [[MokoMakefile]] simplifies building OpenEmbedded.

=== Quick Start: OpenEmbedded Torrent ===

If you are a system developer and would like to get up-to-speed as quickly as possible, then download an [[OpenEmbedded Torrent]].

== From Scratch: OpenEmbedded ==

Beginner OpenMoko developers who would prefer to have full control over their OpenEmbedded build environment should follow the instructions below.

=== Preparations ===

Several prerequisite software components are necessary in order to have a fully functional OpenEmbedded build environment. However, setup and installation varies depending on the operating system installed on your workstation. The [http://wiki.openembedded.net/index.php OpenEmbedded Wiki] provides [http://wiki.openembedded.net/index.php/OEandYourDistro setup instructions] for FreeBSD, Mac OS X, and most major Linux distributions, of course.

For OpenEmbedded installation instructions please refer to [http://wiki.openembedded.net/index.php/OEandYourDistro OEandYourDistro].

=== ${OE_HOME} ===

Assuming that you have installed all prerequisite software, you are now ready to create a directory for all of your OpenEmbedded (OE) related work. We will refer to OE_HOME in a generic way, but for argument's sake, assume that it is equal to ${HOME}/oe. You should expect ${OE_HOME} to grow tremendously in size, up to approximately 8GB or larger in some cases. Also be aware, that a full OE build could require several hours of constant building, which may inhibit the performance of your computer while performing other tasks. Replace ${HOME}/oe with your preferred location.

For Bash users:
export OE_HOME=${HOME}/oe

For Tcsh users:
setenv OE_HOME ${HOME}/oe

Next, run 'mkdir -p ${OE_HOME}' to create the directory.

=== Synchronizing OpenEmbedded With Git ===

Just like any tree, OpenEmbedded has several branches. In this case they are called 'development branches'. Some noteworthy ones include org.openembedded.dev (the default) and org.openembedded.stable .

To syncronize the OpenEmbedded tree, run
<pre>
git clone git://git.openembedded.net/openembedded ${OE_HOME}/org.openembedded.dev
</pre>

Note that last argument could be any directory name (git will create the directory if it doesn't exist). Sticking to 'good convention', the directory name was chosen to reflect the default development branch, org.openembedded.dev . See the [http://wiki.openembedded.net/index.php/GitPhraseBook OE GitPhraseBook] for more info on checking out different branches.

To update the tree, run
<pre>
cd ${OE_HOME}/org.openembedded.dev
git pull
</pre>

For further information on Git, see [http://git-scm.com The Git Homepage].

Also, please explore the directory structure of the OpenEmbedded build tree. Take a few moments to inspect the different types of BitBake files (.bbclass, .bb, .inc, etc). This helps one to become familiar with recipe syntax and the inheritance system. Of particular note, please read the file 'local.conf.sample'.
<pre>
org.openembedded.dev
|-- classes
| |-- rootfs_ipk.bbclass
| `-- xorg-module.bbclass
|-- conf
| `-- local.conf.sample
| |-- distro
| | `-- angstrom-2008.1.conf
| |-- machine
| | |-- om-gta01.conf
| | `-- om-gta02.conf
`-- packages
|-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- images
|-- console-image.bb
|-- fso-console-image.bb
|-- fso-image.bb
|-- openmoko-image.bb
|-- opie-image.bb
`-- x11-image.bb
</pre>

=== local.conf ===

If you explored local.conf.example, then you would be aware that there are some very important variables to be set like MACHINE, DISTRO, and BBFILES, among many others. This is done in a configuration file (local.conf) inside the build directory.

'''Note:''' Using BitBake and OE for cross-compilation require that each target-distro combination is built in a separate directory, so that no version collisions occur. Concurrent builds may safely share the same DL_DIR though. This would suggest that a safe name for build directories is of the form ${OE_HOME}/build-${MACHINE}-${DISTRO}. Of course, if you don't plan on building for more than one machine-distro combination, then the naming of this directory is arbitrary. For the purpose of this example, we will use the convention ${OE_HOME}/build-${MACHINE} .

Now, create the 'local.conf' configuration file. Notice that the CACHE and TMPDIR variables are neatly kept within the build directory while the DL_DIR variable is outside of the build directory, so that concurrent builds may reuse the same source packages.
<pre>
OE_HOME ?= "${HOME}/oe"

MACHINE = "om-gta02"
DISTRO = "angstrom-2008.1"

DL_DIR = "${OE_HOME}/downloads"

BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"

BBMASK = ""

TMPDIR = "${OE_HOME}/build-${MACHINE}/tmp"
CACHE = "${TMPDIR}/cache"

IMAGE_FSTYPES = "jffs2 tar.gz"

ENABLE_BINARY_LOCALE_GENERATION = "0"
</pre>

The BBFILES variable is also of prime importance! It tells bitbake where to locate all available recipes for a build. The OpenEmbedded build environment is almost completely ready to go, with just one more minor step left.

=== setup-env ===

For quick and easy initialization of the OpenEmbedded build environment, it is often suggested that the developer create a 'setup-env' script to source from the command line. This script can be called to initialize the most important of environment variables. Below is a very basic example of a setup-env script.

setup-env for Bash users:
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02
export BBPATH=${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
setup-env for Tcsh users:
<pre>
[[ -z ${OE_HOME} ]] && setenv OE_HOME ${HOME}/oe
[[ -z ${MACHINE} ]] && setenv MACHINE om-gta02
setenv BBPATH ${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
To invoke the setup-env script in bash, run 'source setup-env'. In tcsh, run '. setup-env'.

See the section entitled [http://wiki.openmoko.org/wiki/OpenEmbedded#BitBake_Overlays BitBake Overlays] for an example of a more complicated setup-env script.

=== Testing the OE Build Environment ===

That's it! Now you should be prepared to bake your first BitBake recipe.

bitbake helloworld

=== Building an Image ===

There are several full filesystem images which can be built directly with OpenEmbedded using a single command. These include openmoko-image, fso-image, and so on. The image definitions can be found under ${OE_HOME}/org.openembedded.dev/packages/images

A good place to start is with

bitbake fso-image

That concludes this introduction to BitBake and OpenEmbedded. Good luck!

=== Other References ===

Please feel free to refer to other online sources of information for [http://bitbake.berlios.de BitBake], [http://www.openembedded.org OpenEmbedded], and the [http://www.angstrom-distribution.org Angstrom Distribution] to name a few.

== Broken Builds and Bug Reporting ==

Using the org.openembedded.dev branch can often result in broken builds. For that reason, it is usually a good idea to limit synchronizing with the repository only after successfully building an image. Some may even want to archive the tree and build directory after an image is built.

Now in the case that an image does not successfully build, it is not always necessarily a bug or a new bug. The problem might have to do with some conflicting software on the workstation, and it could be a bug that is already know and being fixed.

Below are a few useful steps to follow when a build does not successfully complete:

* Identify the package that failed to build
** Find a line near the bottom of your output that matches "ERROR: ... failed" or "NOTE: ... failed". The name of the package should be contained in the '...'
* If there is a similar, more stable version in ${OE_HOME}/org.openembedded.dev/packages, then try to use that instead
** bitbake -c clean somepackage && bitbake -b ${OE_HOME}/org.openembedded.dev/packages/somepackage/somepackage_0.1.bb
** add PREFERRED_VERSION_somepackage = "0.1" to local.conf
* Read the BitBake log, as well as config.log if it exists
** Find the log file. There should be a line near the bottom of your output that matches "ERROR: see log in ...", where '...' contains the log file name. These are usually of the form log.do_compile.12345 or log.do_configure.12345, etc.
* Try to identify the root cause of the error
** In many cases, if one examines log.do_configure, only the error is reported, but not the cause of the error
** Most packages that build with autotools will also have a config.log file that contains the exact cause of the error
* If you can fix the error, and the error is local to your workstation, and not really a bug, then fix the error yourself.
* Otherwise, check the [http://bugs.openembedded.net OpenEmbedded Bugzilla] to see if the error is known.
* If a solution is already available, then try it out. If you can fix the error, then do so. If your solution is correct, please post all relevent patches to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

=== Where to Report Bugs ===

Authentic bugs should be reported to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

== Tips & Tricks ==

=== Setting the PREFERRED_VERSION for a package ===

If a certain package is known to not build, and there is a less recent / more stable version of that package, then a good way to avoid repetitive encounters with known build failures is to use preferred versions of packages.

For example, if building gcc-4.2.4 constantly failed, then it would be wise to edit local.conf and set PREFERRED_VERSION_gcc = "4.1.2".

=== Screen is Your Friend ===

If you happen to be building all of your packages remotely on a server, using an ssh session, the session might occasionally be interrupted and the connection could be terminated. A similar event could occur if your X server suddenly craches. If in the process of building an image with bitbake, this means that the build process will terminate as well.

In order to ensure that a build continues in the presence of communication failures, it is advisable to use the [http://www.gnu.org/software/screen GNU Screen] utility. Screen is also very useful when performing several concurrent OpenEmbedded builds for different machine-distro combinations.

Screen installation varies with your OS and distribution.

=== BitBake Overlays ===

Bitbake overlays are useful for OpenEmbedded developers to eliminate bugs or package software without disturbiing the OpenEmbedded tree itself. Overlays are very similar in structure to the OpenEmbedded tree, but are usually only sparsely populated. Non-sparsely poplulated overlays are actually more closely related to separate development branches. Good convention would suggest to always name the overlay appropriately.

Below is an example of two overlays, three build directories, a setup-env script, and a local.conf where the developer has multiple build targets as well as multiple BitBake overlays.
<pre>
oe
|-- build-beagleboard
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-om-gta02
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-ts72xx
| |-- conf
| | `-- local.conf
| `-- tmp
|-- com.somecompany.dev
| |-- conf
| | `-- machine
| `-- packages
| |-- images
| | `-- console-image.bb
| `-- rxtx
| |-- files
| |-- rxtx-fixes-from-debian.patch
| `-- rxtx_2.1-7r2.bb
|-- org.openembedded.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- images
|-- org.openmoko.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- setup-env
</pre>
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02

unset BBPATH

case "${MACHINE}" in
"beagleboard" | "ts72xx" )
BBPATH="${OE_HOME}/com.somecompany.dev"
;;
"om-gta02")
BBPATH="${OE_HOME}/org.openmoko.dev"
;;
*)
echo -e "error: unsupported machine"
exit -1
;;
esac

export BBPATH=${BBPATH}:${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>

Note that the overlay-specific BBPATH entry ''precedes'' the default BBPATH entries.

<pre>
...
BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"
BBFILES += " ${OE_HOME}/org.openmoko.dev/packages/*/*.bb"

BBFILE_COLLECTIONS = "upstream local"
BBFILE_PATTERN_upstream = "${OE_HOME}/org.openembedded.dev"
BBFILE_PRIORITY_upstream = "0"
BBFILE_PATTERN_local = "${OE_HOME}/org.openmoko.dev"
BBFILE_PRIORITY_local = "1"
...
</pre>

In order for the overlay to be detected by BitBake, the above variables need to be defined. It is possible to have more than one overlay and each one should be given a different priority.

=== Useful BitBake Commands ===

<pre>
# list all of the tasks defined for a given package_name
bitbake -c listtasks <package_name>

# clean the work directory for a specific package
bitbake -c clean <package_name>

# build a specific recipe
bitbake -b <path/to/some/recipe.bb>
</pre>

[[Category:Application Developer]]
[[Category:System Developers]]

OpenEmbedded

2009-02-10T19:47:55Z

Cfriedt: /* Build Environment */

{{Languages|OpenEmbedded}}

Openmoko, our distribution, is built using OpenEmbedded. OpenEmbedded will:

* Generate (cross-compile) software packages for multiple embedded targets.
* Handle different hardware architectures, and support multiple releases across those architectures.

For more information please see the [http://www.openembedded.org/ Open Embedded] website.

== Building the OpenMoko Distribution with OpenEmbedded ==

'''Note:''' If you are an application developer, you probably do not want to build OpenEmbedded from scratch. For compiling simple applications with few library dependencies (including boot-loader and kernel), consider using our prebuilt [[Toolchain]]. For more complex applications with many library dependencies, download a prebuilt [[OpenEmbedded Torrent]].

Building OpenMoko from scratch is a time-, cpu- and diskspace-consuming process which should only be done if you are a system integrator and want to customize your OpenMoko distribution.

=== Simplified Instructions: MokoMakefile ===

For beginners who wish to customize their OpenMoko distribution, the facility called [[MokoMakefile]] simplifies building OpenEmbedded.

=== Quick Start: OpenEmbedded Torrent ===

If you are a system developer and would like to get up-to-speed as quickly as possible, then download an [[OpenEmbedded Torrent]].

== From Scratch: OpenEmbedded ==

Beginner OpenMoko developers who would prefer to have full control over their OpenEmbedded build environment should follow the instructions below.

=== Preparations ===

Several prerequisite software components are necessary in order to have a fully functional OpenEmbedded build environment. However, setup and installation varies depending on the operating system installed on your workstation. The [http://wiki.openembedded.net/index.php OpenEmbedded Wiki] provides [http://wiki.openembedded.net/index.php/OEandYourDistro setup instructions] for FreeBSD, Mac OS X, and most major Linux distributions, of course.

For OpenEmbedded installation instructions please refer to [http://wiki.openembedded.net/index.php/OEandYourDistro OEandYourDistro].

=== ${OE_HOME} ===

Assuming that you have installed all prerequisite software, you are now ready to create a directory for all of your OpenEmbedded (OE) related work. We will refer to OE_HOME in a generic way, but for argument's sake, assume that it is equal to ${HOME}/oe. You should expect ${OE_HOME} to grow tremendously in size, up to approximately 8GB or larger in some cases. Also be aware, that a full OE build could require several hours of constant building, which may inhibit the performance of your computer while performing other tasks. Replace ${HOME}/oe with your preferred location.

For Bash users:
export OE_HOME=${HOME}/oe

For Tcsh users:
setenv OE_HOME ${HOME}/oe

Next, run 'mkdir -p ${OE_HOME}' to create the directory.

=== Synchronizing OpenEmbedded With Git ===

Just like any tree, OpenEmbedded has several branches. In this case they are called 'development branches'. Some noteworthy ones include org.openembedded.dev (the default) and org.openembedded.stable .

To syncronize the OpenEmbedded tree, run
<pre>
git clone git://git.openembedded.net/openembedded ${OE_HOME}/org.openembedded.dev
</pre>

Note that last argument could be any directory name (git will create the directory if it doesn't exist). Sticking to 'good convention', the directory name was chosen to reflect the default development branch, org.openembedded.dev . See the [http://wiki.openembedded.net/index.php/GitPhraseBook OE GitPhraseBook] for more info on checking out different branches.

To update the tree, run
<pre>
cd ${OE_HOME}/org.openembedded.dev
git pull
</pre>

For further information on Git, see [http://git-scm.com The Git Homepage].

Also, please explore the directory structure of the OpenEmbedded build tree. Take a few moments to inspect the different types of BitBake files (.bbclass, .bb, .inc, etc). This helps one to become familiar with recipe syntax and the inheritance system. Of particular note, please read the file 'local.conf.sample'.
<pre>
org.openembedded.dev
|-- classes
| |-- rootfs_ipk.bbclass
| `-- xorg-module.bbclass
|-- conf
| `-- local.conf.sample
| |-- distro
| | `-- angstrom-2008.1.conf
| |-- machine
| | |-- om-gta01.conf
| | `-- om-gta02.conf
`-- packages
|-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- images
|-- console-image.bb
|-- fso-console-image.bb
|-- fso-image.bb
|-- openmoko-image.bb
|-- opie-image.bb
`-- x11-image.bb
</pre>

=== local.conf ===

If you explored local.conf.example, then you would be aware that there are some very important variables to be set like MACHINE, DISTRO, and BBFILES, among many others. This is done in a configuration file (local.conf) inside the build directory.

'''Note:''' Using BitBake and OE for cross-compilation require that each target-distro combination is built in a separate directory, so that no version collisions occur. Concurrent builds may safely share the same DL_DIR though. This would suggest that a safe name for build directories is of the form ${OE_HOME}/build-${MACHINE}-${DISTRO}. Of course, if you don't plan on building for more than one machine-distro combination, then the naming of this directory is arbitrary. For the purpose of this example, we will use the convention ${OE_HOME}/build-${MACHINE} .

Now, create the 'local.conf' configuration file. Notice that the CACHE and TMPDIR variables are neatly kept within the build directory while the DL_DIR variable is outside of the build directory, so that concurrent builds may reuse the same source packages.
<pre>
OE_HOME ?= "${HOME}/oe"

MACHINE = "om-gta02"
DISTRO = "angstrom-2008.1"

DL_DIR = "${OE_HOME}/downloads"

BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"

BBMASK = ""

TMPDIR = "${OE_HOME}/build-${MACHINE}/tmp"
CACHE = "${TMPDIR}/cache"

IMAGE_FSTYPES = "jffs2 tar.gz"

ENABLE_BINARY_LOCALE_GENERATION = "0"
</pre>

The BBFILES variable is also of prime importance! It tells bitbake where to locate all available recipes for a build. The OpenEmbedded build environment is almost completely ready to go, with just one more minor step left.

=== setup-env ===

For quick and easy initialization of the OpenEmbedded build environment, it is often suggested that the developer create a 'setup-env' script to source from the command line. This script can be called to initialize the most important of environment variables. Below is a very basic example of a setup-env script.

setup-env for Bash users:
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02
export BBPATH=${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
setup-env for Tcsh users:
<pre>
[[ -z ${OE_HOME} ]] && setenv OE_HOME ${HOME}/oe
[[ -z ${MACHINE} ]] && setenv MACHINE om-gta02
setenv BBPATH ${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
To invoke the setup-env script in bash, run 'source setup-env'. In tcsh, run '. setup-env'.

See the section entitled [http://wiki.openmoko.org/wiki/OpenEmbedded#BitBake_Overlays BitBake Overlays] for an example of a more complicated setup-env script.

=== Testing the OE Build Environment ===

That's it! Now you should be prepared to bake your first BitBake recipe.

bitbake helloworld

=== Building an Image ===

There are several full filesystem images which can be built directly with OpenEmbedded using a single command. These include openmoko-image, fso-image, and so on. The image definitions can be found under ${OE_HOME}/org.openembedded.dev/packages/images

A good place to start is with

bitbake fso-image

That concludes this introduction to BitBake and OpenEmbedded. Good luck!

=== Other References ===

Please feel free to refer to other online sources of information for [http://bitbake.berlios.de BitBake], [http://www.openembedded.org OpenEmbedded], and the [http://www.angstrom-distribution.org Angstrom Distribution] to name a few.

== Broken Builds and Bug Reporting ==

Using the org.openembedded.dev branch can often result in broken builds. For that reason, it is usually a good idea to limit synchronizing with the repository only after successfully building an image. Some may even want to archive the tree and build directory after an image is built.

Now in the case that an image does not successfully build, it is not always necessarily a bug or a new bug. The problem might have to do with some conflicting software on the workstation, and it could be a bug that is already know and being fixed.

Below are a few useful steps to follow when a build does not successfully complete:

* Identify the package that failed to build
** Find a line near the bottom of your output that matches "ERROR: ... failed" or "NOTE: ... failed". The name of the package should be contained in the '...'
* If there is a similar, more stable version in ${OE_HOME}/org.openembedded.dev/packages, then try to use that instead
** bitbake -c clean somepackage && bitbake -b ${OE_HOME}/org.openembedded.dev/packages/somepackage/somepackage_0.1.bb
** add PREFERRED_VERSION_somepackage = "0.1" to local.conf
* Read the BitBake log, as well as config.log if it exists
** Find the log file. There should be a line near the bottom of your output that matches "ERROR: see log in ...", where '...' contains the log file name. These are usually of the form log.do_compile.12345 or log.do_configure.12345, etc.
* Try to identify the root cause of the error
** In many cases, if one examines log.do_configure, only the error is reported, but not the cause of the error
** Most packages that build with autotools will also have a config.log file that contains the exact cause of the error
* If you can fix the error, and the error is local to your workstation, and not really a bug, then fix the error yourself.
* Otherwise, check the [http://bugs.openembedded.net OpenEmbedded Bugzilla] to see if the error is known.
* If a solution is already available, then try it out. If you can fix the error, then do so. If your solution is correct, please post all relevent patches to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

=== Where to Report Bugs ===

Authentic bugs should be reported to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

== Tips & Tricks ==

=== Setting the PREFERRED_VERSION for a package ===

If a certain package is known to not build, and there is a less recent / more stable version of that package, then a good way to avoid repetitive encounters with known build failures is to use preferred versions of packages.

For example, if building gcc-4.2.4 constantly failed, then it would be wise to edit local.conf and set PREFERRED_VERSION_gcc = "4.1.2".

=== Screen is Your Friend ===

If you happen to be building all of your packages remotely on a server, using an ssh session, the session might occasionally be interrupted and the connection could be terminated. A similar event could occur if your X server suddenly craches. If in the process of building an image with bitbake, this means that the build process will terminate as well.

In order to ensure that a build continues in the presence of communication failures, it is advisable to use the [http://www.gnu.org/software/screen GNU Screen] utility. Screen is also very useful when performing several concurrent OpenEmbedded builds for different machine-distro combinations.

Screen installation varies with your OS and distribution.

=== BitBake Overlays ===

Bitbake overlays are useful for OpenEmbedded developers to eliminate bugs or package software without disturbiing the OpenEmbedded tree itself. Overlays are very similar in structure to the OpenEmbedded tree, but are usually only sparsely populated. Non-sparsely poplulated overlays are actually more closely relatedd to separate development branches. Good convention would suggest to always name the overlay appropriately.

Below is an example of two overlays, three build directories, a setup-env script, and a local.conf where the developer has multiple build targets as well as multiple BitBake overlays.
<pre>
oe
|-- build-beagleboard
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-om-gta02
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-ts72xx
| |-- conf
| | `-- local.conf
| `-- tmp
|-- com.somecompany.dev
| |-- conf
| | `-- machine
| `-- packages
| |-- images
| | `-- console-image.bb
| `-- rxtx
| |-- files
| |-- rxtx-fixes-from-debian.patch
| `-- rxtx_2.1-7r2.bb
|-- org.openembedded.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- images
|-- org.openmoko.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- setup-env
</pre>
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02

unset BBPATH

case "${MACHINE}" in
"beagleboard" | "ts72xx" )
BBPATH="${OE_HOME}/com.somecompany.dev"
;;
"om-gta02")
BBPATH="${OE_HOME}/org.openmoko.dev"
;;
*)
echo -e "error: unsupported machine"
exit -1
;;
esac

export BBPATH=${BBPATH}:${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>

Note that the overlay-specific BBPATH entry ''precedes'' the default BBPATH entries.

<pre>
...
BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"
BBFILES += " ${OE_HOME}/org.openmoko.dev/packages/*/*.bb"

BBFILE_COLLECTIONS = "upstream local"
BBFILE_PATTERN_upstream = "${OE_HOME}/org.openembedded.dev"
BBFILE_PRIORITY_upstream = "0"
BBFILE_PATTERN_local = "${OE_HOME}/org.openmoko.dev"
BBFILE_PRIORITY_local = "1"
...
</pre>

In order for the overlay to be detected by BitBake, the above variables need to be defined. It is possible to have more than one overlay and each one should be given a different priority.

=== Useful BitBake Commands ===

<pre>
# list all of the tasks defined for a given package_name
bitbake -c listtasks <package_name>

# clean the work directory for a specific package
bitbake -c clean <package_name>

# build a specific recipe
bitbake -b <path/to/some/recipe.bb>
</pre>

[[Category:Application Developer]]
[[Category:System Developers]]

OpenEmbedded

2009-02-10T19:47:32Z

Cfriedt: /* Build Configuration */

{{Languages|OpenEmbedded}}

Openmoko, our distribution, is built using OpenEmbedded. OpenEmbedded will:

* Generate (cross-compile) software packages for multiple embedded targets.
* Handle different hardware architectures, and support multiple releases across those architectures.

For more information please see the [http://www.openembedded.org/ Open Embedded] website.

== Building the OpenMoko Distribution with OpenEmbedded ==

'''Note:''' If you are an application developer, you probably do not want to build OpenEmbedded from scratch. For compiling simple applications with few library dependencies (including boot-loader and kernel), consider using our prebuilt [[Toolchain]]. For more complex applications with many library dependencies, download a prebuilt [[OpenEmbedded Torrent]].

Building OpenMoko from scratch is a time-, cpu- and diskspace-consuming process which should only be done if you are a system integrator and want to customize your OpenMoko distribution.

=== Simplified Instructions: MokoMakefile ===

For beginners who wish to customize their OpenMoko distribution, the facility called [[MokoMakefile]] simplifies building OpenEmbedded.

=== Quick Start: OpenEmbedded Torrent ===

If you are a system developer and would like to get up-to-speed as quickly as possible, then download an [[OpenEmbedded Torrent]].

== From Scratch: OpenEmbedded ==

Beginner OpenMoko developers who would prefer to have full control over their OpenEmbedded build environment should follow the instructions below.

=== Preparations ===

Several prerequisite software components are necessary in order to have a fully functional OpenEmbedded build environment. However, setup and installation varies depending on the operating system installed on your workstation. The [http://wiki.openembedded.net/index.php OpenEmbedded Wiki] provides [http://wiki.openembedded.net/index.php/OEandYourDistro setup instructions] for FreeBSD, Mac OS X, and most major Linux distributions, of course.

For OpenEmbedded installation instructions please refer to [http://wiki.openembedded.net/index.php/OEandYourDistro OEandYourDistro].

=== ${OE_HOME} ===

Assuming that you have installed all prerequisite software, you are now ready to create a directory for all of your OpenEmbedded (OE) related work. We will refer to OE_HOME in a generic way, but for argument's sake, assume that it is equal to ${HOME}/oe. You should expect ${OE_HOME} to grow tremendously in size, up to approximately 8GB or larger in some cases. Also be aware, that a full OE build could require several hours of constant building, which may inhibit the performance of your computer while performing other tasks. Replace ${HOME}/oe with your preferred location.

For Bash users:
export OE_HOME=${HOME}/oe

For Tcsh users:
setenv OE_HOME ${HOME}/oe

Next, run 'mkdir -p ${OE_HOME}' to create the directory.

=== Synchronizing OpenEmbedded With Git ===

Just like any tree, OpenEmbedded has several branches. In this case they are called 'development branches'. Some noteworthy ones include org.openembedded.dev (the default) and org.openembedded.stable .

To syncronize the OpenEmbedded tree, run
<pre>
git clone git://git.openembedded.net/openembedded ${OE_HOME}/org.openembedded.dev
</pre>

Note that last argument could be any directory name (git will create the directory if it doesn't exist). Sticking to 'good convention', the directory name was chosen to reflect the default development branch, org.openembedded.dev . See the [http://wiki.openembedded.net/index.php/GitPhraseBook OE GitPhraseBook] for more info on checking out different branches.

To update the tree, run
<pre>
cd ${OE_HOME}/org.openembedded.dev
git pull
</pre>

For further information on Git, see [http://git-scm.com The Git Homepage].

Also, please explore the directory structure of the OpenEmbedded build tree. Take a few moments to inspect the different types of BitBake files (.bbclass, .bb, .inc, etc). This helps one to become familiar with recipe syntax and the inheritance system. Of particular note, please read the file 'local.conf.sample'.
<pre>
org.openembedded.dev
|-- classes
| |-- rootfs_ipk.bbclass
| `-- xorg-module.bbclass
|-- conf
| `-- local.conf.sample
| |-- distro
| | `-- angstrom-2008.1.conf
| |-- machine
| | |-- om-gta01.conf
| | `-- om-gta02.conf
`-- packages
|-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- images
|-- console-image.bb
|-- fso-console-image.bb
|-- fso-image.bb
|-- openmoko-image.bb
|-- opie-image.bb
`-- x11-image.bb
</pre>

=== local.conf ===

If you explored local.conf.example, then you would be aware that there are some very important variables to be set like MACHINE, DISTRO, and BBFILES, among many others. This is done in a configuration file (local.conf) inside the build directory.

'''Note:''' Using BitBake and OE for cross-compilation require that each target-distro combination is built in a separate directory, so that no version collisions occur. Concurrent builds may safely share the same DL_DIR though. This would suggest that a safe name for build directories is of the form ${OE_HOME}/build-${MACHINE}-${DISTRO}. Of course, if you don't plan on building for more than one machine-distro combination, then the naming of this directory is arbitrary. For the purpose of this example, we will use the convention ${OE_HOME}/build-${MACHINE} .

Now, create the 'local.conf' configuration file. Notice that the CACHE and TMPDIR variables are neatly kept within the build directory while the DL_DIR variable is outside of the build directory, so that concurrent builds may reuse the same source packages.
<pre>
OE_HOME ?= "${HOME}/oe"

MACHINE = "om-gta02"
DISTRO = "angstrom-2008.1"

DL_DIR = "${OE_HOME}/downloads"

BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"

BBMASK = ""

TMPDIR = "${OE_HOME}/build-${MACHINE}/tmp"
CACHE = "${TMPDIR}/cache"

IMAGE_FSTYPES = "jffs2 tar.gz"

ENABLE_BINARY_LOCALE_GENERATION = "0"
</pre>

The BBFILES variable is also of prime importance! It tells bitbake where to locate all available recipes for a build. The OpenEmbedded build environment is almost completely ready to go, with just one more minor step left.

=== Build Environment ===

For quick and easy initialization of the OpenEmbedded build environment, it is often suggested that the developer create a 'setup-env' script to source from the command line. This script can be called to initialize the most important of environment variables. Below is a very basic example of a setup-env script.

setup-env for Bash users:
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02
export BBPATH=${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
setup-env for Tcsh users:
<pre>
[[ -z ${OE_HOME} ]] && setenv OE_HOME ${HOME}/oe
[[ -z ${MACHINE} ]] && setenv MACHINE om-gta02
setenv BBPATH ${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
To invoke the setup-env script in bash, run 'source setup-env'. In tcsh, run '. setup-env'.

See the section entitled [http://wiki.openmoko.org/wiki/OpenEmbedded#BitBake_Overlays BitBake Overlays] for an example of a more complicated setup-env script.

=== Testing the OE Build Environment ===

That's it! Now you should be prepared to bake your first BitBake recipe.

bitbake helloworld

=== Building an Image ===

There are several full filesystem images which can be built directly with OpenEmbedded using a single command. These include openmoko-image, fso-image, and so on. The image definitions can be found under ${OE_HOME}/org.openembedded.dev/packages/images

A good place to start is with

bitbake fso-image

That concludes this introduction to BitBake and OpenEmbedded. Good luck!

=== Other References ===

Please feel free to refer to other online sources of information for [http://bitbake.berlios.de BitBake], [http://www.openembedded.org OpenEmbedded], and the [http://www.angstrom-distribution.org Angstrom Distribution] to name a few.

== Broken Builds and Bug Reporting ==

Using the org.openembedded.dev branch can often result in broken builds. For that reason, it is usually a good idea to limit synchronizing with the repository only after successfully building an image. Some may even want to archive the tree and build directory after an image is built.

Now in the case that an image does not successfully build, it is not always necessarily a bug or a new bug. The problem might have to do with some conflicting software on the workstation, and it could be a bug that is already know and being fixed.

Below are a few useful steps to follow when a build does not successfully complete:

* Identify the package that failed to build
** Find a line near the bottom of your output that matches "ERROR: ... failed" or "NOTE: ... failed". The name of the package should be contained in the '...'
* If there is a similar, more stable version in ${OE_HOME}/org.openembedded.dev/packages, then try to use that instead
** bitbake -c clean somepackage && bitbake -b ${OE_HOME}/org.openembedded.dev/packages/somepackage/somepackage_0.1.bb
** add PREFERRED_VERSION_somepackage = "0.1" to local.conf
* Read the BitBake log, as well as config.log if it exists
** Find the log file. There should be a line near the bottom of your output that matches "ERROR: see log in ...", where '...' contains the log file name. These are usually of the form log.do_compile.12345 or log.do_configure.12345, etc.
* Try to identify the root cause of the error
** In many cases, if one examines log.do_configure, only the error is reported, but not the cause of the error
** Most packages that build with autotools will also have a config.log file that contains the exact cause of the error
* If you can fix the error, and the error is local to your workstation, and not really a bug, then fix the error yourself.
* Otherwise, check the [http://bugs.openembedded.net OpenEmbedded Bugzilla] to see if the error is known.
* If a solution is already available, then try it out. If you can fix the error, then do so. If your solution is correct, please post all relevent patches to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

=== Where to Report Bugs ===

Authentic bugs should be reported to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

== Tips & Tricks ==

=== Setting the PREFERRED_VERSION for a package ===

If a certain package is known to not build, and there is a less recent / more stable version of that package, then a good way to avoid repetitive encounters with known build failures is to use preferred versions of packages.

For example, if building gcc-4.2.4 constantly failed, then it would be wise to edit local.conf and set PREFERRED_VERSION_gcc = "4.1.2".

=== Screen is Your Friend ===

If you happen to be building all of your packages remotely on a server, using an ssh session, the session might occasionally be interrupted and the connection could be terminated. A similar event could occur if your X server suddenly craches. If in the process of building an image with bitbake, this means that the build process will terminate as well.

In order to ensure that a build continues in the presence of communication failures, it is advisable to use the [http://www.gnu.org/software/screen GNU Screen] utility. Screen is also very useful when performing several concurrent OpenEmbedded builds for different machine-distro combinations.

Screen installation varies with your OS and distribution.

=== BitBake Overlays ===

Bitbake overlays are useful for OpenEmbedded developers to eliminate bugs or package software without disturbiing the OpenEmbedded tree itself. Overlays are very similar in structure to the OpenEmbedded tree, but are usually only sparsely populated. Non-sparsely poplulated overlays are actually more closely relatedd to separate development branches. Good convention would suggest to always name the overlay appropriately.

Below is an example of two overlays, three build directories, a setup-env script, and a local.conf where the developer has multiple build targets as well as multiple BitBake overlays.
<pre>
oe
|-- build-beagleboard
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-om-gta02
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-ts72xx
| |-- conf
| | `-- local.conf
| `-- tmp
|-- com.somecompany.dev
| |-- conf
| | `-- machine
| `-- packages
| |-- images
| | `-- console-image.bb
| `-- rxtx
| |-- files
| |-- rxtx-fixes-from-debian.patch
| `-- rxtx_2.1-7r2.bb
|-- org.openembedded.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- images
|-- org.openmoko.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- setup-env
</pre>
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02

unset BBPATH

case "${MACHINE}" in
"beagleboard" | "ts72xx" )
BBPATH="${OE_HOME}/com.somecompany.dev"
;;
"om-gta02")
BBPATH="${OE_HOME}/org.openmoko.dev"
;;
*)
echo -e "error: unsupported machine"
exit -1
;;
esac

export BBPATH=${BBPATH}:${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>

Note that the overlay-specific BBPATH entry ''precedes'' the default BBPATH entries.

<pre>
...
BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"
BBFILES += " ${OE_HOME}/org.openmoko.dev/packages/*/*.bb"

BBFILE_COLLECTIONS = "upstream local"
BBFILE_PATTERN_upstream = "${OE_HOME}/org.openembedded.dev"
BBFILE_PRIORITY_upstream = "0"
BBFILE_PATTERN_local = "${OE_HOME}/org.openmoko.dev"
BBFILE_PRIORITY_local = "1"
...
</pre>

In order for the overlay to be detected by BitBake, the above variables need to be defined. It is possible to have more than one overlay and each one should be given a different priority.

=== Useful BitBake Commands ===

<pre>
# list all of the tasks defined for a given package_name
bitbake -c listtasks <package_name>

# clean the work directory for a specific package
bitbake -c clean <package_name>

# build a specific recipe
bitbake -b <path/to/some/recipe.bb>
</pre>

[[Category:Application Developer]]
[[Category:System Developers]]

OpenEmbedded

2009-02-10T19:09:34Z

Cfriedt: /* Broken Builds and Bug Reporting */

{{Languages|OpenEmbedded}}

Openmoko, our distribution, is built using OpenEmbedded. OpenEmbedded will:

* Generate (cross-compile) software packages for multiple embedded targets.
* Handle different hardware architectures, and support multiple releases across those architectures.

For more information please see the [http://www.openembedded.org/ Open Embedded] website.

== Building the OpenMoko Distribution with OpenEmbedded ==

'''Note:''' If you are an application developer, you probably do not want to build OpenEmbedded from scratch. For compiling simple applications with few library dependencies (including boot-loader and kernel), consider using our prebuilt [[Toolchain]]. For more complex applications with many library dependencies, download a prebuilt [[OpenEmbedded Torrent]].

Building OpenMoko from scratch is a time-, cpu- and diskspace-consuming process which should only be done if you are a system integrator and want to customize your OpenMoko distribution.

=== Simplified Instructions: MokoMakefile ===

For beginners who wish to customize their OpenMoko distribution, the facility called [[MokoMakefile]] simplifies building OpenEmbedded.

=== Quick Start: OpenEmbedded Torrent ===

If you are a system developer and would like to get up-to-speed as quickly as possible, then download an [[OpenEmbedded Torrent]].

== From Scratch: OpenEmbedded ==

Beginner OpenMoko developers who would prefer to have full control over their OpenEmbedded build environment should follow the instructions below.

=== Preparations ===

Several prerequisite software components are necessary in order to have a fully functional OpenEmbedded build environment. However, setup and installation varies depending on the operating system installed on your workstation. The [http://wiki.openembedded.net/index.php OpenEmbedded Wiki] provides [http://wiki.openembedded.net/index.php/OEandYourDistro setup instructions] for FreeBSD, Mac OS X, and most major Linux distributions, of course.

For OpenEmbedded installation instructions please refer to [http://wiki.openembedded.net/index.php/OEandYourDistro OEandYourDistro].

=== ${OE_HOME} ===

Assuming that you have installed all prerequisite software, you are now ready to create a directory for all of your OpenEmbedded (OE) related work. We will refer to OE_HOME in a generic way, but for argument's sake, assume that it is equal to ${HOME}/oe. You should expect ${OE_HOME} to grow tremendously in size, up to approximately 8GB or larger in some cases. Also be aware, that a full OE build could require several hours of constant building, which may inhibit the performance of your computer while performing other tasks. Replace ${HOME}/oe with your preferred location.

For Bash users:
export OE_HOME=${HOME}/oe

For Tcsh users:
setenv OE_HOME ${HOME}/oe

Next, run 'mkdir -p ${OE_HOME}' to create the directory.

=== Synchronizing OpenEmbedded With Git ===

Just like any tree, OpenEmbedded has several branches. In this case they are called 'development branches'. Some noteworthy ones include org.openembedded.dev (the default) and org.openembedded.stable .

To syncronize the OpenEmbedded tree, run
<pre>
git clone git://git.openembedded.net/openembedded ${OE_HOME}/org.openembedded.dev
</pre>

Note that last argument could be any directory name (git will create the directory if it doesn't exist). Sticking to 'good convention', the directory name was chosen to reflect the default development branch, org.openembedded.dev . See the [http://wiki.openembedded.net/index.php/GitPhraseBook OE GitPhraseBook] for more info on checking out different branches.

To update the tree, run
<pre>
cd ${OE_HOME}/org.openembedded.dev
git pull
</pre>

For further information on Git, see [http://git-scm.com The Git Homepage].

Also, please explore the directory structure of the OpenEmbedded build tree. Take a few moments to inspect the different types of BitBake files (.bbclass, .bb, .inc, etc). This helps one to become familiar with recipe syntax and the inheritance system. Of particular note, please read the file 'local.conf.sample'.
<pre>
org.openembedded.dev
|-- classes
| |-- rootfs_ipk.bbclass
| `-- xorg-module.bbclass
|-- conf
| `-- local.conf.sample
| |-- distro
| | `-- angstrom-2008.1.conf
| |-- machine
| | |-- om-gta01.conf
| | `-- om-gta02.conf
`-- packages
|-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- images
|-- console-image.bb
|-- fso-console-image.bb
|-- fso-image.bb
|-- openmoko-image.bb
|-- opie-image.bb
`-- x11-image.bb
</pre>

=== Build Configuration ===

If you explored local.conf.example, then you would be aware that there are some very important variables to be set like MACHINE, DISTRO, and BBFILES, among many others. This is done in a configuration file (local.conf) inside the build directory.

'''Note:''' Using BitBake and OE for cross-compilation require that each target-distro combination is built in a separate directory, so that no version collisions occur. Concurrent builds may safely share the same DL_DIR though. This would suggest that a safe name for build directories is of the form ${OE_HOME}/build-${MACHINE}-${DISTRO}. Of course, if you don't plan on building for more than one machine-distro combination, then the naming of this directory is arbitrary. For the purpose of this example, we will use the convention ${OE_HOME}/build-${MACHINE} .

Now, create the 'local.conf' configuration file. Notice that the CACHE and TMPDIR variables are neatly kept within the build directory while the DL_DIR variable is outside of the build directory, so that concurrent builds may reuse the same source packages.
<pre>
OE_HOME ?= "${HOME}/oe"

MACHINE = "om-gta02"
DISTRO = "angstrom-2008.1"

DL_DIR = "${OE_HOME}/downloads"

BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"

BBMASK = ""

TMPDIR = "${OE_HOME}/build-${MACHINE}/tmp"
CACHE = "${TMPDIR}/cache"

IMAGE_FSTYPES = "jffs2 tar.gz"

ENABLE_BINARY_LOCALE_GENERATION = "0"
</pre>

The BBFILES variable is also of prime importance! It tells bitbake where to locate all available recipes for a build. The OpenEmbedded build environment is almost completely ready to go, with just one more minor step left.

=== Build Environment ===

For quick and easy initialization of the OpenEmbedded build environment, it is often suggested that the developer create a 'setup-env' script to source from the command line. This script can be called to initialize the most important of environment variables. Below is a very basic example of a setup-env script.

setup-env for Bash users:
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02
export BBPATH=${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
setup-env for Tcsh users:
<pre>
[[ -z ${OE_HOME} ]] && setenv OE_HOME ${HOME}/oe
[[ -z ${MACHINE} ]] && setenv MACHINE om-gta02
setenv BBPATH ${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
To invoke the setup-env script in bash, run 'source setup-env'. In tcsh, run '. setup-env'.

See the section entitled [http://wiki.openmoko.org/wiki/OpenEmbedded#BitBake_Overlays BitBake Overlays] for an example of a more complicated setup-env script.

=== Testing the OE Build Environment ===

That's it! Now you should be prepared to bake your first BitBake recipe.

bitbake helloworld

=== Building an Image ===

There are several full filesystem images which can be built directly with OpenEmbedded using a single command. These include openmoko-image, fso-image, and so on. The image definitions can be found under ${OE_HOME}/org.openembedded.dev/packages/images

A good place to start is with

bitbake fso-image

That concludes this introduction to BitBake and OpenEmbedded. Good luck!

=== Other References ===

Please feel free to refer to other online sources of information for [http://bitbake.berlios.de BitBake], [http://www.openembedded.org OpenEmbedded], and the [http://www.angstrom-distribution.org Angstrom Distribution] to name a few.

== Broken Builds and Bug Reporting ==

Using the org.openembedded.dev branch can often result in broken builds. For that reason, it is usually a good idea to limit synchronizing with the repository only after successfully building an image. Some may even want to archive the tree and build directory after an image is built.

Now in the case that an image does not successfully build, it is not always necessarily a bug or a new bug. The problem might have to do with some conflicting software on the workstation, and it could be a bug that is already know and being fixed.

Below are a few useful steps to follow when a build does not successfully complete:

* Identify the package that failed to build
** Find a line near the bottom of your output that matches "ERROR: ... failed" or "NOTE: ... failed". The name of the package should be contained in the '...'
* If there is a similar, more stable version in ${OE_HOME}/org.openembedded.dev/packages, then try to use that instead
** bitbake -c clean somepackage && bitbake -b ${OE_HOME}/org.openembedded.dev/packages/somepackage/somepackage_0.1.bb
** add PREFERRED_VERSION_somepackage = "0.1" to local.conf
* Read the BitBake log, as well as config.log if it exists
** Find the log file. There should be a line near the bottom of your output that matches "ERROR: see log in ...", where '...' contains the log file name. These are usually of the form log.do_compile.12345 or log.do_configure.12345, etc.
* Try to identify the root cause of the error
** In many cases, if one examines log.do_configure, only the error is reported, but not the cause of the error
** Most packages that build with autotools will also have a config.log file that contains the exact cause of the error
* If you can fix the error, and the error is local to your workstation, and not really a bug, then fix the error yourself.
* Otherwise, check the [http://bugs.openembedded.net OpenEmbedded Bugzilla] to see if the error is known.
* If a solution is already available, then try it out. If you can fix the error, then do so. If your solution is correct, please post all relevent patches to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

=== Where to Report Bugs ===

Authentic bugs should be reported to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

== Tips & Tricks ==

=== Setting the PREFERRED_VERSION for a package ===

If a certain package is known to not build, and there is a less recent / more stable version of that package, then a good way to avoid repetitive encounters with known build failures is to use preferred versions of packages.

For example, if building gcc-4.2.4 constantly failed, then it would be wise to edit local.conf and set PREFERRED_VERSION_gcc = "4.1.2".

=== Screen is Your Friend ===

If you happen to be building all of your packages remotely on a server, using an ssh session, the session might occasionally be interrupted and the connection could be terminated. A similar event could occur if your X server suddenly craches. If in the process of building an image with bitbake, this means that the build process will terminate as well.

In order to ensure that a build continues in the presence of communication failures, it is advisable to use the [http://www.gnu.org/software/screen GNU Screen] utility. Screen is also very useful when performing several concurrent OpenEmbedded builds for different machine-distro combinations.

Screen installation varies with your OS and distribution.

=== BitBake Overlays ===

Bitbake overlays are useful for OpenEmbedded developers to eliminate bugs or package software without disturbiing the OpenEmbedded tree itself. Overlays are very similar in structure to the OpenEmbedded tree, but are usually only sparsely populated. Non-sparsely poplulated overlays are actually more closely relatedd to separate development branches. Good convention would suggest to always name the overlay appropriately.

Below is an example of two overlays, three build directories, a setup-env script, and a local.conf where the developer has multiple build targets as well as multiple BitBake overlays.
<pre>
oe
|-- build-beagleboard
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-om-gta02
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-ts72xx
| |-- conf
| | `-- local.conf
| `-- tmp
|-- com.somecompany.dev
| |-- conf
| | `-- machine
| `-- packages
| |-- images
| | `-- console-image.bb
| `-- rxtx
| |-- files
| |-- rxtx-fixes-from-debian.patch
| `-- rxtx_2.1-7r2.bb
|-- org.openembedded.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- images
|-- org.openmoko.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- setup-env
</pre>
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02

unset BBPATH

case "${MACHINE}" in
"beagleboard" | "ts72xx" )
BBPATH="${OE_HOME}/com.somecompany.dev"
;;
"om-gta02")
BBPATH="${OE_HOME}/org.openmoko.dev"
;;
*)
echo -e "error: unsupported machine"
exit -1
;;
esac

export BBPATH=${BBPATH}:${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>

Note that the overlay-specific BBPATH entry ''precedes'' the default BBPATH entries.

<pre>
...
BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"
BBFILES += " ${OE_HOME}/org.openmoko.dev/packages/*/*.bb"

BBFILE_COLLECTIONS = "upstream local"
BBFILE_PATTERN_upstream = "${OE_HOME}/org.openembedded.dev"
BBFILE_PRIORITY_upstream = "0"
BBFILE_PATTERN_local = "${OE_HOME}/org.openmoko.dev"
BBFILE_PRIORITY_local = "1"
...
</pre>

In order for the overlay to be detected by BitBake, the above variables need to be defined. It is possible to have more than one overlay and each one should be given a different priority.

=== Useful BitBake Commands ===

<pre>
# list all of the tasks defined for a given package_name
bitbake -c listtasks <package_name>

# clean the work directory for a specific package
bitbake -c clean <package_name>

# build a specific recipe
bitbake -b <path/to/some/recipe.bb>
</pre>

[[Category:Application Developer]]
[[Category:System Developers]]

OpenEmbedded

2009-02-10T19:08:14Z

Cfriedt: /* Build Environment */

{{Languages|OpenEmbedded}}

Openmoko, our distribution, is built using OpenEmbedded. OpenEmbedded will:

* Generate (cross-compile) software packages for multiple embedded targets.
* Handle different hardware architectures, and support multiple releases across those architectures.

For more information please see the [http://www.openembedded.org/ Open Embedded] website.

== Building the OpenMoko Distribution with OpenEmbedded ==

'''Note:''' If you are an application developer, you probably do not want to build OpenEmbedded from scratch. For compiling simple applications with few library dependencies (including boot-loader and kernel), consider using our prebuilt [[Toolchain]]. For more complex applications with many library dependencies, download a prebuilt [[OpenEmbedded Torrent]].

Building OpenMoko from scratch is a time-, cpu- and diskspace-consuming process which should only be done if you are a system integrator and want to customize your OpenMoko distribution.

=== Simplified Instructions: MokoMakefile ===

For beginners who wish to customize their OpenMoko distribution, the facility called [[MokoMakefile]] simplifies building OpenEmbedded.

=== Quick Start: OpenEmbedded Torrent ===

If you are a system developer and would like to get up-to-speed as quickly as possible, then download an [[OpenEmbedded Torrent]].

== From Scratch: OpenEmbedded ==

Beginner OpenMoko developers who would prefer to have full control over their OpenEmbedded build environment should follow the instructions below.

=== Preparations ===

Several prerequisite software components are necessary in order to have a fully functional OpenEmbedded build environment. However, setup and installation varies depending on the operating system installed on your workstation. The [http://wiki.openembedded.net/index.php OpenEmbedded Wiki] provides [http://wiki.openembedded.net/index.php/OEandYourDistro setup instructions] for FreeBSD, Mac OS X, and most major Linux distributions, of course.

For OpenEmbedded installation instructions please refer to [http://wiki.openembedded.net/index.php/OEandYourDistro OEandYourDistro].

=== ${OE_HOME} ===

Assuming that you have installed all prerequisite software, you are now ready to create a directory for all of your OpenEmbedded (OE) related work. We will refer to OE_HOME in a generic way, but for argument's sake, assume that it is equal to ${HOME}/oe. You should expect ${OE_HOME} to grow tremendously in size, up to approximately 8GB or larger in some cases. Also be aware, that a full OE build could require several hours of constant building, which may inhibit the performance of your computer while performing other tasks. Replace ${HOME}/oe with your preferred location.

For Bash users:
export OE_HOME=${HOME}/oe

For Tcsh users:
setenv OE_HOME ${HOME}/oe

Next, run 'mkdir -p ${OE_HOME}' to create the directory.

=== Synchronizing OpenEmbedded With Git ===

Just like any tree, OpenEmbedded has several branches. In this case they are called 'development branches'. Some noteworthy ones include org.openembedded.dev (the default) and org.openembedded.stable .

To syncronize the OpenEmbedded tree, run
<pre>
git clone git://git.openembedded.net/openembedded ${OE_HOME}/org.openembedded.dev
</pre>

Note that last argument could be any directory name (git will create the directory if it doesn't exist). Sticking to 'good convention', the directory name was chosen to reflect the default development branch, org.openembedded.dev . See the [http://wiki.openembedded.net/index.php/GitPhraseBook OE GitPhraseBook] for more info on checking out different branches.

To update the tree, run
<pre>
cd ${OE_HOME}/org.openembedded.dev
git pull
</pre>

For further information on Git, see [http://git-scm.com The Git Homepage].

Also, please explore the directory structure of the OpenEmbedded build tree. Take a few moments to inspect the different types of BitBake files (.bbclass, .bb, .inc, etc). This helps one to become familiar with recipe syntax and the inheritance system. Of particular note, please read the file 'local.conf.sample'.
<pre>
org.openembedded.dev
|-- classes
| |-- rootfs_ipk.bbclass
| `-- xorg-module.bbclass
|-- conf
| `-- local.conf.sample
| |-- distro
| | `-- angstrom-2008.1.conf
| |-- machine
| | |-- om-gta01.conf
| | `-- om-gta02.conf
`-- packages
|-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- images
|-- console-image.bb
|-- fso-console-image.bb
|-- fso-image.bb
|-- openmoko-image.bb
|-- opie-image.bb
`-- x11-image.bb
</pre>

=== Build Configuration ===

If you explored local.conf.example, then you would be aware that there are some very important variables to be set like MACHINE, DISTRO, and BBFILES, among many others. This is done in a configuration file (local.conf) inside the build directory.

'''Note:''' Using BitBake and OE for cross-compilation require that each target-distro combination is built in a separate directory, so that no version collisions occur. Concurrent builds may safely share the same DL_DIR though. This would suggest that a safe name for build directories is of the form ${OE_HOME}/build-${MACHINE}-${DISTRO}. Of course, if you don't plan on building for more than one machine-distro combination, then the naming of this directory is arbitrary. For the purpose of this example, we will use the convention ${OE_HOME}/build-${MACHINE} .

Now, create the 'local.conf' configuration file. Notice that the CACHE and TMPDIR variables are neatly kept within the build directory while the DL_DIR variable is outside of the build directory, so that concurrent builds may reuse the same source packages.
<pre>
OE_HOME ?= "${HOME}/oe"

MACHINE = "om-gta02"
DISTRO = "angstrom-2008.1"

DL_DIR = "${OE_HOME}/downloads"

BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"

BBMASK = ""

TMPDIR = "${OE_HOME}/build-${MACHINE}/tmp"
CACHE = "${TMPDIR}/cache"

IMAGE_FSTYPES = "jffs2 tar.gz"

ENABLE_BINARY_LOCALE_GENERATION = "0"
</pre>

The BBFILES variable is also of prime importance! It tells bitbake where to locate all available recipes for a build. The OpenEmbedded build environment is almost completely ready to go, with just one more minor step left.

=== Build Environment ===

For quick and easy initialization of the OpenEmbedded build environment, it is often suggested that the developer create a 'setup-env' script to source from the command line. This script can be called to initialize the most important of environment variables. Below is a very basic example of a setup-env script.

setup-env for Bash users:
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02
export BBPATH=${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
setup-env for Tcsh users:
<pre>
[[ -z ${OE_HOME} ]] && setenv OE_HOME ${HOME}/oe
[[ -z ${MACHINE} ]] && setenv MACHINE om-gta02
setenv BBPATH ${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
To invoke the setup-env script in bash, run 'source setup-env'. In tcsh, run '. setup-env'.

See the section entitled [http://wiki.openmoko.org/wiki/OpenEmbedded#BitBake_Overlays BitBake Overlays] for an example of a more complicated setup-env script.

=== Testing the OE Build Environment ===

That's it! Now you should be prepared to bake your first BitBake recipe.

bitbake helloworld

=== Building an Image ===

There are several full filesystem images which can be built directly with OpenEmbedded using a single command. These include openmoko-image, fso-image, and so on. The image definitions can be found under ${OE_HOME}/org.openembedded.dev/packages/images

A good place to start is with

bitbake fso-image

That concludes this introduction to BitBake and OpenEmbedded. Good luck!

=== Other References ===

Please feel free to refer to other online sources of information for [http://bitbake.berlios.de BitBake], [http://www.openembedded.org OpenEmbedded], and the [http://www.angstrom-distribution.org Angstrom Distribution] to name a few.

== Broken Builds and Bug Reporting ==

Using the org.openembedded.dev branch can often result in broken builds. For that reason, it is usually a good idea to limit synchronizing with the repository only after successfully building an image. Some may even want to archive the tree and build directory after an image is built.

Now in the case that an image does not successfully build, it is not always necessarily a bug or a new bug. The problem might have to do with some conflicting software on the workstation, and it could be a bug that is already know and being fixed.

Below are a few useful steps to follow when a build does not successfully complete:

* Identify the package that failed to build
** Find a line near the bottom of your output that matches "ERROR: ... failed" or "NOTE: ... failed". The name of the package should be contained in the '...'
* If there is a similar, more stable version in ${OE_HOME}/org.openembedded.dev/packages, then try to use that instead
** bitbake -c clean package_name && bitbake -b ${OE_HOME}/org.openembedded.dev/packages/somepackage/somepackage_0.1.bb
** add PREFERRED_VERSION_somepackage = "0.1" to local.conf
* Read the BitBake log, as well as config.log if it exists
** Find the log file. There should be a line near the bottom of your output that matches "ERROR: see log in ...", where '...' contains the log file name. These are usually of the form log.do_compile.12345 or log.do_configure.12345, etc.
* Try to identify the root cause of the error
** In many cases, if one examines log.do_configure, only the error is reported, but not the cause of the error
** Most packages that build with autotools will also have a config.log file that contains the exact cause of the error
* If you can fix the error, and the error is local to your workstation, and not really a bug, then fix the error yourself.
* Otherwise, check the [http://bugs.openembedded.net OpenEmbedded Bugzilla] to see if the error is known.
* If a solution is already available, then try it out. If you can fix the error, then do so. If your solution is correct, please post all relevent patches to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

=== Where to Report Bugs ===

Authentic bugs should be reported to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

== Tips & Tricks ==

=== Setting the PREFERRED_VERSION for a package ===

If a certain package is known to not build, and there is a less recent / more stable version of that package, then a good way to avoid repetitive encounters with known build failures is to use preferred versions of packages.

For example, if building gcc-4.2.4 constantly failed, then it would be wise to edit local.conf and set PREFERRED_VERSION_gcc = "4.1.2".

=== Screen is Your Friend ===

If you happen to be building all of your packages remotely on a server, using an ssh session, the session might occasionally be interrupted and the connection could be terminated. A similar event could occur if your X server suddenly craches. If in the process of building an image with bitbake, this means that the build process will terminate as well.

In order to ensure that a build continues in the presence of communication failures, it is advisable to use the [http://www.gnu.org/software/screen GNU Screen] utility. Screen is also very useful when performing several concurrent OpenEmbedded builds for different machine-distro combinations.

Screen installation varies with your OS and distribution.

=== BitBake Overlays ===

Bitbake overlays are useful for OpenEmbedded developers to eliminate bugs or package software without disturbiing the OpenEmbedded tree itself. Overlays are very similar in structure to the OpenEmbedded tree, but are usually only sparsely populated. Non-sparsely poplulated overlays are actually more closely relatedd to separate development branches. Good convention would suggest to always name the overlay appropriately.

Below is an example of two overlays, three build directories, a setup-env script, and a local.conf where the developer has multiple build targets as well as multiple BitBake overlays.
<pre>
oe
|-- build-beagleboard
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-om-gta02
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-ts72xx
| |-- conf
| | `-- local.conf
| `-- tmp
|-- com.somecompany.dev
| |-- conf
| | `-- machine
| `-- packages
| |-- images
| | `-- console-image.bb
| `-- rxtx
| |-- files
| |-- rxtx-fixes-from-debian.patch
| `-- rxtx_2.1-7r2.bb
|-- org.openembedded.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- images
|-- org.openmoko.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- setup-env
</pre>
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02

unset BBPATH

case "${MACHINE}" in
"beagleboard" | "ts72xx" )
BBPATH="${OE_HOME}/com.somecompany.dev"
;;
"om-gta02")
BBPATH="${OE_HOME}/org.openmoko.dev"
;;
*)
echo -e "error: unsupported machine"
exit -1
;;
esac

export BBPATH=${BBPATH}:${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>

Note that the overlay-specific BBPATH entry ''precedes'' the default BBPATH entries.

<pre>
...
BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"
BBFILES += " ${OE_HOME}/org.openmoko.dev/packages/*/*.bb"

BBFILE_COLLECTIONS = "upstream local"
BBFILE_PATTERN_upstream = "${OE_HOME}/org.openembedded.dev"
BBFILE_PRIORITY_upstream = "0"
BBFILE_PATTERN_local = "${OE_HOME}/org.openmoko.dev"
BBFILE_PRIORITY_local = "1"
...
</pre>

In order for the overlay to be detected by BitBake, the above variables need to be defined. It is possible to have more than one overlay and each one should be given a different priority.

=== Useful BitBake Commands ===

<pre>
# list all of the tasks defined for a given package_name
bitbake -c listtasks <package_name>

# clean the work directory for a specific package
bitbake -c clean <package_name>

# build a specific recipe
bitbake -b <path/to/some/recipe.bb>
</pre>

[[Category:Application Developer]]
[[Category:System Developers]]

OpenEmbedded

2009-02-10T19:07:27Z

Cfriedt: /* Build Environment */

{{Languages|OpenEmbedded}}

Openmoko, our distribution, is built using OpenEmbedded. OpenEmbedded will:

* Generate (cross-compile) software packages for multiple embedded targets.
* Handle different hardware architectures, and support multiple releases across those architectures.

For more information please see the [http://www.openembedded.org/ Open Embedded] website.

== Building the OpenMoko Distribution with OpenEmbedded ==

'''Note:''' If you are an application developer, you probably do not want to build OpenEmbedded from scratch. For compiling simple applications with few library dependencies (including boot-loader and kernel), consider using our prebuilt [[Toolchain]]. For more complex applications with many library dependencies, download a prebuilt [[OpenEmbedded Torrent]].

Building OpenMoko from scratch is a time-, cpu- and diskspace-consuming process which should only be done if you are a system integrator and want to customize your OpenMoko distribution.

=== Simplified Instructions: MokoMakefile ===

For beginners who wish to customize their OpenMoko distribution, the facility called [[MokoMakefile]] simplifies building OpenEmbedded.

=== Quick Start: OpenEmbedded Torrent ===

If you are a system developer and would like to get up-to-speed as quickly as possible, then download an [[OpenEmbedded Torrent]].

== From Scratch: OpenEmbedded ==

Beginner OpenMoko developers who would prefer to have full control over their OpenEmbedded build environment should follow the instructions below.

=== Preparations ===

Several prerequisite software components are necessary in order to have a fully functional OpenEmbedded build environment. However, setup and installation varies depending on the operating system installed on your workstation. The [http://wiki.openembedded.net/index.php OpenEmbedded Wiki] provides [http://wiki.openembedded.net/index.php/OEandYourDistro setup instructions] for FreeBSD, Mac OS X, and most major Linux distributions, of course.

For OpenEmbedded installation instructions please refer to [http://wiki.openembedded.net/index.php/OEandYourDistro OEandYourDistro].

=== ${OE_HOME} ===

Assuming that you have installed all prerequisite software, you are now ready to create a directory for all of your OpenEmbedded (OE) related work. We will refer to OE_HOME in a generic way, but for argument's sake, assume that it is equal to ${HOME}/oe. You should expect ${OE_HOME} to grow tremendously in size, up to approximately 8GB or larger in some cases. Also be aware, that a full OE build could require several hours of constant building, which may inhibit the performance of your computer while performing other tasks. Replace ${HOME}/oe with your preferred location.

For Bash users:
export OE_HOME=${HOME}/oe

For Tcsh users:
setenv OE_HOME ${HOME}/oe

Next, run 'mkdir -p ${OE_HOME}' to create the directory.

=== Synchronizing OpenEmbedded With Git ===

Just like any tree, OpenEmbedded has several branches. In this case they are called 'development branches'. Some noteworthy ones include org.openembedded.dev (the default) and org.openembedded.stable .

To syncronize the OpenEmbedded tree, run
<pre>
git clone git://git.openembedded.net/openembedded ${OE_HOME}/org.openembedded.dev
</pre>

Note that last argument could be any directory name (git will create the directory if it doesn't exist). Sticking to 'good convention', the directory name was chosen to reflect the default development branch, org.openembedded.dev . See the [http://wiki.openembedded.net/index.php/GitPhraseBook OE GitPhraseBook] for more info on checking out different branches.

To update the tree, run
<pre>
cd ${OE_HOME}/org.openembedded.dev
git pull
</pre>

For further information on Git, see [http://git-scm.com The Git Homepage].

Also, please explore the directory structure of the OpenEmbedded build tree. Take a few moments to inspect the different types of BitBake files (.bbclass, .bb, .inc, etc). This helps one to become familiar with recipe syntax and the inheritance system. Of particular note, please read the file 'local.conf.sample'.
<pre>
org.openembedded.dev
|-- classes
| |-- rootfs_ipk.bbclass
| `-- xorg-module.bbclass
|-- conf
| `-- local.conf.sample
| |-- distro
| | `-- angstrom-2008.1.conf
| |-- machine
| | |-- om-gta01.conf
| | `-- om-gta02.conf
`-- packages
|-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- images
|-- console-image.bb
|-- fso-console-image.bb
|-- fso-image.bb
|-- openmoko-image.bb
|-- opie-image.bb
`-- x11-image.bb
</pre>

=== Build Configuration ===

If you explored local.conf.example, then you would be aware that there are some very important variables to be set like MACHINE, DISTRO, and BBFILES, among many others. This is done in a configuration file (local.conf) inside the build directory.

'''Note:''' Using BitBake and OE for cross-compilation require that each target-distro combination is built in a separate directory, so that no version collisions occur. Concurrent builds may safely share the same DL_DIR though. This would suggest that a safe name for build directories is of the form ${OE_HOME}/build-${MACHINE}-${DISTRO}. Of course, if you don't plan on building for more than one machine-distro combination, then the naming of this directory is arbitrary. For the purpose of this example, we will use the convention ${OE_HOME}/build-${MACHINE} .

Now, create the 'local.conf' configuration file. Notice that the CACHE and TMPDIR variables are neatly kept within the build directory while the DL_DIR variable is outside of the build directory, so that concurrent builds may reuse the same source packages.
<pre>
OE_HOME ?= "${HOME}/oe"

MACHINE = "om-gta02"
DISTRO = "angstrom-2008.1"

DL_DIR = "${OE_HOME}/downloads"

BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"

BBMASK = ""

TMPDIR = "${OE_HOME}/build-${MACHINE}/tmp"
CACHE = "${TMPDIR}/cache"

IMAGE_FSTYPES = "jffs2 tar.gz"

ENABLE_BINARY_LOCALE_GENERATION = "0"
</pre>

The BBFILES variable is also of prime importance! It tells bitbake where to locate all available recipes for a build. The OpenEmbedded build environment is almost completely ready to go, with just one more minor step left.

=== Build Environment ===

For quick and easy initialization of the OpenEmbedded build environment, it is often suggested that the developer create a 'setup-env' script to source from the command line. This script can be called to initialize the most important of environment variables. Below is a very basic example of a setup-env script.

setup-env for Bash users:
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02
export BBPATH=${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
setup-env for Tcsh users:
<pre>
[[ -z ${OE_HOME} ]] && setenv OE_HOME ${HOME}/oe
[[ -z ${MACHINE} ]] && setenv MACHINE om-gta02
setenv BBPATH ${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
To invoke the setup-env script in bash, run 'source setup-env'. In tcsh, run '. setup-env'.

See the section entitled [http://wiki.openmoko.org/wiki/OpenEmbedded#BitBake_Overlays] for an example of a more complicated setup-env script.

=== Testing the OE Build Environment ===

That's it! Now you should be prepared to bake your first BitBake recipe.

bitbake helloworld

=== Building an Image ===

There are several full filesystem images which can be built directly with OpenEmbedded using a single command. These include openmoko-image, fso-image, and so on. The image definitions can be found under ${OE_HOME}/org.openembedded.dev/packages/images

A good place to start is with

bitbake fso-image

That concludes this introduction to BitBake and OpenEmbedded. Good luck!

=== Other References ===

Please feel free to refer to other online sources of information for [http://bitbake.berlios.de BitBake], [http://www.openembedded.org OpenEmbedded], and the [http://www.angstrom-distribution.org Angstrom Distribution] to name a few.

== Broken Builds and Bug Reporting ==

Using the org.openembedded.dev branch can often result in broken builds. For that reason, it is usually a good idea to limit synchronizing with the repository only after successfully building an image. Some may even want to archive the tree and build directory after an image is built.

Now in the case that an image does not successfully build, it is not always necessarily a bug or a new bug. The problem might have to do with some conflicting software on the workstation, and it could be a bug that is already know and being fixed.

Below are a few useful steps to follow when a build does not successfully complete:

* Identify the package that failed to build
** Find a line near the bottom of your output that matches "ERROR: ... failed" or "NOTE: ... failed". The name of the package should be contained in the '...'
* If there is a similar, more stable version in ${OE_HOME}/org.openembedded.dev/packages, then try to use that instead
** bitbake -c clean package_name && bitbake -b ${OE_HOME}/org.openembedded.dev/packages/somepackage/somepackage_0.1.bb
** add PREFERRED_VERSION_somepackage = "0.1" to local.conf
* Read the BitBake log, as well as config.log if it exists
** Find the log file. There should be a line near the bottom of your output that matches "ERROR: see log in ...", where '...' contains the log file name. These are usually of the form log.do_compile.12345 or log.do_configure.12345, etc.
* Try to identify the root cause of the error
** In many cases, if one examines log.do_configure, only the error is reported, but not the cause of the error
** Most packages that build with autotools will also have a config.log file that contains the exact cause of the error
* If you can fix the error, and the error is local to your workstation, and not really a bug, then fix the error yourself.
* Otherwise, check the [http://bugs.openembedded.net OpenEmbedded Bugzilla] to see if the error is known.
* If a solution is already available, then try it out. If you can fix the error, then do so. If your solution is correct, please post all relevent patches to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

=== Where to Report Bugs ===

Authentic bugs should be reported to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

== Tips & Tricks ==

=== Setting the PREFERRED_VERSION for a package ===

If a certain package is known to not build, and there is a less recent / more stable version of that package, then a good way to avoid repetitive encounters with known build failures is to use preferred versions of packages.

For example, if building gcc-4.2.4 constantly failed, then it would be wise to edit local.conf and set PREFERRED_VERSION_gcc = "4.1.2".

=== Screen is Your Friend ===

If you happen to be building all of your packages remotely on a server, using an ssh session, the session might occasionally be interrupted and the connection could be terminated. A similar event could occur if your X server suddenly craches. If in the process of building an image with bitbake, this means that the build process will terminate as well.

In order to ensure that a build continues in the presence of communication failures, it is advisable to use the [http://www.gnu.org/software/screen GNU Screen] utility. Screen is also very useful when performing several concurrent OpenEmbedded builds for different machine-distro combinations.

Screen installation varies with your OS and distribution.

=== BitBake Overlays ===

Bitbake overlays are useful for OpenEmbedded developers to eliminate bugs or package software without disturbiing the OpenEmbedded tree itself. Overlays are very similar in structure to the OpenEmbedded tree, but are usually only sparsely populated. Non-sparsely poplulated overlays are actually more closely relatedd to separate development branches. Good convention would suggest to always name the overlay appropriately.

Below is an example of two overlays, three build directories, a setup-env script, and a local.conf where the developer has multiple build targets as well as multiple BitBake overlays.
<pre>
oe
|-- build-beagleboard
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-om-gta02
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-ts72xx
| |-- conf
| | `-- local.conf
| `-- tmp
|-- com.somecompany.dev
| |-- conf
| | `-- machine
| `-- packages
| |-- images
| | `-- console-image.bb
| `-- rxtx
| |-- files
| |-- rxtx-fixes-from-debian.patch
| `-- rxtx_2.1-7r2.bb
|-- org.openembedded.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- images
|-- org.openmoko.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- setup-env
</pre>
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02

unset BBPATH

case "${MACHINE}" in
"beagleboard" | "ts72xx" )
BBPATH="${OE_HOME}/com.somecompany.dev"
;;
"om-gta02")
BBPATH="${OE_HOME}/org.openmoko.dev"
;;
*)
echo -e "error: unsupported machine"
exit -1
;;
esac

export BBPATH=${BBPATH}:${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>

Note that the overlay-specific BBPATH entry ''precedes'' the default BBPATH entries.

<pre>
...
BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"
BBFILES += " ${OE_HOME}/org.openmoko.dev/packages/*/*.bb"

BBFILE_COLLECTIONS = "upstream local"
BBFILE_PATTERN_upstream = "${OE_HOME}/org.openembedded.dev"
BBFILE_PRIORITY_upstream = "0"
BBFILE_PATTERN_local = "${OE_HOME}/org.openmoko.dev"
BBFILE_PRIORITY_local = "1"
...
</pre>

In order for the overlay to be detected by BitBake, the above variables need to be defined. It is possible to have more than one overlay and each one should be given a different priority.

=== Useful BitBake Commands ===

<pre>
# list all of the tasks defined for a given package_name
bitbake -c listtasks <package_name>

# clean the work directory for a specific package
bitbake -c clean <package_name>

# build a specific recipe
bitbake -b <path/to/some/recipe.bb>
</pre>

[[Category:Application Developer]]
[[Category:System Developers]]

OpenEmbedded

2009-02-10T19:05:19Z

Cfriedt: /* Synchronizing OpenEmbedded With Git */

{{Languages|OpenEmbedded}}

Openmoko, our distribution, is built using OpenEmbedded. OpenEmbedded will:

* Generate (cross-compile) software packages for multiple embedded targets.
* Handle different hardware architectures, and support multiple releases across those architectures.

For more information please see the [http://www.openembedded.org/ Open Embedded] website.

== Building the OpenMoko Distribution with OpenEmbedded ==

'''Note:''' If you are an application developer, you probably do not want to build OpenEmbedded from scratch. For compiling simple applications with few library dependencies (including boot-loader and kernel), consider using our prebuilt [[Toolchain]]. For more complex applications with many library dependencies, download a prebuilt [[OpenEmbedded Torrent]].

Building OpenMoko from scratch is a time-, cpu- and diskspace-consuming process which should only be done if you are a system integrator and want to customize your OpenMoko distribution.

=== Simplified Instructions: MokoMakefile ===

For beginners who wish to customize their OpenMoko distribution, the facility called [[MokoMakefile]] simplifies building OpenEmbedded.

=== Quick Start: OpenEmbedded Torrent ===

If you are a system developer and would like to get up-to-speed as quickly as possible, then download an [[OpenEmbedded Torrent]].

== From Scratch: OpenEmbedded ==

Beginner OpenMoko developers who would prefer to have full control over their OpenEmbedded build environment should follow the instructions below.

=== Preparations ===

Several prerequisite software components are necessary in order to have a fully functional OpenEmbedded build environment. However, setup and installation varies depending on the operating system installed on your workstation. The [http://wiki.openembedded.net/index.php OpenEmbedded Wiki] provides [http://wiki.openembedded.net/index.php/OEandYourDistro setup instructions] for FreeBSD, Mac OS X, and most major Linux distributions, of course.

For OpenEmbedded installation instructions please refer to [http://wiki.openembedded.net/index.php/OEandYourDistro OEandYourDistro].

=== ${OE_HOME} ===

Assuming that you have installed all prerequisite software, you are now ready to create a directory for all of your OpenEmbedded (OE) related work. We will refer to OE_HOME in a generic way, but for argument's sake, assume that it is equal to ${HOME}/oe. You should expect ${OE_HOME} to grow tremendously in size, up to approximately 8GB or larger in some cases. Also be aware, that a full OE build could require several hours of constant building, which may inhibit the performance of your computer while performing other tasks. Replace ${HOME}/oe with your preferred location.

For Bash users:
export OE_HOME=${HOME}/oe

For Tcsh users:
setenv OE_HOME ${HOME}/oe

Next, run 'mkdir -p ${OE_HOME}' to create the directory.

=== Synchronizing OpenEmbedded With Git ===

Just like any tree, OpenEmbedded has several branches. In this case they are called 'development branches'. Some noteworthy ones include org.openembedded.dev (the default) and org.openembedded.stable .

To syncronize the OpenEmbedded tree, run
<pre>
git clone git://git.openembedded.net/openembedded ${OE_HOME}/org.openembedded.dev
</pre>

Note that last argument could be any directory name (git will create the directory if it doesn't exist). Sticking to 'good convention', the directory name was chosen to reflect the default development branch, org.openembedded.dev . See the [http://wiki.openembedded.net/index.php/GitPhraseBook OE GitPhraseBook] for more info on checking out different branches.

To update the tree, run
<pre>
cd ${OE_HOME}/org.openembedded.dev
git pull
</pre>

For further information on Git, see [http://git-scm.com The Git Homepage].

Also, please explore the directory structure of the OpenEmbedded build tree. Take a few moments to inspect the different types of BitBake files (.bbclass, .bb, .inc, etc). This helps one to become familiar with recipe syntax and the inheritance system. Of particular note, please read the file 'local.conf.sample'.
<pre>
org.openembedded.dev
|-- classes
| |-- rootfs_ipk.bbclass
| `-- xorg-module.bbclass
|-- conf
| `-- local.conf.sample
| |-- distro
| | `-- angstrom-2008.1.conf
| |-- machine
| | |-- om-gta01.conf
| | `-- om-gta02.conf
`-- packages
|-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- images
|-- console-image.bb
|-- fso-console-image.bb
|-- fso-image.bb
|-- openmoko-image.bb
|-- opie-image.bb
`-- x11-image.bb
</pre>

=== Build Configuration ===

If you explored local.conf.example, then you would be aware that there are some very important variables to be set like MACHINE, DISTRO, and BBFILES, among many others. This is done in a configuration file (local.conf) inside the build directory.

'''Note:''' Using BitBake and OE for cross-compilation require that each target-distro combination is built in a separate directory, so that no version collisions occur. Concurrent builds may safely share the same DL_DIR though. This would suggest that a safe name for build directories is of the form ${OE_HOME}/build-${MACHINE}-${DISTRO}. Of course, if you don't plan on building for more than one machine-distro combination, then the naming of this directory is arbitrary. For the purpose of this example, we will use the convention ${OE_HOME}/build-${MACHINE} .

Now, create the 'local.conf' configuration file. Notice that the CACHE and TMPDIR variables are neatly kept within the build directory while the DL_DIR variable is outside of the build directory, so that concurrent builds may reuse the same source packages.
<pre>
OE_HOME ?= "${HOME}/oe"

MACHINE = "om-gta02"
DISTRO = "angstrom-2008.1"

DL_DIR = "${OE_HOME}/downloads"

BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"

BBMASK = ""

TMPDIR = "${OE_HOME}/build-${MACHINE}/tmp"
CACHE = "${TMPDIR}/cache"

IMAGE_FSTYPES = "jffs2 tar.gz"

ENABLE_BINARY_LOCALE_GENERATION = "0"
</pre>

The BBFILES variable is also of prime importance! It tells bitbake where to locate all available recipes for a build. The OpenEmbedded build environment is almost completely ready to go, with just one more minor step left.

=== Build Environment ===

For quick and easy initialization of the OpenEmbedded build environment, it is often suggested that the developer create a 'setup-env' script to source from the command line. This script can be called to initialize the most important of environment variables. Below is a very basic example of a setup-env script.

setup-env for Bash users:
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02
export BBPATH=${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
setup-env for Tcsh users:
<pre>
[[ -z ${OE_HOME} ]] && setenv OE_HOME ${HOME}/oe
[[ -z ${MACHINE} ]] && setenv MACHINE om-gta02
setenv BBPATH ${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
To invoke the setup-env script in bash, run 'source setup-env'. In tcsh, run '. setup-env'.

=== Testing the OE Build Environment ===

That's it! Now you should be prepared to bake your first BitBake recipe.

bitbake helloworld

=== Building an Image ===

There are several full filesystem images which can be built directly with OpenEmbedded using a single command. These include openmoko-image, fso-image, and so on. The image definitions can be found under ${OE_HOME}/org.openembedded.dev/packages/images

A good place to start is with

bitbake fso-image

That concludes this introduction to BitBake and OpenEmbedded. Good luck!

=== Other References ===

Please feel free to refer to other online sources of information for [http://bitbake.berlios.de BitBake], [http://www.openembedded.org OpenEmbedded], and the [http://www.angstrom-distribution.org Angstrom Distribution] to name a few.

== Broken Builds and Bug Reporting ==

Using the org.openembedded.dev branch can often result in broken builds. For that reason, it is usually a good idea to limit synchronizing with the repository only after successfully building an image. Some may even want to archive the tree and build directory after an image is built.

Now in the case that an image does not successfully build, it is not always necessarily a bug or a new bug. The problem might have to do with some conflicting software on the workstation, and it could be a bug that is already know and being fixed.

Below are a few useful steps to follow when a build does not successfully complete:

* Identify the package that failed to build
** Find a line near the bottom of your output that matches "ERROR: ... failed" or "NOTE: ... failed". The name of the package should be contained in the '...'
* If there is a similar, more stable version in ${OE_HOME}/org.openembedded.dev/packages, then try to use that instead
** bitbake -c clean package_name && bitbake -b ${OE_HOME}/org.openembedded.dev/packages/somepackage/somepackage_0.1.bb
** add PREFERRED_VERSION_somepackage = "0.1" to local.conf
* Read the BitBake log, as well as config.log if it exists
** Find the log file. There should be a line near the bottom of your output that matches "ERROR: see log in ...", where '...' contains the log file name. These are usually of the form log.do_compile.12345 or log.do_configure.12345, etc.
* Try to identify the root cause of the error
** In many cases, if one examines log.do_configure, only the error is reported, but not the cause of the error
** Most packages that build with autotools will also have a config.log file that contains the exact cause of the error
* If you can fix the error, and the error is local to your workstation, and not really a bug, then fix the error yourself.
* Otherwise, check the [http://bugs.openembedded.net OpenEmbedded Bugzilla] to see if the error is known.
* If a solution is already available, then try it out. If you can fix the error, then do so. If your solution is correct, please post all relevent patches to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

=== Where to Report Bugs ===

Authentic bugs should be reported to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

== Tips & Tricks ==

=== Setting the PREFERRED_VERSION for a package ===

If a certain package is known to not build, and there is a less recent / more stable version of that package, then a good way to avoid repetitive encounters with known build failures is to use preferred versions of packages.

For example, if building gcc-4.2.4 constantly failed, then it would be wise to edit local.conf and set PREFERRED_VERSION_gcc = "4.1.2".

=== Screen is Your Friend ===

If you happen to be building all of your packages remotely on a server, using an ssh session, the session might occasionally be interrupted and the connection could be terminated. A similar event could occur if your X server suddenly craches. If in the process of building an image with bitbake, this means that the build process will terminate as well.

In order to ensure that a build continues in the presence of communication failures, it is advisable to use the [http://www.gnu.org/software/screen GNU Screen] utility. Screen is also very useful when performing several concurrent OpenEmbedded builds for different machine-distro combinations.

Screen installation varies with your OS and distribution.

=== BitBake Overlays ===

Bitbake overlays are useful for OpenEmbedded developers to eliminate bugs or package software without disturbiing the OpenEmbedded tree itself. Overlays are very similar in structure to the OpenEmbedded tree, but are usually only sparsely populated. Non-sparsely poplulated overlays are actually more closely relatedd to separate development branches. Good convention would suggest to always name the overlay appropriately.

Below is an example of two overlays, three build directories, a setup-env script, and a local.conf where the developer has multiple build targets as well as multiple BitBake overlays.
<pre>
oe
|-- build-beagleboard
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-om-gta02
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-ts72xx
| |-- conf
| | `-- local.conf
| `-- tmp
|-- com.somecompany.dev
| |-- conf
| | `-- machine
| `-- packages
| |-- images
| | `-- console-image.bb
| `-- rxtx
| |-- files
| |-- rxtx-fixes-from-debian.patch
| `-- rxtx_2.1-7r2.bb
|-- org.openembedded.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- images
|-- org.openmoko.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- setup-env
</pre>
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02

unset BBPATH

case "${MACHINE}" in
"beagleboard" | "ts72xx" )
BBPATH="${OE_HOME}/com.somecompany.dev"
;;
"om-gta02")
BBPATH="${OE_HOME}/org.openmoko.dev"
;;
*)
echo -e "error: unsupported machine"
exit -1
;;
esac

export BBPATH=${BBPATH}:${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>

Note that the overlay-specific BBPATH entry ''precedes'' the default BBPATH entries.

<pre>
...
BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"
BBFILES += " ${OE_HOME}/org.openmoko.dev/packages/*/*.bb"

BBFILE_COLLECTIONS = "upstream local"
BBFILE_PATTERN_upstream = "${OE_HOME}/org.openembedded.dev"
BBFILE_PRIORITY_upstream = "0"
BBFILE_PATTERN_local = "${OE_HOME}/org.openmoko.dev"
BBFILE_PRIORITY_local = "1"
...
</pre>

In order for the overlay to be detected by BitBake, the above variables need to be defined. It is possible to have more than one overlay and each one should be given a different priority.

=== Useful BitBake Commands ===

<pre>
# list all of the tasks defined for a given package_name
bitbake -c listtasks <package_name>

# clean the work directory for a specific package
bitbake -c clean <package_name>

# build a specific recipe
bitbake -b <path/to/some/recipe.bb>
</pre>

[[Category:Application Developer]]
[[Category:System Developers]]

OpenEmbedded

2009-02-10T19:02:51Z

Cfriedt: /* Building the OpenMoko Distribution with OpenEmbedded */

{{Languages|OpenEmbedded}}

Openmoko, our distribution, is built using OpenEmbedded. OpenEmbedded will:

* Generate (cross-compile) software packages for multiple embedded targets.
* Handle different hardware architectures, and support multiple releases across those architectures.

For more information please see the [http://www.openembedded.org/ Open Embedded] website.

== Building the OpenMoko Distribution with OpenEmbedded ==

'''Note:''' If you are an application developer, you probably do not want to build OpenEmbedded from scratch. For compiling simple applications with few library dependencies (including boot-loader and kernel), consider using our prebuilt [[Toolchain]]. For more complex applications with many library dependencies, download a prebuilt [[OpenEmbedded Torrent]].

Building OpenMoko from scratch is a time-, cpu- and diskspace-consuming process which should only be done if you are a system integrator and want to customize your OpenMoko distribution.

=== Simplified Instructions: MokoMakefile ===

For beginners who wish to customize their OpenMoko distribution, the facility called [[MokoMakefile]] simplifies building OpenEmbedded.

=== Quick Start: OpenEmbedded Torrent ===

If you are a system developer and would like to get up-to-speed as quickly as possible, then download an [[OpenEmbedded Torrent]].

== From Scratch: OpenEmbedded ==

Beginner OpenMoko developers who would prefer to have full control over their OpenEmbedded build environment should follow the instructions below.

=== Preparations ===

Several prerequisite software components are necessary in order to have a fully functional OpenEmbedded build environment. However, setup and installation varies depending on the operating system installed on your workstation. The [http://wiki.openembedded.net/index.php OpenEmbedded Wiki] provides [http://wiki.openembedded.net/index.php/OEandYourDistro setup instructions] for FreeBSD, Mac OS X, and most major Linux distributions, of course.

For OpenEmbedded installation instructions please refer to [http://wiki.openembedded.net/index.php/OEandYourDistro OEandYourDistro].

=== ${OE_HOME} ===

Assuming that you have installed all prerequisite software, you are now ready to create a directory for all of your OpenEmbedded (OE) related work. We will refer to OE_HOME in a generic way, but for argument's sake, assume that it is equal to ${HOME}/oe. You should expect ${OE_HOME} to grow tremendously in size, up to approximately 8GB or larger in some cases. Also be aware, that a full OE build could require several hours of constant building, which may inhibit the performance of your computer while performing other tasks. Replace ${HOME}/oe with your preferred location.

For Bash users:
export OE_HOME=${HOME}/oe

For Tcsh users:
setenv OE_HOME ${HOME}/oe

Next, run 'mkdir -p ${OE_HOME}' to create the directory.

=== Synchronizing OpenEmbedded With Git ===

Just like any tree, OpenEmbedded has several branches. In this case they are called 'development branches'. Some noteworthy ones include org.openembedded.dev (the default) and org.openembedded.stable .

To syncronize the OpenEmbedded tree, run
<pre>
git clone git://git.openembedded.net/openembedded ${OE_HOME}/org.openembedded.dev
</pre>

Note that last argument could be any directory name (git will create the directory if it doesn't exist). Sticking to 'good convention', the directory name was chosen to reflect the default development branch, org.openembedded.dev . See the [http://wiki.openembedded.net/index.php/GitPhraseBook OE GitPhraseBook] for more info on checking out different branches.

To update the tree, run
<pre>
cd ${OE_HOME}/org.openembedded.dev
git pull
</pre>

For further information on Git, see [http://git-scm.com The Git Homepage].

Also, please explore the directory structure of the OpenEmbedded build tree and take a moment to open and read one of the each type of BitBake file. This helps one to become familiar with recipe syntax and the inheritance system. Of particular note, please read the file 'local.conf.sample'.
<pre>
org.openembedded.dev
|-- classes
| |-- rootfs_ipk.bbclass
| `-- xorg-module.bbclass
|-- conf
| `-- local.conf.sample
| |-- distro
| | `-- angstrom-2008.1.conf
| |-- machine
| | |-- om-gta01.conf
| | `-- om-gta02.conf
`-- packages
|-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- images
|-- console-image.bb
|-- fso-console-image.bb
|-- fso-image.bb
|-- openmoko-image.bb
|-- opie-image.bb
`-- x11-image.bb
</pre>
=== Build Configuration ===

If you explored local.conf.example, then you would be aware that there are some very important variables to be set like MACHINE, DISTRO, and BBFILES, among many others. This is done in a configuration file (local.conf) inside the build directory.

'''Note:''' Using BitBake and OE for cross-compilation require that each target-distro combination is built in a separate directory, so that no version collisions occur. Concurrent builds may safely share the same DL_DIR though. This would suggest that a safe name for build directories is of the form ${OE_HOME}/build-${MACHINE}-${DISTRO}. Of course, if you don't plan on building for more than one machine-distro combination, then the naming of this directory is arbitrary. For the purpose of this example, we will use the convention ${OE_HOME}/build-${MACHINE} .

Now, create the 'local.conf' configuration file. Notice that the CACHE and TMPDIR variables are neatly kept within the build directory while the DL_DIR variable is outside of the build directory, so that concurrent builds may reuse the same source packages.
<pre>
OE_HOME ?= "${HOME}/oe"

MACHINE = "om-gta02"
DISTRO = "angstrom-2008.1"

DL_DIR = "${OE_HOME}/downloads"

BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"

BBMASK = ""

TMPDIR = "${OE_HOME}/build-${MACHINE}/tmp"
CACHE = "${TMPDIR}/cache"

IMAGE_FSTYPES = "jffs2 tar.gz"

ENABLE_BINARY_LOCALE_GENERATION = "0"
</pre>

The BBFILES variable is also of prime importance! It tells bitbake where to locate all available recipes for a build. The OpenEmbedded build environment is almost completely ready to go, with just one more minor step left.

=== Build Environment ===

For quick and easy initialization of the OpenEmbedded build environment, it is often suggested that the developer create a 'setup-env' script to source from the command line. This script can be called to initialize the most important of environment variables. Below is a very basic example of a setup-env script.

setup-env for Bash users:
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02
export BBPATH=${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
setup-env for Tcsh users:
<pre>
[[ -z ${OE_HOME} ]] && setenv OE_HOME ${HOME}/oe
[[ -z ${MACHINE} ]] && setenv MACHINE om-gta02
setenv BBPATH ${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
To invoke the setup-env script in bash, run 'source setup-env'. In tcsh, run '. setup-env'.

=== Testing the OE Build Environment ===

That's it! Now you should be prepared to bake your first BitBake recipe.

bitbake helloworld

=== Building an Image ===

There are several full filesystem images which can be built directly with OpenEmbedded using a single command. These include openmoko-image, fso-image, and so on. The image definitions can be found under ${OE_HOME}/org.openembedded.dev/packages/images

A good place to start is with

bitbake fso-image

That concludes this introduction to BitBake and OpenEmbedded. Good luck!

=== Other References ===

Please feel free to refer to other online sources of information for [http://bitbake.berlios.de BitBake], [http://www.openembedded.org OpenEmbedded], and the [http://www.angstrom-distribution.org Angstrom Distribution] to name a few.

== Broken Builds and Bug Reporting ==

Using the org.openembedded.dev branch can often result in broken builds. For that reason, it is usually a good idea to limit synchronizing with the repository only after successfully building an image. Some may even want to archive the tree and build directory after an image is built.

Now in the case that an image does not successfully build, it is not always necessarily a bug or a new bug. The problem might have to do with some conflicting software on the workstation, and it could be a bug that is already know and being fixed.

Below are a few useful steps to follow when a build does not successfully complete:

* Identify the package that failed to build
** Find a line near the bottom of your output that matches "ERROR: ... failed" or "NOTE: ... failed". The name of the package should be contained in the '...'
* If there is a similar, more stable version in ${OE_HOME}/org.openembedded.dev/packages, then try to use that instead
** bitbake -c clean package_name && bitbake -b ${OE_HOME}/org.openembedded.dev/packages/somepackage/somepackage_0.1.bb
** add PREFERRED_VERSION_somepackage = "0.1" to local.conf
* Read the BitBake log, as well as config.log if it exists
** Find the log file. There should be a line near the bottom of your output that matches "ERROR: see log in ...", where '...' contains the log file name. These are usually of the form log.do_compile.12345 or log.do_configure.12345, etc.
* Try to identify the root cause of the error
** In many cases, if one examines log.do_configure, only the error is reported, but not the cause of the error
** Most packages that build with autotools will also have a config.log file that contains the exact cause of the error
* If you can fix the error, and the error is local to your workstation, and not really a bug, then fix the error yourself.
* Otherwise, check the [http://bugs.openembedded.net OpenEmbedded Bugzilla] to see if the error is known.
* If a solution is already available, then try it out. If you can fix the error, then do so. If your solution is correct, please post all relevent patches to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

=== Where to Report Bugs ===

Authentic bugs should be reported to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

== Tips & Tricks ==

=== Setting the PREFERRED_VERSION for a package ===

If a certain package is known to not build, and there is a less recent / more stable version of that package, then a good way to avoid repetitive encounters with known build failures is to use preferred versions of packages.

For example, if building gcc-4.2.4 constantly failed, then it would be wise to edit local.conf and set PREFERRED_VERSION_gcc = "4.1.2".

=== Screen is Your Friend ===

If you happen to be building all of your packages remotely on a server, using an ssh session, the session might occasionally be interrupted and the connection could be terminated. A similar event could occur if your X server suddenly craches. If in the process of building an image with bitbake, this means that the build process will terminate as well.

In order to ensure that a build continues in the presence of communication failures, it is advisable to use the [http://www.gnu.org/software/screen GNU Screen] utility. Screen is also very useful when performing several concurrent OpenEmbedded builds for different machine-distro combinations.

Screen installation varies with your OS and distribution.

=== BitBake Overlays ===

Bitbake overlays are useful for OpenEmbedded developers to eliminate bugs or package software without disturbiing the OpenEmbedded tree itself. Overlays are very similar in structure to the OpenEmbedded tree, but are usually only sparsely populated. Non-sparsely poplulated overlays are actually more closely relatedd to separate development branches. Good convention would suggest to always name the overlay appropriately.

Below is an example of two overlays, three build directories, a setup-env script, and a local.conf where the developer has multiple build targets as well as multiple BitBake overlays.
<pre>
oe
|-- build-beagleboard
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-om-gta02
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-ts72xx
| |-- conf
| | `-- local.conf
| `-- tmp
|-- com.somecompany.dev
| |-- conf
| | `-- machine
| `-- packages
| |-- images
| | `-- console-image.bb
| `-- rxtx
| |-- files
| |-- rxtx-fixes-from-debian.patch
| `-- rxtx_2.1-7r2.bb
|-- org.openembedded.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- images
|-- org.openmoko.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- setup-env
</pre>
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02

unset BBPATH

case "${MACHINE}" in
"beagleboard" | "ts72xx" )
BBPATH="${OE_HOME}/com.somecompany.dev"
;;
"om-gta02")
BBPATH="${OE_HOME}/org.openmoko.dev"
;;
*)
echo -e "error: unsupported machine"
exit -1
;;
esac

export BBPATH=${BBPATH}:${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>

Note that the overlay-specific BBPATH entry ''precedes'' the default BBPATH entries.

<pre>
...
BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"
BBFILES += " ${OE_HOME}/org.openmoko.dev/packages/*/*.bb"

BBFILE_COLLECTIONS = "upstream local"
BBFILE_PATTERN_upstream = "${OE_HOME}/org.openembedded.dev"
BBFILE_PRIORITY_upstream = "0"
BBFILE_PATTERN_local = "${OE_HOME}/org.openmoko.dev"
BBFILE_PRIORITY_local = "1"
...
</pre>

In order for the overlay to be detected by BitBake, the above variables need to be defined. It is possible to have more than one overlay and each one should be given a different priority.

=== Useful BitBake Commands ===

<pre>
# list all of the tasks defined for a given package_name
bitbake -c listtasks <package_name>

# clean the work directory for a specific package
bitbake -c clean <package_name>

# build a specific recipe
bitbake -b <path/to/some/recipe.bb>
</pre>

[[Category:Application Developer]]
[[Category:System Developers]]

OpenEmbedded

2009-02-10T19:01:13Z

Cfriedt: /* Setting the PREFERRED_VERSION for a package */

{{Languages|OpenEmbedded}}

Openmoko, our distribution, is built using OpenEmbedded. OpenEmbedded will:

* Generate (cross-compile) software packages for multiple embedded targets.
* Handle different hardware architectures, and support multiple releases across those architectures.

For more information please see the [http://www.openembedded.org/ Open Embedded] website.

== Building the OpenMoko Distribution with OpenEmbedded ==

'''Note:''' If you are an application developer, you probably do not want to build OpenEmbedded from scratch. For compiling simple applications with few library dependencies (including boot-loader and kernel), consider using our prebuilt [[Toolchain]]. For more complex applications with many library dependencies, download a prebuilt [[OpenEmbedded Torrent]] with your favourite [http://en.wikipedia.org/wiki/BitTorrent_client BitTorrent client].

Building OpenMoko from scratch is a time-, cpu- and diskspace-consuming process which should only be done if you are a system integrator and want to customize your OpenMoko distribution.

=== Simplified Instructions: MokoMakefile ===

For beginners who wish to customize their OpenMoko distribution, the facility called [[MokoMakefile]] simplifies building OpenEmbedded.

=== Quick Start: OpenEmbedded Torrent ===

If you are a system developer and would like to get up-to-speed as quickly as possible, then download an [[OpenEmbedded Torrent]].

== From Scratch: OpenEmbedded ==

Beginner OpenMoko developers who would prefer to have full control over their OpenEmbedded build environment should follow the instructions below.

=== Preparations ===

Several prerequisite software components are necessary in order to have a fully functional OpenEmbedded build environment. However, setup and installation varies depending on the operating system installed on your workstation. The [http://wiki.openembedded.net/index.php OpenEmbedded Wiki] provides [http://wiki.openembedded.net/index.php/OEandYourDistro setup instructions] for FreeBSD, Mac OS X, and most major Linux distributions, of course.

For OpenEmbedded installation instructions please refer to [http://wiki.openembedded.net/index.php/OEandYourDistro OEandYourDistro].

=== ${OE_HOME} ===

Assuming that you have installed all prerequisite software, you are now ready to create a directory for all of your OpenEmbedded (OE) related work. We will refer to OE_HOME in a generic way, but for argument's sake, assume that it is equal to ${HOME}/oe. You should expect ${OE_HOME} to grow tremendously in size, up to approximately 8GB or larger in some cases. Also be aware, that a full OE build could require several hours of constant building, which may inhibit the performance of your computer while performing other tasks. Replace ${HOME}/oe with your preferred location.

For Bash users:
export OE_HOME=${HOME}/oe

For Tcsh users:
setenv OE_HOME ${HOME}/oe

Next, run 'mkdir -p ${OE_HOME}' to create the directory.

=== Synchronizing OpenEmbedded With Git ===

Just like any tree, OpenEmbedded has several branches. In this case they are called 'development branches'. Some noteworthy ones include org.openembedded.dev (the default) and org.openembedded.stable .

To syncronize the OpenEmbedded tree, run
<pre>
git clone git://git.openembedded.net/openembedded ${OE_HOME}/org.openembedded.dev
</pre>

Note that last argument could be any directory name (git will create the directory if it doesn't exist). Sticking to 'good convention', the directory name was chosen to reflect the default development branch, org.openembedded.dev . See the [http://wiki.openembedded.net/index.php/GitPhraseBook OE GitPhraseBook] for more info on checking out different branches.

To update the tree, run
<pre>
cd ${OE_HOME}/org.openembedded.dev
git pull
</pre>

For further information on Git, see [http://git-scm.com The Git Homepage].

Also, please explore the directory structure of the OpenEmbedded build tree and take a moment to open and read one of the each type of BitBake file. This helps one to become familiar with recipe syntax and the inheritance system. Of particular note, please read the file 'local.conf.sample'.
<pre>
org.openembedded.dev
|-- classes
| |-- rootfs_ipk.bbclass
| `-- xorg-module.bbclass
|-- conf
| `-- local.conf.sample
| |-- distro
| | `-- angstrom-2008.1.conf
| |-- machine
| | |-- om-gta01.conf
| | `-- om-gta02.conf
`-- packages
|-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- images
|-- console-image.bb
|-- fso-console-image.bb
|-- fso-image.bb
|-- openmoko-image.bb
|-- opie-image.bb
`-- x11-image.bb
</pre>
=== Build Configuration ===

If you explored local.conf.example, then you would be aware that there are some very important variables to be set like MACHINE, DISTRO, and BBFILES, among many others. This is done in a configuration file (local.conf) inside the build directory.

'''Note:''' Using BitBake and OE for cross-compilation require that each target-distro combination is built in a separate directory, so that no version collisions occur. Concurrent builds may safely share the same DL_DIR though. This would suggest that a safe name for build directories is of the form ${OE_HOME}/build-${MACHINE}-${DISTRO}. Of course, if you don't plan on building for more than one machine-distro combination, then the naming of this directory is arbitrary. For the purpose of this example, we will use the convention ${OE_HOME}/build-${MACHINE} .

Now, create the 'local.conf' configuration file. Notice that the CACHE and TMPDIR variables are neatly kept within the build directory while the DL_DIR variable is outside of the build directory, so that concurrent builds may reuse the same source packages.
<pre>
OE_HOME ?= "${HOME}/oe"

MACHINE = "om-gta02"
DISTRO = "angstrom-2008.1"

DL_DIR = "${OE_HOME}/downloads"

BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"

BBMASK = ""

TMPDIR = "${OE_HOME}/build-${MACHINE}/tmp"
CACHE = "${TMPDIR}/cache"

IMAGE_FSTYPES = "jffs2 tar.gz"

ENABLE_BINARY_LOCALE_GENERATION = "0"
</pre>

The BBFILES variable is also of prime importance! It tells bitbake where to locate all available recipes for a build. The OpenEmbedded build environment is almost completely ready to go, with just one more minor step left.

=== Build Environment ===

For quick and easy initialization of the OpenEmbedded build environment, it is often suggested that the developer create a 'setup-env' script to source from the command line. This script can be called to initialize the most important of environment variables. Below is a very basic example of a setup-env script.

setup-env for Bash users:
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02
export BBPATH=${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
setup-env for Tcsh users:
<pre>
[[ -z ${OE_HOME} ]] && setenv OE_HOME ${HOME}/oe
[[ -z ${MACHINE} ]] && setenv MACHINE om-gta02
setenv BBPATH ${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
To invoke the setup-env script in bash, run 'source setup-env'. In tcsh, run '. setup-env'.

=== Testing the OE Build Environment ===

That's it! Now you should be prepared to bake your first BitBake recipe.

bitbake helloworld

=== Building an Image ===

There are several full filesystem images which can be built directly with OpenEmbedded using a single command. These include openmoko-image, fso-image, and so on. The image definitions can be found under ${OE_HOME}/org.openembedded.dev/packages/images

A good place to start is with

bitbake fso-image

That concludes this introduction to BitBake and OpenEmbedded. Good luck!

=== Other References ===

Please feel free to refer to other online sources of information for [http://bitbake.berlios.de BitBake], [http://www.openembedded.org OpenEmbedded], and the [http://www.angstrom-distribution.org Angstrom Distribution] to name a few.

== Broken Builds and Bug Reporting ==

Using the org.openembedded.dev branch can often result in broken builds. For that reason, it is usually a good idea to limit synchronizing with the repository only after successfully building an image. Some may even want to archive the tree and build directory after an image is built.

Now in the case that an image does not successfully build, it is not always necessarily a bug or a new bug. The problem might have to do with some conflicting software on the workstation, and it could be a bug that is already know and being fixed.

Below are a few useful steps to follow when a build does not successfully complete:

* Identify the package that failed to build
** Find a line near the bottom of your output that matches "ERROR: ... failed" or "NOTE: ... failed". The name of the package should be contained in the '...'
* If there is a similar, more stable version in ${OE_HOME}/org.openembedded.dev/packages, then try to use that instead
** bitbake -c clean package_name && bitbake -b ${OE_HOME}/org.openembedded.dev/packages/somepackage/somepackage_0.1.bb
** add PREFERRED_VERSION_somepackage = "0.1" to local.conf
* Read the BitBake log, as well as config.log if it exists
** Find the log file. There should be a line near the bottom of your output that matches "ERROR: see log in ...", where '...' contains the log file name. These are usually of the form log.do_compile.12345 or log.do_configure.12345, etc.
* Try to identify the root cause of the error
** In many cases, if one examines log.do_configure, only the error is reported, but not the cause of the error
** Most packages that build with autotools will also have a config.log file that contains the exact cause of the error
* If you can fix the error, and the error is local to your workstation, and not really a bug, then fix the error yourself.
* Otherwise, check the [http://bugs.openembedded.net OpenEmbedded Bugzilla] to see if the error is known.
* If a solution is already available, then try it out. If you can fix the error, then do so. If your solution is correct, please post all relevent patches to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

=== Where to Report Bugs ===

Authentic bugs should be reported to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

== Tips & Tricks ==

=== Setting the PREFERRED_VERSION for a package ===

If a certain package is known to not build, and there is a less recent / more stable version of that package, then a good way to avoid repetitive encounters with known build failures is to use preferred versions of packages.

For example, if building gcc-4.2.4 constantly failed, then it would be wise to edit local.conf and set PREFERRED_VERSION_gcc = "4.1.2".

=== Screen is Your Friend ===

If you happen to be building all of your packages remotely on a server, using an ssh session, the session might occasionally be interrupted and the connection could be terminated. A similar event could occur if your X server suddenly craches. If in the process of building an image with bitbake, this means that the build process will terminate as well.

In order to ensure that a build continues in the presence of communication failures, it is advisable to use the [http://www.gnu.org/software/screen GNU Screen] utility. Screen is also very useful when performing several concurrent OpenEmbedded builds for different machine-distro combinations.

Screen installation varies with your OS and distribution.

=== BitBake Overlays ===

Bitbake overlays are useful for OpenEmbedded developers to eliminate bugs or package software without disturbiing the OpenEmbedded tree itself. Overlays are very similar in structure to the OpenEmbedded tree, but are usually only sparsely populated. Non-sparsely poplulated overlays are actually more closely relatedd to separate development branches. Good convention would suggest to always name the overlay appropriately.

Below is an example of two overlays, three build directories, a setup-env script, and a local.conf where the developer has multiple build targets as well as multiple BitBake overlays.
<pre>
oe
|-- build-beagleboard
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-om-gta02
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-ts72xx
| |-- conf
| | `-- local.conf
| `-- tmp
|-- com.somecompany.dev
| |-- conf
| | `-- machine
| `-- packages
| |-- images
| | `-- console-image.bb
| `-- rxtx
| |-- files
| |-- rxtx-fixes-from-debian.patch
| `-- rxtx_2.1-7r2.bb
|-- org.openembedded.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- images
|-- org.openmoko.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- setup-env
</pre>
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02

unset BBPATH

case "${MACHINE}" in
"beagleboard" | "ts72xx" )
BBPATH="${OE_HOME}/com.somecompany.dev"
;;
"om-gta02")
BBPATH="${OE_HOME}/org.openmoko.dev"
;;
*)
echo -e "error: unsupported machine"
exit -1
;;
esac

export BBPATH=${BBPATH}:${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>

Note that the overlay-specific BBPATH entry ''precedes'' the default BBPATH entries.

<pre>
...
BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"
BBFILES += " ${OE_HOME}/org.openmoko.dev/packages/*/*.bb"

BBFILE_COLLECTIONS = "upstream local"
BBFILE_PATTERN_upstream = "${OE_HOME}/org.openembedded.dev"
BBFILE_PRIORITY_upstream = "0"
BBFILE_PATTERN_local = "${OE_HOME}/org.openmoko.dev"
BBFILE_PRIORITY_local = "1"
...
</pre>

In order for the overlay to be detected by BitBake, the above variables need to be defined. It is possible to have more than one overlay and each one should be given a different priority.

=== Useful BitBake Commands ===

<pre>
# list all of the tasks defined for a given package_name
bitbake -c listtasks <package_name>

# clean the work directory for a specific package
bitbake -c clean <package_name>

# build a specific recipe
bitbake -b <path/to/some/recipe.bb>
</pre>

[[Category:Application Developer]]
[[Category:System Developers]]

OpenEmbedded

2009-02-10T18:59:50Z

Cfriedt: /* Tips & Tricks */

{{Languages|OpenEmbedded}}

Openmoko, our distribution, is built using OpenEmbedded. OpenEmbedded will:

* Generate (cross-compile) software packages for multiple embedded targets.
* Handle different hardware architectures, and support multiple releases across those architectures.

For more information please see the [http://www.openembedded.org/ Open Embedded] website.

== Building the OpenMoko Distribution with OpenEmbedded ==

'''Note:''' If you are an application developer, you probably do not want to build OpenEmbedded from scratch. For compiling simple applications with few library dependencies (including boot-loader and kernel), consider using our prebuilt [[Toolchain]]. For more complex applications with many library dependencies, download a prebuilt [[OpenEmbedded Torrent]] with your favourite [http://en.wikipedia.org/wiki/BitTorrent_client BitTorrent client].

Building OpenMoko from scratch is a time-, cpu- and diskspace-consuming process which should only be done if you are a system integrator and want to customize your OpenMoko distribution.

=== Simplified Instructions: MokoMakefile ===

For beginners who wish to customize their OpenMoko distribution, the facility called [[MokoMakefile]] simplifies building OpenEmbedded.

=== Quick Start: OpenEmbedded Torrent ===

If you are a system developer and would like to get up-to-speed as quickly as possible, then download an [[OpenEmbedded Torrent]].

== From Scratch: OpenEmbedded ==

Beginner OpenMoko developers who would prefer to have full control over their OpenEmbedded build environment should follow the instructions below.

=== Preparations ===

Several prerequisite software components are necessary in order to have a fully functional OpenEmbedded build environment. However, setup and installation varies depending on the operating system installed on your workstation. The [http://wiki.openembedded.net/index.php OpenEmbedded Wiki] provides [http://wiki.openembedded.net/index.php/OEandYourDistro setup instructions] for FreeBSD, Mac OS X, and most major Linux distributions, of course.

For OpenEmbedded installation instructions please refer to [http://wiki.openembedded.net/index.php/OEandYourDistro OEandYourDistro].

=== ${OE_HOME} ===

Assuming that you have installed all prerequisite software, you are now ready to create a directory for all of your OpenEmbedded (OE) related work. We will refer to OE_HOME in a generic way, but for argument's sake, assume that it is equal to ${HOME}/oe. You should expect ${OE_HOME} to grow tremendously in size, up to approximately 8GB or larger in some cases. Also be aware, that a full OE build could require several hours of constant building, which may inhibit the performance of your computer while performing other tasks. Replace ${HOME}/oe with your preferred location.

For Bash users:
export OE_HOME=${HOME}/oe

For Tcsh users:
setenv OE_HOME ${HOME}/oe

Next, run 'mkdir -p ${OE_HOME}' to create the directory.

=== Synchronizing OpenEmbedded With Git ===

Just like any tree, OpenEmbedded has several branches. In this case they are called 'development branches'. Some noteworthy ones include org.openembedded.dev (the default) and org.openembedded.stable .

To syncronize the OpenEmbedded tree, run
<pre>
git clone git://git.openembedded.net/openembedded ${OE_HOME}/org.openembedded.dev
</pre>

Note that last argument could be any directory name (git will create the directory if it doesn't exist). Sticking to 'good convention', the directory name was chosen to reflect the default development branch, org.openembedded.dev . See the [http://wiki.openembedded.net/index.php/GitPhraseBook OE GitPhraseBook] for more info on checking out different branches.

To update the tree, run
<pre>
cd ${OE_HOME}/org.openembedded.dev
git pull
</pre>

For further information on Git, see [http://git-scm.com The Git Homepage].

Also, please explore the directory structure of the OpenEmbedded build tree and take a moment to open and read one of the each type of BitBake file. This helps one to become familiar with recipe syntax and the inheritance system. Of particular note, please read the file 'local.conf.sample'.
<pre>
org.openembedded.dev
|-- classes
| |-- rootfs_ipk.bbclass
| `-- xorg-module.bbclass
|-- conf
| `-- local.conf.sample
| |-- distro
| | `-- angstrom-2008.1.conf
| |-- machine
| | |-- om-gta01.conf
| | `-- om-gta02.conf
`-- packages
|-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- images
|-- console-image.bb
|-- fso-console-image.bb
|-- fso-image.bb
|-- openmoko-image.bb
|-- opie-image.bb
`-- x11-image.bb
</pre>
=== Build Configuration ===

If you explored local.conf.example, then you would be aware that there are some very important variables to be set like MACHINE, DISTRO, and BBFILES, among many others. This is done in a configuration file (local.conf) inside the build directory.

'''Note:''' Using BitBake and OE for cross-compilation require that each target-distro combination is built in a separate directory, so that no version collisions occur. Concurrent builds may safely share the same DL_DIR though. This would suggest that a safe name for build directories is of the form ${OE_HOME}/build-${MACHINE}-${DISTRO}. Of course, if you don't plan on building for more than one machine-distro combination, then the naming of this directory is arbitrary. For the purpose of this example, we will use the convention ${OE_HOME}/build-${MACHINE} .

Now, create the 'local.conf' configuration file. Notice that the CACHE and TMPDIR variables are neatly kept within the build directory while the DL_DIR variable is outside of the build directory, so that concurrent builds may reuse the same source packages.
<pre>
OE_HOME ?= "${HOME}/oe"

MACHINE = "om-gta02"
DISTRO = "angstrom-2008.1"

DL_DIR = "${OE_HOME}/downloads"

BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"

BBMASK = ""

TMPDIR = "${OE_HOME}/build-${MACHINE}/tmp"
CACHE = "${TMPDIR}/cache"

IMAGE_FSTYPES = "jffs2 tar.gz"

ENABLE_BINARY_LOCALE_GENERATION = "0"
</pre>

The BBFILES variable is also of prime importance! It tells bitbake where to locate all available recipes for a build. The OpenEmbedded build environment is almost completely ready to go, with just one more minor step left.

=== Build Environment ===

For quick and easy initialization of the OpenEmbedded build environment, it is often suggested that the developer create a 'setup-env' script to source from the command line. This script can be called to initialize the most important of environment variables. Below is a very basic example of a setup-env script.

setup-env for Bash users:
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02
export BBPATH=${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
setup-env for Tcsh users:
<pre>
[[ -z ${OE_HOME} ]] && setenv OE_HOME ${HOME}/oe
[[ -z ${MACHINE} ]] && setenv MACHINE om-gta02
setenv BBPATH ${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
To invoke the setup-env script in bash, run 'source setup-env'. In tcsh, run '. setup-env'.

=== Testing the OE Build Environment ===

That's it! Now you should be prepared to bake your first BitBake recipe.

bitbake helloworld

=== Building an Image ===

There are several full filesystem images which can be built directly with OpenEmbedded using a single command. These include openmoko-image, fso-image, and so on. The image definitions can be found under ${OE_HOME}/org.openembedded.dev/packages/images

A good place to start is with

bitbake fso-image

That concludes this introduction to BitBake and OpenEmbedded. Good luck!

=== Other References ===

Please feel free to refer to other online sources of information for [http://bitbake.berlios.de BitBake], [http://www.openembedded.org OpenEmbedded], and the [http://www.angstrom-distribution.org Angstrom Distribution] to name a few.

== Broken Builds and Bug Reporting ==

Using the org.openembedded.dev branch can often result in broken builds. For that reason, it is usually a good idea to limit synchronizing with the repository only after successfully building an image. Some may even want to archive the tree and build directory after an image is built.

Now in the case that an image does not successfully build, it is not always necessarily a bug or a new bug. The problem might have to do with some conflicting software on the workstation, and it could be a bug that is already know and being fixed.

Below are a few useful steps to follow when a build does not successfully complete:

* Identify the package that failed to build
** Find a line near the bottom of your output that matches "ERROR: ... failed" or "NOTE: ... failed". The name of the package should be contained in the '...'
* If there is a similar, more stable version in ${OE_HOME}/org.openembedded.dev/packages, then try to use that instead
** bitbake -c clean package_name && bitbake -b ${OE_HOME}/org.openembedded.dev/packages/somepackage/somepackage_0.1.bb
** add PREFERRED_VERSION_somepackage = "0.1" to local.conf
* Read the BitBake log, as well as config.log if it exists
** Find the log file. There should be a line near the bottom of your output that matches "ERROR: see log in ...", where '...' contains the log file name. These are usually of the form log.do_compile.12345 or log.do_configure.12345, etc.
* Try to identify the root cause of the error
** In many cases, if one examines log.do_configure, only the error is reported, but not the cause of the error
** Most packages that build with autotools will also have a config.log file that contains the exact cause of the error
* If you can fix the error, and the error is local to your workstation, and not really a bug, then fix the error yourself.
* Otherwise, check the [http://bugs.openembedded.net OpenEmbedded Bugzilla] to see if the error is known.
* If a solution is already available, then try it out. If you can fix the error, then do so. If your solution is correct, please post all relevent patches to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

=== Where to Report Bugs ===

Authentic bugs should be reported to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

== Tips & Tricks ==

=== Setting the PREFERRED_VERSION for a package ===

A good way to avoid repetitive encounters with known build failures is to use preferred versions of packages. For example, if building gcc-4.2.4 constantly failed, then it would be wise to edit local.conf and set PREFERRED_VERSION_gcc = "4.1.2".

=== Screen is Your Friend ===

If you happen to be building all of your packages remotely on a server, using an ssh session, the session might occasionally be interrupted and the connection could be terminated. A similar event could occur if your X server suddenly craches. If in the process of building an image with bitbake, this means that the build process will terminate as well.

In order to ensure that a build continues in the presence of communication failures, it is advisable to use the [http://www.gnu.org/software/screen GNU Screen] utility. Screen is also very useful when performing several concurrent OpenEmbedded builds for different machine-distro combinations.

Screen installation varies with your OS and distribution.

=== BitBake Overlays ===

Bitbake overlays are useful for OpenEmbedded developers to eliminate bugs or package software without disturbiing the OpenEmbedded tree itself. Overlays are very similar in structure to the OpenEmbedded tree, but are usually only sparsely populated. Non-sparsely poplulated overlays are actually more closely relatedd to separate development branches. Good convention would suggest to always name the overlay appropriately.

Below is an example of two overlays, three build directories, a setup-env script, and a local.conf where the developer has multiple build targets as well as multiple BitBake overlays.
<pre>
oe
|-- build-beagleboard
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-om-gta02
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-ts72xx
| |-- conf
| | `-- local.conf
| `-- tmp
|-- com.somecompany.dev
| |-- conf
| | `-- machine
| `-- packages
| |-- images
| | `-- console-image.bb
| `-- rxtx
| |-- files
| |-- rxtx-fixes-from-debian.patch
| `-- rxtx_2.1-7r2.bb
|-- org.openembedded.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- images
|-- org.openmoko.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- setup-env
</pre>
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02

unset BBPATH

case "${MACHINE}" in
"beagleboard" | "ts72xx" )
BBPATH="${OE_HOME}/com.somecompany.dev"
;;
"om-gta02")
BBPATH="${OE_HOME}/org.openmoko.dev"
;;
*)
echo -e "error: unsupported machine"
exit -1
;;
esac

export BBPATH=${BBPATH}:${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>

Note that the overlay-specific BBPATH entry ''precedes'' the default BBPATH entries.

<pre>
...
BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"
BBFILES += " ${OE_HOME}/org.openmoko.dev/packages/*/*.bb"

BBFILE_COLLECTIONS = "upstream local"
BBFILE_PATTERN_upstream = "${OE_HOME}/org.openembedded.dev"
BBFILE_PRIORITY_upstream = "0"
BBFILE_PATTERN_local = "${OE_HOME}/org.openmoko.dev"
BBFILE_PRIORITY_local = "1"
...
</pre>

In order for the overlay to be detected by BitBake, the above variables need to be defined. It is possible to have more than one overlay and each one should be given a different priority.

=== Useful BitBake Commands ===

<pre>
# list all of the tasks defined for a given package_name
bitbake -c listtasks <package_name>

# clean the work directory for a specific package
bitbake -c clean <package_name>

# build a specific recipe
bitbake -b <path/to/some/recipe.bb>
</pre>

[[Category:Application Developer]]
[[Category:System Developers]]

OpenEmbedded

2009-02-10T18:53:53Z

Cfriedt: /* Screen is Your Friend */

{{Languages|OpenEmbedded}}

Openmoko, our distribution, is built using OpenEmbedded. OpenEmbedded will:

* Generate (cross-compile) software packages for multiple embedded targets.
* Handle different hardware architectures, and support multiple releases across those architectures.

For more information please see the [http://www.openembedded.org/ Open Embedded] website.

== Building the OpenMoko Distribution with OpenEmbedded ==

'''Note:''' If you are an application developer, you probably do not want to build OpenEmbedded from scratch. For compiling simple applications with few library dependencies (including boot-loader and kernel), consider using our prebuilt [[Toolchain]]. For more complex applications with many library dependencies, download a prebuilt [[OpenEmbedded Torrent]] with your favourite [http://en.wikipedia.org/wiki/BitTorrent_client BitTorrent client].

Building OpenMoko from scratch is a time-, cpu- and diskspace-consuming process which should only be done if you are a system integrator and want to customize your OpenMoko distribution.

=== Simplified Instructions: MokoMakefile ===

For beginners who wish to customize their OpenMoko distribution, the facility called [[MokoMakefile]] simplifies building OpenEmbedded.

=== Quick Start: OpenEmbedded Torrent ===

If you are a system developer and would like to get up-to-speed as quickly as possible, then download an [[OpenEmbedded Torrent]].

== From Scratch: OpenEmbedded ==

Beginner OpenMoko developers who would prefer to have full control over their OpenEmbedded build environment should follow the instructions below.

=== Preparations ===

Several prerequisite software components are necessary in order to have a fully functional OpenEmbedded build environment. However, setup and installation varies depending on the operating system installed on your workstation. The [http://wiki.openembedded.net/index.php OpenEmbedded Wiki] provides [http://wiki.openembedded.net/index.php/OEandYourDistro setup instructions] for FreeBSD, Mac OS X, and most major Linux distributions, of course.

For OpenEmbedded installation instructions please refer to [http://wiki.openembedded.net/index.php/OEandYourDistro OEandYourDistro].

=== ${OE_HOME} ===

Assuming that you have installed all prerequisite software, you are now ready to create a directory for all of your OpenEmbedded (OE) related work. We will refer to OE_HOME in a generic way, but for argument's sake, assume that it is equal to ${HOME}/oe. You should expect ${OE_HOME} to grow tremendously in size, up to approximately 8GB or larger in some cases. Also be aware, that a full OE build could require several hours of constant building, which may inhibit the performance of your computer while performing other tasks. Replace ${HOME}/oe with your preferred location.

For Bash users:
export OE_HOME=${HOME}/oe

For Tcsh users:
setenv OE_HOME ${HOME}/oe

Next, run 'mkdir -p ${OE_HOME}' to create the directory.

=== Synchronizing OpenEmbedded With Git ===

Just like any tree, OpenEmbedded has several branches. In this case they are called 'development branches'. Some noteworthy ones include org.openembedded.dev (the default) and org.openembedded.stable .

To syncronize the OpenEmbedded tree, run
<pre>
git clone git://git.openembedded.net/openembedded ${OE_HOME}/org.openembedded.dev
</pre>

Note that last argument could be any directory name (git will create the directory if it doesn't exist). Sticking to 'good convention', the directory name was chosen to reflect the default development branch, org.openembedded.dev . See the [http://wiki.openembedded.net/index.php/GitPhraseBook OE GitPhraseBook] for more info on checking out different branches.

To update the tree, run
<pre>
cd ${OE_HOME}/org.openembedded.dev
git pull
</pre>

For further information on Git, see [http://git-scm.com The Git Homepage].

Also, please explore the directory structure of the OpenEmbedded build tree and take a moment to open and read one of the each type of BitBake file. This helps one to become familiar with recipe syntax and the inheritance system. Of particular note, please read the file 'local.conf.sample'.
<pre>
org.openembedded.dev
|-- classes
| |-- rootfs_ipk.bbclass
| `-- xorg-module.bbclass
|-- conf
| `-- local.conf.sample
| |-- distro
| | `-- angstrom-2008.1.conf
| |-- machine
| | |-- om-gta01.conf
| | `-- om-gta02.conf
`-- packages
|-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- images
|-- console-image.bb
|-- fso-console-image.bb
|-- fso-image.bb
|-- openmoko-image.bb
|-- opie-image.bb
`-- x11-image.bb
</pre>
=== Build Configuration ===

If you explored local.conf.example, then you would be aware that there are some very important variables to be set like MACHINE, DISTRO, and BBFILES, among many others. This is done in a configuration file (local.conf) inside the build directory.

'''Note:''' Using BitBake and OE for cross-compilation require that each target-distro combination is built in a separate directory, so that no version collisions occur. Concurrent builds may safely share the same DL_DIR though. This would suggest that a safe name for build directories is of the form ${OE_HOME}/build-${MACHINE}-${DISTRO}. Of course, if you don't plan on building for more than one machine-distro combination, then the naming of this directory is arbitrary. For the purpose of this example, we will use the convention ${OE_HOME}/build-${MACHINE} .

Now, create the 'local.conf' configuration file. Notice that the CACHE and TMPDIR variables are neatly kept within the build directory while the DL_DIR variable is outside of the build directory, so that concurrent builds may reuse the same source packages.
<pre>
OE_HOME ?= "${HOME}/oe"

MACHINE = "om-gta02"
DISTRO = "angstrom-2008.1"

DL_DIR = "${OE_HOME}/downloads"

BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"

BBMASK = ""

TMPDIR = "${OE_HOME}/build-${MACHINE}/tmp"
CACHE = "${TMPDIR}/cache"

IMAGE_FSTYPES = "jffs2 tar.gz"

ENABLE_BINARY_LOCALE_GENERATION = "0"
</pre>

The BBFILES variable is also of prime importance! It tells bitbake where to locate all available recipes for a build. The OpenEmbedded build environment is almost completely ready to go, with just one more minor step left.

=== Build Environment ===

For quick and easy initialization of the OpenEmbedded build environment, it is often suggested that the developer create a 'setup-env' script to source from the command line. This script can be called to initialize the most important of environment variables. Below is a very basic example of a setup-env script.

setup-env for Bash users:
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02
export BBPATH=${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
setup-env for Tcsh users:
<pre>
[[ -z ${OE_HOME} ]] && setenv OE_HOME ${HOME}/oe
[[ -z ${MACHINE} ]] && setenv MACHINE om-gta02
setenv BBPATH ${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
To invoke the setup-env script in bash, run 'source setup-env'. In tcsh, run '. setup-env'.

=== Testing the OE Build Environment ===

That's it! Now you should be prepared to bake your first BitBake recipe.

bitbake helloworld

=== Building an Image ===

There are several full filesystem images which can be built directly with OpenEmbedded using a single command. These include openmoko-image, fso-image, and so on. The image definitions can be found under ${OE_HOME}/org.openembedded.dev/packages/images

A good place to start is with

bitbake fso-image

That concludes this introduction to BitBake and OpenEmbedded. Good luck!

=== Other References ===

Please feel free to refer to other online sources of information for [http://bitbake.berlios.de BitBake], [http://www.openembedded.org OpenEmbedded], and the [http://www.angstrom-distribution.org Angstrom Distribution] to name a few.

== Broken Builds and Bug Reporting ==

Using the org.openembedded.dev branch can often result in broken builds. For that reason, it is usually a good idea to limit synchronizing with the repository only after successfully building an image. Some may even want to archive the tree and build directory after an image is built.

Now in the case that an image does not successfully build, it is not always necessarily a bug or a new bug. The problem might have to do with some conflicting software on the workstation, and it could be a bug that is already know and being fixed.

Below are a few useful steps to follow when a build does not successfully complete:

* Identify the package that failed to build
** Find a line near the bottom of your output that matches "ERROR: ... failed" or "NOTE: ... failed". The name of the package should be contained in the '...'
* If there is a similar, more stable version in ${OE_HOME}/org.openembedded.dev/packages, then try to use that instead
** bitbake -c clean package_name && bitbake -b ${OE_HOME}/org.openembedded.dev/packages/somepackage/somepackage_0.1.bb
** add PREFERRED_VERSION_somepackage = "0.1" to local.conf
* Read the BitBake log, as well as config.log if it exists
** Find the log file. There should be a line near the bottom of your output that matches "ERROR: see log in ...", where '...' contains the log file name. These are usually of the form log.do_compile.12345 or log.do_configure.12345, etc.
* Try to identify the root cause of the error
** In many cases, if one examines log.do_configure, only the error is reported, but not the cause of the error
** Most packages that build with autotools will also have a config.log file that contains the exact cause of the error
* If you can fix the error, and the error is local to your workstation, and not really a bug, then fix the error yourself.
* Otherwise, check the [http://bugs.openembedded.net OpenEmbedded Bugzilla] to see if the error is known.
* If a solution is already available, then try it out. If you can fix the error, then do so. If your solution is correct, please post all relevent patches to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

=== Where to Report Bugs ===

Authentic bugs should be reported to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

== Tips & Tricks ==

=== Screen is Your Friend ===

If you happen to be building all of your packages remotely on a server, using an ssh session, the session might occasionally be interrupted and the connection could be terminated. A similar event could occur if your X server suddenly craches. If in the process of building an image with bitbake, this means that the build process will terminate as well.

In order to ensure that a build continues in the presence of communication failures, it is advisable to use the [http://www.gnu.org/software/screen GNU Screen] utility. Screen is also very useful when performing several concurrent OpenEmbedded builds for different machine-distro combinations.

Screen installation varies with your OS and distribution.

=== BitBake Overlays ===

Bitbake overlays are useful for OpenEmbedded developers to eliminate bugs or package software without disturbiing the OpenEmbedded tree itself. Overlays are very similar in structure to the OpenEmbedded tree, but are usually only sparsely populated. Non-sparsely poplulated overlays are actually more closely relatedd to separate development branches. Good convention would suggest to always name the overlay appropriately.

Below is an example of two overlays, three build directories, a setup-env script, and a local.conf where the developer has multiple build targets as well as multiple BitBake overlays.
<pre>
oe
|-- build-beagleboard
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-om-gta02
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-ts72xx
| |-- conf
| | `-- local.conf
| `-- tmp
|-- com.somecompany.dev
| |-- conf
| | `-- machine
| `-- packages
| |-- images
| | `-- console-image.bb
| `-- rxtx
| |-- files
| |-- rxtx-fixes-from-debian.patch
| `-- rxtx_2.1-7r2.bb
|-- org.openembedded.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- images
|-- org.openmoko.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- setup-env
</pre>
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02

unset BBPATH

case "${MACHINE}" in
"beagleboard" | "ts72xx" )
BBPATH="${OE_HOME}/com.somecompany.dev"
;;
"om-gta02")
BBPATH="${OE_HOME}/org.openmoko.dev"
;;
*)
echo -e "error: unsupported machine"
exit -1
;;
esac

export BBPATH=${BBPATH}:${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>

Note that the overlay-specific BBPATH entry ''precedes'' the default BBPATH entries.

<pre>
...
BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"
BBFILES += " ${OE_HOME}/org.openmoko.dev/packages/*/*.bb"

BBFILE_COLLECTIONS = "upstream local"
BBFILE_PATTERN_upstream = "${OE_HOME}/org.openembedded.dev"
BBFILE_PRIORITY_upstream = "0"
BBFILE_PATTERN_local = "${OE_HOME}/org.openmoko.dev"
BBFILE_PRIORITY_local = "1"
...
</pre>

In order for the overlay to be detected by BitBake, the above variables need to be defined. It is possible to have more than one overlay and each one should be given a different priority.

=== Useful BitBake Commands ===

<pre>
# list all of the tasks defined for a given package_name
bitbake -c listtasks <package_name>

# clean the work directory for a specific package
bitbake -c clean <package_name>

# build a specific recipe
bitbake -b <path/to/some/recipe.bb>
</pre>

[[Category:Application Developer]]
[[Category:System Developers]]

BitBake

2009-02-10T18:51:39Z

Cfriedt: Please refer to the OpenEmbedded page for OE instructions and the BitBake_recipe page for BitBake instructions

{{Languages|BitBake}}
BitBake is the build tool used by [[OpenEmbedded]] and was originally used by the OpenHandhelds and OpenZaurus communities.

[[BitBake recipe]]s are simple, declarative files.

OpenEmbedded

2009-02-10T18:45:56Z

Cfriedt: /* Broken Builds and Bug Reporting */

{{Languages|OpenEmbedded}}

Openmoko, our distribution, is built using OpenEmbedded. OpenEmbedded will:

* Generate (cross-compile) software packages for multiple embedded targets.
* Handle different hardware architectures, and support multiple releases across those architectures.

For more information please see the [http://www.openembedded.org/ Open Embedded] website.

== Building the OpenMoko Distribution with OpenEmbedded ==

'''Note:''' If you are an application developer, you probably do not want to build OpenEmbedded from scratch. For compiling simple applications with few library dependencies (including boot-loader and kernel), consider using our prebuilt [[Toolchain]]. For more complex applications with many library dependencies, download a prebuilt [[OpenEmbedded Torrent]] with your favourite [http://en.wikipedia.org/wiki/BitTorrent_client BitTorrent client].

Building OpenMoko from scratch is a time-, cpu- and diskspace-consuming process which should only be done if you are a system integrator and want to customize your OpenMoko distribution.

=== Simplified Instructions: MokoMakefile ===

For beginners who wish to customize their OpenMoko distribution, the facility called [[MokoMakefile]] simplifies building OpenEmbedded.

=== Quick Start: OpenEmbedded Torrent ===

If you are a system developer and would like to get up-to-speed as quickly as possible, then download an [[OpenEmbedded Torrent]].

== From Scratch: OpenEmbedded ==

Beginner OpenMoko developers who would prefer to have full control over their OpenEmbedded build environment should follow the instructions below.

=== Preparations ===

Several prerequisite software components are necessary in order to have a fully functional OpenEmbedded build environment. However, setup and installation varies depending on the operating system installed on your workstation. The [http://wiki.openembedded.net/index.php OpenEmbedded Wiki] provides [http://wiki.openembedded.net/index.php/OEandYourDistro setup instructions] for FreeBSD, Mac OS X, and most major Linux distributions, of course.

For OpenEmbedded installation instructions please refer to [http://wiki.openembedded.net/index.php/OEandYourDistro OEandYourDistro].

=== ${OE_HOME} ===

Assuming that you have installed all prerequisite software, you are now ready to create a directory for all of your OpenEmbedded (OE) related work. We will refer to OE_HOME in a generic way, but for argument's sake, assume that it is equal to ${HOME}/oe. You should expect ${OE_HOME} to grow tremendously in size, up to approximately 8GB or larger in some cases. Also be aware, that a full OE build could require several hours of constant building, which may inhibit the performance of your computer while performing other tasks. Replace ${HOME}/oe with your preferred location.

For Bash users:
export OE_HOME=${HOME}/oe

For Tcsh users:
setenv OE_HOME ${HOME}/oe

Next, run 'mkdir -p ${OE_HOME}' to create the directory.

=== Synchronizing OpenEmbedded With Git ===

Just like any tree, OpenEmbedded has several branches. In this case they are called 'development branches'. Some noteworthy ones include org.openembedded.dev (the default) and org.openembedded.stable .

To syncronize the OpenEmbedded tree, run
<pre>
git clone git://git.openembedded.net/openembedded ${OE_HOME}/org.openembedded.dev
</pre>

Note that last argument could be any directory name (git will create the directory if it doesn't exist). Sticking to 'good convention', the directory name was chosen to reflect the default development branch, org.openembedded.dev . See the [http://wiki.openembedded.net/index.php/GitPhraseBook OE GitPhraseBook] for more info on checking out different branches.

To update the tree, run
<pre>
cd ${OE_HOME}/org.openembedded.dev
git pull
</pre>

For further information on Git, see [http://git-scm.com The Git Homepage].

Also, please explore the directory structure of the OpenEmbedded build tree and take a moment to open and read one of the each type of BitBake file. This helps one to become familiar with recipe syntax and the inheritance system. Of particular note, please read the file 'local.conf.sample'.
<pre>
org.openembedded.dev
|-- classes
| |-- rootfs_ipk.bbclass
| `-- xorg-module.bbclass
|-- conf
| `-- local.conf.sample
| |-- distro
| | `-- angstrom-2008.1.conf
| |-- machine
| | |-- om-gta01.conf
| | `-- om-gta02.conf
`-- packages
|-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- images
|-- console-image.bb
|-- fso-console-image.bb
|-- fso-image.bb
|-- openmoko-image.bb
|-- opie-image.bb
`-- x11-image.bb
</pre>
=== Build Configuration ===

If you explored local.conf.example, then you would be aware that there are some very important variables to be set like MACHINE, DISTRO, and BBFILES, among many others. This is done in a configuration file (local.conf) inside the build directory.

'''Note:''' Using BitBake and OE for cross-compilation require that each target-distro combination is built in a separate directory, so that no version collisions occur. Concurrent builds may safely share the same DL_DIR though. This would suggest that a safe name for build directories is of the form ${OE_HOME}/build-${MACHINE}-${DISTRO}. Of course, if you don't plan on building for more than one machine-distro combination, then the naming of this directory is arbitrary. For the purpose of this example, we will use the convention ${OE_HOME}/build-${MACHINE} .

Now, create the 'local.conf' configuration file. Notice that the CACHE and TMPDIR variables are neatly kept within the build directory while the DL_DIR variable is outside of the build directory, so that concurrent builds may reuse the same source packages.
<pre>
OE_HOME ?= "${HOME}/oe"

MACHINE = "om-gta02"
DISTRO = "angstrom-2008.1"

DL_DIR = "${OE_HOME}/downloads"

BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"

BBMASK = ""

TMPDIR = "${OE_HOME}/build-${MACHINE}/tmp"
CACHE = "${TMPDIR}/cache"

IMAGE_FSTYPES = "jffs2 tar.gz"

ENABLE_BINARY_LOCALE_GENERATION = "0"
</pre>

The BBFILES variable is also of prime importance! It tells bitbake where to locate all available recipes for a build. The OpenEmbedded build environment is almost completely ready to go, with just one more minor step left.

=== Build Environment ===

For quick and easy initialization of the OpenEmbedded build environment, it is often suggested that the developer create a 'setup-env' script to source from the command line. This script can be called to initialize the most important of environment variables. Below is a very basic example of a setup-env script.

setup-env for Bash users:
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02
export BBPATH=${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
setup-env for Tcsh users:
<pre>
[[ -z ${OE_HOME} ]] && setenv OE_HOME ${HOME}/oe
[[ -z ${MACHINE} ]] && setenv MACHINE om-gta02
setenv BBPATH ${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
To invoke the setup-env script in bash, run 'source setup-env'. In tcsh, run '. setup-env'.

=== Testing the OE Build Environment ===

That's it! Now you should be prepared to bake your first BitBake recipe.

bitbake helloworld

=== Building an Image ===

There are several full filesystem images which can be built directly with OpenEmbedded using a single command. These include openmoko-image, fso-image, and so on. The image definitions can be found under ${OE_HOME}/org.openembedded.dev/packages/images

A good place to start is with

bitbake fso-image

That concludes this introduction to BitBake and OpenEmbedded. Good luck!

=== Other References ===

Please feel free to refer to other online sources of information for [http://bitbake.berlios.de BitBake], [http://www.openembedded.org OpenEmbedded], and the [http://www.angstrom-distribution.org Angstrom Distribution] to name a few.

== Broken Builds and Bug Reporting ==

Using the org.openembedded.dev branch can often result in broken builds. For that reason, it is usually a good idea to limit synchronizing with the repository only after successfully building an image. Some may even want to archive the tree and build directory after an image is built.

Now in the case that an image does not successfully build, it is not always necessarily a bug or a new bug. The problem might have to do with some conflicting software on the workstation, and it could be a bug that is already know and being fixed.

Below are a few useful steps to follow when a build does not successfully complete:

* Identify the package that failed to build
** Find a line near the bottom of your output that matches "ERROR: ... failed" or "NOTE: ... failed". The name of the package should be contained in the '...'
* If there is a similar, more stable version in ${OE_HOME}/org.openembedded.dev/packages, then try to use that instead
** bitbake -c clean package_name && bitbake -b ${OE_HOME}/org.openembedded.dev/packages/somepackage/somepackage_0.1.bb
** add PREFERRED_VERSION_somepackage = "0.1" to local.conf
* Read the BitBake log, as well as config.log if it exists
** Find the log file. There should be a line near the bottom of your output that matches "ERROR: see log in ...", where '...' contains the log file name. These are usually of the form log.do_compile.12345 or log.do_configure.12345, etc.
* Try to identify the root cause of the error
** In many cases, if one examines log.do_configure, only the error is reported, but not the cause of the error
** Most packages that build with autotools will also have a config.log file that contains the exact cause of the error
* If you can fix the error, and the error is local to your workstation, and not really a bug, then fix the error yourself.
* Otherwise, check the [http://bugs.openembedded.net OpenEmbedded Bugzilla] to see if the error is known.
* If a solution is already available, then try it out. If you can fix the error, then do so. If your solution is correct, please post all relevent patches to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

=== Where to Report Bugs ===

Authentic bugs should be reported to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

== Tips & Tricks ==

=== Screen is Your Friend ===

If you happen to be building all of your packages remotely on a server, using an ssh session, the session might occasionally be interrupted and the connection could be terminated. If in the process of building an image with bitbake, this means that the build process will terminate as well.

In order to ensure that a build continues in the presence of communication failures, it is advisable to use the [http://www.gnu.org/software/screen GNU Screen] utility. Screen is also very useful when performing several concurrent OpenEmbedded builds for different machine-distro combinations.

Screen installation varies with your OS and distribution.

=== BitBake Overlays ===

Bitbake overlays are useful for OpenEmbedded developers to eliminate bugs or package software without disturbiing the OpenEmbedded tree itself. Overlays are very similar in structure to the OpenEmbedded tree, but are usually only sparsely populated. Non-sparsely poplulated overlays are actually more closely relatedd to separate development branches. Good convention would suggest to always name the overlay appropriately.

Below is an example of two overlays, three build directories, a setup-env script, and a local.conf where the developer has multiple build targets as well as multiple BitBake overlays.
<pre>
oe
|-- build-beagleboard
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-om-gta02
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-ts72xx
| |-- conf
| | `-- local.conf
| `-- tmp
|-- com.somecompany.dev
| |-- conf
| | `-- machine
| `-- packages
| |-- images
| | `-- console-image.bb
| `-- rxtx
| |-- files
| |-- rxtx-fixes-from-debian.patch
| `-- rxtx_2.1-7r2.bb
|-- org.openembedded.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- images
|-- org.openmoko.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- setup-env
</pre>
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02

unset BBPATH

case "${MACHINE}" in
"beagleboard" | "ts72xx" )
BBPATH="${OE_HOME}/com.somecompany.dev"
;;
"om-gta02")
BBPATH="${OE_HOME}/org.openmoko.dev"
;;
*)
echo -e "error: unsupported machine"
exit -1
;;
esac

export BBPATH=${BBPATH}:${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>

Note that the overlay-specific BBPATH entry ''precedes'' the default BBPATH entries.

<pre>
...
BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"
BBFILES += " ${OE_HOME}/org.openmoko.dev/packages/*/*.bb"

BBFILE_COLLECTIONS = "upstream local"
BBFILE_PATTERN_upstream = "${OE_HOME}/org.openembedded.dev"
BBFILE_PRIORITY_upstream = "0"
BBFILE_PATTERN_local = "${OE_HOME}/org.openmoko.dev"
BBFILE_PRIORITY_local = "1"
...
</pre>

In order for the overlay to be detected by BitBake, the above variables need to be defined. It is possible to have more than one overlay and each one should be given a different priority.

=== Useful BitBake Commands ===

<pre>
# list all of the tasks defined for a given package_name
bitbake -c listtasks <package_name>

# clean the work directory for a specific package
bitbake -c clean <package_name>

# build a specific recipe
bitbake -b <path/to/some/recipe.bb>
</pre>

[[Category:Application Developer]]
[[Category:System Developers]]

OpenEmbedded

2009-02-10T18:45:13Z

Cfriedt: /* Broken Builds and Bug Reporting */

{{Languages|OpenEmbedded}}

Openmoko, our distribution, is built using OpenEmbedded. OpenEmbedded will:

* Generate (cross-compile) software packages for multiple embedded targets.
* Handle different hardware architectures, and support multiple releases across those architectures.

For more information please see the [http://www.openembedded.org/ Open Embedded] website.

== Building the OpenMoko Distribution with OpenEmbedded ==

'''Note:''' If you are an application developer, you probably do not want to build OpenEmbedded from scratch. For compiling simple applications with few library dependencies (including boot-loader and kernel), consider using our prebuilt [[Toolchain]]. For more complex applications with many library dependencies, download a prebuilt [[OpenEmbedded Torrent]] with your favourite [http://en.wikipedia.org/wiki/BitTorrent_client BitTorrent client].

Building OpenMoko from scratch is a time-, cpu- and diskspace-consuming process which should only be done if you are a system integrator and want to customize your OpenMoko distribution.

=== Simplified Instructions: MokoMakefile ===

For beginners who wish to customize their OpenMoko distribution, the facility called [[MokoMakefile]] simplifies building OpenEmbedded.

=== Quick Start: OpenEmbedded Torrent ===

If you are a system developer and would like to get up-to-speed as quickly as possible, then download an [[OpenEmbedded Torrent]].

== From Scratch: OpenEmbedded ==

Beginner OpenMoko developers who would prefer to have full control over their OpenEmbedded build environment should follow the instructions below.

=== Preparations ===

Several prerequisite software components are necessary in order to have a fully functional OpenEmbedded build environment. However, setup and installation varies depending on the operating system installed on your workstation. The [http://wiki.openembedded.net/index.php OpenEmbedded Wiki] provides [http://wiki.openembedded.net/index.php/OEandYourDistro setup instructions] for FreeBSD, Mac OS X, and most major Linux distributions, of course.

For OpenEmbedded installation instructions please refer to [http://wiki.openembedded.net/index.php/OEandYourDistro OEandYourDistro].

=== ${OE_HOME} ===

Assuming that you have installed all prerequisite software, you are now ready to create a directory for all of your OpenEmbedded (OE) related work. We will refer to OE_HOME in a generic way, but for argument's sake, assume that it is equal to ${HOME}/oe. You should expect ${OE_HOME} to grow tremendously in size, up to approximately 8GB or larger in some cases. Also be aware, that a full OE build could require several hours of constant building, which may inhibit the performance of your computer while performing other tasks. Replace ${HOME}/oe with your preferred location.

For Bash users:
export OE_HOME=${HOME}/oe

For Tcsh users:
setenv OE_HOME ${HOME}/oe

Next, run 'mkdir -p ${OE_HOME}' to create the directory.

=== Synchronizing OpenEmbedded With Git ===

Just like any tree, OpenEmbedded has several branches. In this case they are called 'development branches'. Some noteworthy ones include org.openembedded.dev (the default) and org.openembedded.stable .

To syncronize the OpenEmbedded tree, run
<pre>
git clone git://git.openembedded.net/openembedded ${OE_HOME}/org.openembedded.dev
</pre>

Note that last argument could be any directory name (git will create the directory if it doesn't exist). Sticking to 'good convention', the directory name was chosen to reflect the default development branch, org.openembedded.dev . See the [http://wiki.openembedded.net/index.php/GitPhraseBook OE GitPhraseBook] for more info on checking out different branches.

To update the tree, run
<pre>
cd ${OE_HOME}/org.openembedded.dev
git pull
</pre>

For further information on Git, see [http://git-scm.com The Git Homepage].

Also, please explore the directory structure of the OpenEmbedded build tree and take a moment to open and read one of the each type of BitBake file. This helps one to become familiar with recipe syntax and the inheritance system. Of particular note, please read the file 'local.conf.sample'.
<pre>
org.openembedded.dev
|-- classes
| |-- rootfs_ipk.bbclass
| `-- xorg-module.bbclass
|-- conf
| `-- local.conf.sample
| |-- distro
| | `-- angstrom-2008.1.conf
| |-- machine
| | |-- om-gta01.conf
| | `-- om-gta02.conf
`-- packages
|-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- images
|-- console-image.bb
|-- fso-console-image.bb
|-- fso-image.bb
|-- openmoko-image.bb
|-- opie-image.bb
`-- x11-image.bb
</pre>
=== Build Configuration ===

If you explored local.conf.example, then you would be aware that there are some very important variables to be set like MACHINE, DISTRO, and BBFILES, among many others. This is done in a configuration file (local.conf) inside the build directory.

'''Note:''' Using BitBake and OE for cross-compilation require that each target-distro combination is built in a separate directory, so that no version collisions occur. Concurrent builds may safely share the same DL_DIR though. This would suggest that a safe name for build directories is of the form ${OE_HOME}/build-${MACHINE}-${DISTRO}. Of course, if you don't plan on building for more than one machine-distro combination, then the naming of this directory is arbitrary. For the purpose of this example, we will use the convention ${OE_HOME}/build-${MACHINE} .

Now, create the 'local.conf' configuration file. Notice that the CACHE and TMPDIR variables are neatly kept within the build directory while the DL_DIR variable is outside of the build directory, so that concurrent builds may reuse the same source packages.
<pre>
OE_HOME ?= "${HOME}/oe"

MACHINE = "om-gta02"
DISTRO = "angstrom-2008.1"

DL_DIR = "${OE_HOME}/downloads"

BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"

BBMASK = ""

TMPDIR = "${OE_HOME}/build-${MACHINE}/tmp"
CACHE = "${TMPDIR}/cache"

IMAGE_FSTYPES = "jffs2 tar.gz"

ENABLE_BINARY_LOCALE_GENERATION = "0"
</pre>

The BBFILES variable is also of prime importance! It tells bitbake where to locate all available recipes for a build. The OpenEmbedded build environment is almost completely ready to go, with just one more minor step left.

=== Build Environment ===

For quick and easy initialization of the OpenEmbedded build environment, it is often suggested that the developer create a 'setup-env' script to source from the command line. This script can be called to initialize the most important of environment variables. Below is a very basic example of a setup-env script.

setup-env for Bash users:
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02
export BBPATH=${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
setup-env for Tcsh users:
<pre>
[[ -z ${OE_HOME} ]] && setenv OE_HOME ${HOME}/oe
[[ -z ${MACHINE} ]] && setenv MACHINE om-gta02
setenv BBPATH ${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
To invoke the setup-env script in bash, run 'source setup-env'. In tcsh, run '. setup-env'.

=== Testing the OE Build Environment ===

That's it! Now you should be prepared to bake your first BitBake recipe.

bitbake helloworld

=== Building an Image ===

There are several full filesystem images which can be built directly with OpenEmbedded using a single command. These include openmoko-image, fso-image, and so on. The image definitions can be found under ${OE_HOME}/org.openembedded.dev/packages/images

A good place to start is with

bitbake fso-image

That concludes this introduction to BitBake and OpenEmbedded. Good luck!

=== Other References ===

Please feel free to refer to other online sources of information for [http://bitbake.berlios.de BitBake], [http://www.openembedded.org OpenEmbedded], and the [http://www.angstrom-distribution.org Angstrom Distribution] to name a few.

== Broken Builds and Bug Reporting ==

Using the org.openembedded.dev branch can often result in broken builds. For that reason, it is usually a good idea to limit synchronizing with the repository only after successfully building an image. Some may even want to archive the tree and build directory after an image is built.

Now in the case that an image does not successfully build, it is not always necessarily a bug or a new bug. The problem might have to do with some conflicting software on the workstation, and it could be a bug that is already know and being fixed.

Below are a few useful steps to follow when a build does not successfully complete:

* Identify the package that failed to build
** Find a line near the bottom of your output that matches "ERROR: ... failed" or "NOTE: ... failed". The name of the package should be contained in the '...'
* If there is a similar, more stable version in ${OE_HOME}/org.openembedded.dev/packages, then try to use that instead
** bitbake -c clean package_name && bitbake -b ${OE_HOME}/org.openembedded.dev/packages/somepackage/somepackage_0.1.bb
* Read the BitBake log, as well as config.log if it exists
** Find the log file. There should be a line near the bottom of your output that matches "ERROR: see log in ...", where '...' contains the log file name. These are usually of the form log.do_compile.12345 or log.do_configure.12345, etc.
* Try to identify the root cause of the error
** In many cases, if one examines log.do_configure, only the error is reported, but not the cause of the error
** Most packages that build with autotools will also have a config.log file that contains the exact cause of the error
* If you can fix the error, and the error is local to your workstation, and not really a bug, then fix the error yourself.
* Otherwise, check the [http://bugs.openembedded.net OpenEmbedded Bugzilla] to see if the error is known.
* If a solution is already available, then try it out. If you can fix the error, then do so. If your solution is correct, please post all relevent patches to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

=== Where to Report Bugs ===

Authentic bugs should be reported to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

== Tips & Tricks ==

=== Screen is Your Friend ===

If you happen to be building all of your packages remotely on a server, using an ssh session, the session might occasionally be interrupted and the connection could be terminated. If in the process of building an image with bitbake, this means that the build process will terminate as well.

In order to ensure that a build continues in the presence of communication failures, it is advisable to use the [http://www.gnu.org/software/screen GNU Screen] utility. Screen is also very useful when performing several concurrent OpenEmbedded builds for different machine-distro combinations.

Screen installation varies with your OS and distribution.

=== BitBake Overlays ===

Bitbake overlays are useful for OpenEmbedded developers to eliminate bugs or package software without disturbiing the OpenEmbedded tree itself. Overlays are very similar in structure to the OpenEmbedded tree, but are usually only sparsely populated. Non-sparsely poplulated overlays are actually more closely relatedd to separate development branches. Good convention would suggest to always name the overlay appropriately.

Below is an example of two overlays, three build directories, a setup-env script, and a local.conf where the developer has multiple build targets as well as multiple BitBake overlays.
<pre>
oe
|-- build-beagleboard
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-om-gta02
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-ts72xx
| |-- conf
| | `-- local.conf
| `-- tmp
|-- com.somecompany.dev
| |-- conf
| | `-- machine
| `-- packages
| |-- images
| | `-- console-image.bb
| `-- rxtx
| |-- files
| |-- rxtx-fixes-from-debian.patch
| `-- rxtx_2.1-7r2.bb
|-- org.openembedded.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- images
|-- org.openmoko.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- setup-env
</pre>
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02

unset BBPATH

case "${MACHINE}" in
"beagleboard" | "ts72xx" )
BBPATH="${OE_HOME}/com.somecompany.dev"
;;
"om-gta02")
BBPATH="${OE_HOME}/org.openmoko.dev"
;;
*)
echo -e "error: unsupported machine"
exit -1
;;
esac

export BBPATH=${BBPATH}:${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>

Note that the overlay-specific BBPATH entry ''precedes'' the default BBPATH entries.

<pre>
...
BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"
BBFILES += " ${OE_HOME}/org.openmoko.dev/packages/*/*.bb"

BBFILE_COLLECTIONS = "upstream local"
BBFILE_PATTERN_upstream = "${OE_HOME}/org.openembedded.dev"
BBFILE_PRIORITY_upstream = "0"
BBFILE_PATTERN_local = "${OE_HOME}/org.openmoko.dev"
BBFILE_PRIORITY_local = "1"
...
</pre>

In order for the overlay to be detected by BitBake, the above variables need to be defined. It is possible to have more than one overlay and each one should be given a different priority.

=== Useful BitBake Commands ===

<pre>
# list all of the tasks defined for a given package_name
bitbake -c listtasks <package_name>

# clean the work directory for a specific package
bitbake -c clean <package_name>

# build a specific recipe
bitbake -b <path/to/some/recipe.bb>
</pre>

[[Category:Application Developer]]
[[Category:System Developers]]

OpenEmbedded

2009-02-10T18:41:20Z

Cfriedt: /* Quick Start: OpenEmbedded Torrent */

{{Languages|OpenEmbedded}}

Openmoko, our distribution, is built using OpenEmbedded. OpenEmbedded will:

* Generate (cross-compile) software packages for multiple embedded targets.
* Handle different hardware architectures, and support multiple releases across those architectures.

For more information please see the [http://www.openembedded.org/ Open Embedded] website.

== Building the OpenMoko Distribution with OpenEmbedded ==

'''Note:''' If you are an application developer, you probably do not want to build OpenEmbedded from scratch. For compiling simple applications with few library dependencies (including boot-loader and kernel), consider using our prebuilt [[Toolchain]]. For more complex applications with many library dependencies, download a prebuilt [[OpenEmbedded Torrent]] with your favourite [http://en.wikipedia.org/wiki/BitTorrent_client BitTorrent client].

Building OpenMoko from scratch is a time-, cpu- and diskspace-consuming process which should only be done if you are a system integrator and want to customize your OpenMoko distribution.

=== Simplified Instructions: MokoMakefile ===

For beginners who wish to customize their OpenMoko distribution, the facility called [[MokoMakefile]] simplifies building OpenEmbedded.

=== Quick Start: OpenEmbedded Torrent ===

If you are a system developer and would like to get up-to-speed as quickly as possible, then download an [[OpenEmbedded Torrent]].

== From Scratch: OpenEmbedded ==

Beginner OpenMoko developers who would prefer to have full control over their OpenEmbedded build environment should follow the instructions below.

=== Preparations ===

Several prerequisite software components are necessary in order to have a fully functional OpenEmbedded build environment. However, setup and installation varies depending on the operating system installed on your workstation. The [http://wiki.openembedded.net/index.php OpenEmbedded Wiki] provides [http://wiki.openembedded.net/index.php/OEandYourDistro setup instructions] for FreeBSD, Mac OS X, and most major Linux distributions, of course.

For OpenEmbedded installation instructions please refer to [http://wiki.openembedded.net/index.php/OEandYourDistro OEandYourDistro].

=== ${OE_HOME} ===

Assuming that you have installed all prerequisite software, you are now ready to create a directory for all of your OpenEmbedded (OE) related work. We will refer to OE_HOME in a generic way, but for argument's sake, assume that it is equal to ${HOME}/oe. You should expect ${OE_HOME} to grow tremendously in size, up to approximately 8GB or larger in some cases. Also be aware, that a full OE build could require several hours of constant building, which may inhibit the performance of your computer while performing other tasks. Replace ${HOME}/oe with your preferred location.

For Bash users:
export OE_HOME=${HOME}/oe

For Tcsh users:
setenv OE_HOME ${HOME}/oe

Next, run 'mkdir -p ${OE_HOME}' to create the directory.

=== Synchronizing OpenEmbedded With Git ===

Just like any tree, OpenEmbedded has several branches. In this case they are called 'development branches'. Some noteworthy ones include org.openembedded.dev (the default) and org.openembedded.stable .

To syncronize the OpenEmbedded tree, run
<pre>
git clone git://git.openembedded.net/openembedded ${OE_HOME}/org.openembedded.dev
</pre>

Note that last argument could be any directory name (git will create the directory if it doesn't exist). Sticking to 'good convention', the directory name was chosen to reflect the default development branch, org.openembedded.dev . See the [http://wiki.openembedded.net/index.php/GitPhraseBook OE GitPhraseBook] for more info on checking out different branches.

To update the tree, run
<pre>
cd ${OE_HOME}/org.openembedded.dev
git pull
</pre>

For further information on Git, see [http://git-scm.com The Git Homepage].

Also, please explore the directory structure of the OpenEmbedded build tree and take a moment to open and read one of the each type of BitBake file. This helps one to become familiar with recipe syntax and the inheritance system. Of particular note, please read the file 'local.conf.sample'.
<pre>
org.openembedded.dev
|-- classes
| |-- rootfs_ipk.bbclass
| `-- xorg-module.bbclass
|-- conf
| `-- local.conf.sample
| |-- distro
| | `-- angstrom-2008.1.conf
| |-- machine
| | |-- om-gta01.conf
| | `-- om-gta02.conf
`-- packages
|-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- images
|-- console-image.bb
|-- fso-console-image.bb
|-- fso-image.bb
|-- openmoko-image.bb
|-- opie-image.bb
`-- x11-image.bb
</pre>
=== Build Configuration ===

If you explored local.conf.example, then you would be aware that there are some very important variables to be set like MACHINE, DISTRO, and BBFILES, among many others. This is done in a configuration file (local.conf) inside the build directory.

'''Note:''' Using BitBake and OE for cross-compilation require that each target-distro combination is built in a separate directory, so that no version collisions occur. Concurrent builds may safely share the same DL_DIR though. This would suggest that a safe name for build directories is of the form ${OE_HOME}/build-${MACHINE}-${DISTRO}. Of course, if you don't plan on building for more than one machine-distro combination, then the naming of this directory is arbitrary. For the purpose of this example, we will use the convention ${OE_HOME}/build-${MACHINE} .

Now, create the 'local.conf' configuration file. Notice that the CACHE and TMPDIR variables are neatly kept within the build directory while the DL_DIR variable is outside of the build directory, so that concurrent builds may reuse the same source packages.
<pre>
OE_HOME ?= "${HOME}/oe"

MACHINE = "om-gta02"
DISTRO = "angstrom-2008.1"

DL_DIR = "${OE_HOME}/downloads"

BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"

BBMASK = ""

TMPDIR = "${OE_HOME}/build-${MACHINE}/tmp"
CACHE = "${TMPDIR}/cache"

IMAGE_FSTYPES = "jffs2 tar.gz"

ENABLE_BINARY_LOCALE_GENERATION = "0"
</pre>

The BBFILES variable is also of prime importance! It tells bitbake where to locate all available recipes for a build. The OpenEmbedded build environment is almost completely ready to go, with just one more minor step left.

=== Build Environment ===

For quick and easy initialization of the OpenEmbedded build environment, it is often suggested that the developer create a 'setup-env' script to source from the command line. This script can be called to initialize the most important of environment variables. Below is a very basic example of a setup-env script.

setup-env for Bash users:
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02
export BBPATH=${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
setup-env for Tcsh users:
<pre>
[[ -z ${OE_HOME} ]] && setenv OE_HOME ${HOME}/oe
[[ -z ${MACHINE} ]] && setenv MACHINE om-gta02
setenv BBPATH ${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
To invoke the setup-env script in bash, run 'source setup-env'. In tcsh, run '. setup-env'.

=== Testing the OE Build Environment ===

That's it! Now you should be prepared to bake your first BitBake recipe.

bitbake helloworld

=== Building an Image ===

There are several full filesystem images which can be built directly with OpenEmbedded using a single command. These include openmoko-image, fso-image, and so on. The image definitions can be found under ${OE_HOME}/org.openembedded.dev/packages/images

A good place to start is with

bitbake fso-image

That concludes this introduction to BitBake and OpenEmbedded. Good luck!

=== Other References ===

Please feel free to refer to other online sources of information for [http://bitbake.berlios.de BitBake], [http://www.openembedded.org OpenEmbedded], and the [http://www.angstrom-distribution.org Angstrom Distribution] to name a few.

== Broken Builds and Bug Reporting ==

Using the org.openembedded.dev branch can often result in broken builds. For that reason, it is usually a good idea to limit synchronizing with the repository only after successfully building an image. Some may even want to archive the tree and build directory after an image is built.

Now in the case that an image does not successfully build, it is not always necessarily a bug or a new bug. The problem might have to do with some conflicting software on the workstation, and it could be a bug that is already know and being fixed.

Below are a few useful steps to follow when a build does not successfully complete:

* Identify the package that failed to build and read the bitbake log, as well as config.log if it exists
** Find a line near the bottom of your output that matches "ERROR: ... failed" or "NOTE: ... failed". The name of the package should be contained in the '...'
** Find the log file. There should be a line near the bottom of your output that matches "ERROR: see log in ...", where '...' contains the log file name. These are usually of the form log.do_compile.12345 or log.do_configure.12345, etc.
* Try to identify the root cause of the error
** In many cases, if one examines log.do_configure, only the error is reported, but not the cause of the error
** Most packages that build with autotools will also have a config.log file that contains the exact cause of the error
* If you can fix the error, and the error is local to your workstation, and not really a bug, then fix the error yourself.
* Otherwise, check the [http://bugs.openembedded.net OpenEmbedded Bugzilla] to see if the error is known.
* If a solution is already available, then try it out. If you can fix the error, then do so. If your solution is correct, please post all relevent patches to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

=== Where to Report Bugs ===

Authentic bugs should be reported to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

== Tips & Tricks ==

=== Screen is Your Friend ===

If you happen to be building all of your packages remotely on a server, using an ssh session, the session might occasionally be interrupted and the connection could be terminated. If in the process of building an image with bitbake, this means that the build process will terminate as well.

In order to ensure that a build continues in the presence of communication failures, it is advisable to use the [http://www.gnu.org/software/screen GNU Screen] utility. Screen is also very useful when performing several concurrent OpenEmbedded builds for different machine-distro combinations.

Screen installation varies with your OS and distribution.

=== BitBake Overlays ===

Bitbake overlays are useful for OpenEmbedded developers to eliminate bugs or package software without disturbiing the OpenEmbedded tree itself. Overlays are very similar in structure to the OpenEmbedded tree, but are usually only sparsely populated. Non-sparsely poplulated overlays are actually more closely relatedd to separate development branches. Good convention would suggest to always name the overlay appropriately.

Below is an example of two overlays, three build directories, a setup-env script, and a local.conf where the developer has multiple build targets as well as multiple BitBake overlays.
<pre>
oe
|-- build-beagleboard
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-om-gta02
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-ts72xx
| |-- conf
| | `-- local.conf
| `-- tmp
|-- com.somecompany.dev
| |-- conf
| | `-- machine
| `-- packages
| |-- images
| | `-- console-image.bb
| `-- rxtx
| |-- files
| |-- rxtx-fixes-from-debian.patch
| `-- rxtx_2.1-7r2.bb
|-- org.openembedded.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- images
|-- org.openmoko.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- setup-env
</pre>
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02

unset BBPATH

case "${MACHINE}" in
"beagleboard" | "ts72xx" )
BBPATH="${OE_HOME}/com.somecompany.dev"
;;
"om-gta02")
BBPATH="${OE_HOME}/org.openmoko.dev"
;;
*)
echo -e "error: unsupported machine"
exit -1
;;
esac

export BBPATH=${BBPATH}:${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>

Note that the overlay-specific BBPATH entry ''precedes'' the default BBPATH entries.

<pre>
...
BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"
BBFILES += " ${OE_HOME}/org.openmoko.dev/packages/*/*.bb"

BBFILE_COLLECTIONS = "upstream local"
BBFILE_PATTERN_upstream = "${OE_HOME}/org.openembedded.dev"
BBFILE_PRIORITY_upstream = "0"
BBFILE_PATTERN_local = "${OE_HOME}/org.openmoko.dev"
BBFILE_PRIORITY_local = "1"
...
</pre>

In order for the overlay to be detected by BitBake, the above variables need to be defined. It is possible to have more than one overlay and each one should be given a different priority.

=== Useful BitBake Commands ===

<pre>
# list all of the tasks defined for a given package_name
bitbake -c listtasks <package_name>

# clean the work directory for a specific package
bitbake -c clean <package_name>

# build a specific recipe
bitbake -b <path/to/some/recipe.bb>
</pre>

[[Category:Application Developer]]
[[Category:System Developers]]

OpenEmbedded

2009-02-10T18:40:21Z

Cfriedt: /* Simplified Instructions: MokoMakefile */

{{Languages|OpenEmbedded}}

Openmoko, our distribution, is built using OpenEmbedded. OpenEmbedded will:

* Generate (cross-compile) software packages for multiple embedded targets.
* Handle different hardware architectures, and support multiple releases across those architectures.

For more information please see the [http://www.openembedded.org/ Open Embedded] website.

== Building the OpenMoko Distribution with OpenEmbedded ==

'''Note:''' If you are an application developer, you probably do not want to build OpenEmbedded from scratch. For compiling simple applications with few library dependencies (including boot-loader and kernel), consider using our prebuilt [[Toolchain]]. For more complex applications with many library dependencies, download a prebuilt [[OpenEmbedded Torrent]] with your favourite [http://en.wikipedia.org/wiki/BitTorrent_client BitTorrent client].

Building OpenMoko from scratch is a time-, cpu- and diskspace-consuming process which should only be done if you are a system integrator and want to customize your OpenMoko distribution.

=== Simplified Instructions: MokoMakefile ===

For beginners who wish to customize their OpenMoko distribution, the facility called [[MokoMakefile]] simplifies building OpenEmbedded.

== Quick Start: OpenEmbedded Torrent ==

If you are a system developer and would like to get up-to-speed as quickly as possible, then download an [[OpenEmbedded Torrent]].

== From Scratch: OpenEmbedded ==

Beginner OpenMoko developers who would prefer to have full control over their OpenEmbedded build environment should follow the instructions below.

=== Preparations ===

Several prerequisite software components are necessary in order to have a fully functional OpenEmbedded build environment. However, setup and installation varies depending on the operating system installed on your workstation. The [http://wiki.openembedded.net/index.php OpenEmbedded Wiki] provides [http://wiki.openembedded.net/index.php/OEandYourDistro setup instructions] for FreeBSD, Mac OS X, and most major Linux distributions, of course.

For OpenEmbedded installation instructions please refer to [http://wiki.openembedded.net/index.php/OEandYourDistro OEandYourDistro].

=== ${OE_HOME} ===

Assuming that you have installed all prerequisite software, you are now ready to create a directory for all of your OpenEmbedded (OE) related work. We will refer to OE_HOME in a generic way, but for argument's sake, assume that it is equal to ${HOME}/oe. You should expect ${OE_HOME} to grow tremendously in size, up to approximately 8GB or larger in some cases. Also be aware, that a full OE build could require several hours of constant building, which may inhibit the performance of your computer while performing other tasks. Replace ${HOME}/oe with your preferred location.

For Bash users:
export OE_HOME=${HOME}/oe

For Tcsh users:
setenv OE_HOME ${HOME}/oe

Next, run 'mkdir -p ${OE_HOME}' to create the directory.

=== Synchronizing OpenEmbedded With Git ===

Just like any tree, OpenEmbedded has several branches. In this case they are called 'development branches'. Some noteworthy ones include org.openembedded.dev (the default) and org.openembedded.stable .

To syncronize the OpenEmbedded tree, run
<pre>
git clone git://git.openembedded.net/openembedded ${OE_HOME}/org.openembedded.dev
</pre>

Note that last argument could be any directory name (git will create the directory if it doesn't exist). Sticking to 'good convention', the directory name was chosen to reflect the default development branch, org.openembedded.dev . See the [http://wiki.openembedded.net/index.php/GitPhraseBook OE GitPhraseBook] for more info on checking out different branches.

To update the tree, run
<pre>
cd ${OE_HOME}/org.openembedded.dev
git pull
</pre>

For further information on Git, see [http://git-scm.com The Git Homepage].

Also, please explore the directory structure of the OpenEmbedded build tree and take a moment to open and read one of the each type of BitBake file. This helps one to become familiar with recipe syntax and the inheritance system. Of particular note, please read the file 'local.conf.sample'.
<pre>
org.openembedded.dev
|-- classes
| |-- rootfs_ipk.bbclass
| `-- xorg-module.bbclass
|-- conf
| `-- local.conf.sample
| |-- distro
| | `-- angstrom-2008.1.conf
| |-- machine
| | |-- om-gta01.conf
| | `-- om-gta02.conf
`-- packages
|-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- images
|-- console-image.bb
|-- fso-console-image.bb
|-- fso-image.bb
|-- openmoko-image.bb
|-- opie-image.bb
`-- x11-image.bb
</pre>
=== Build Configuration ===

If you explored local.conf.example, then you would be aware that there are some very important variables to be set like MACHINE, DISTRO, and BBFILES, among many others. This is done in a configuration file (local.conf) inside the build directory.

'''Note:''' Using BitBake and OE for cross-compilation require that each target-distro combination is built in a separate directory, so that no version collisions occur. Concurrent builds may safely share the same DL_DIR though. This would suggest that a safe name for build directories is of the form ${OE_HOME}/build-${MACHINE}-${DISTRO}. Of course, if you don't plan on building for more than one machine-distro combination, then the naming of this directory is arbitrary. For the purpose of this example, we will use the convention ${OE_HOME}/build-${MACHINE} .

Now, create the 'local.conf' configuration file. Notice that the CACHE and TMPDIR variables are neatly kept within the build directory while the DL_DIR variable is outside of the build directory, so that concurrent builds may reuse the same source packages.
<pre>
OE_HOME ?= "${HOME}/oe"

MACHINE = "om-gta02"
DISTRO = "angstrom-2008.1"

DL_DIR = "${OE_HOME}/downloads"

BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"

BBMASK = ""

TMPDIR = "${OE_HOME}/build-${MACHINE}/tmp"
CACHE = "${TMPDIR}/cache"

IMAGE_FSTYPES = "jffs2 tar.gz"

ENABLE_BINARY_LOCALE_GENERATION = "0"
</pre>

The BBFILES variable is also of prime importance! It tells bitbake where to locate all available recipes for a build. The OpenEmbedded build environment is almost completely ready to go, with just one more minor step left.

=== Build Environment ===

For quick and easy initialization of the OpenEmbedded build environment, it is often suggested that the developer create a 'setup-env' script to source from the command line. This script can be called to initialize the most important of environment variables. Below is a very basic example of a setup-env script.

setup-env for Bash users:
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02
export BBPATH=${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
setup-env for Tcsh users:
<pre>
[[ -z ${OE_HOME} ]] && setenv OE_HOME ${HOME}/oe
[[ -z ${MACHINE} ]] && setenv MACHINE om-gta02
setenv BBPATH ${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
To invoke the setup-env script in bash, run 'source setup-env'. In tcsh, run '. setup-env'.

=== Testing the OE Build Environment ===

That's it! Now you should be prepared to bake your first BitBake recipe.

bitbake helloworld

=== Building an Image ===

There are several full filesystem images which can be built directly with OpenEmbedded using a single command. These include openmoko-image, fso-image, and so on. The image definitions can be found under ${OE_HOME}/org.openembedded.dev/packages/images

A good place to start is with

bitbake fso-image

That concludes this introduction to BitBake and OpenEmbedded. Good luck!

=== Other References ===

Please feel free to refer to other online sources of information for [http://bitbake.berlios.de BitBake], [http://www.openembedded.org OpenEmbedded], and the [http://www.angstrom-distribution.org Angstrom Distribution] to name a few.

== Broken Builds and Bug Reporting ==

Using the org.openembedded.dev branch can often result in broken builds. For that reason, it is usually a good idea to limit synchronizing with the repository only after successfully building an image. Some may even want to archive the tree and build directory after an image is built.

Now in the case that an image does not successfully build, it is not always necessarily a bug or a new bug. The problem might have to do with some conflicting software on the workstation, and it could be a bug that is already know and being fixed.

Below are a few useful steps to follow when a build does not successfully complete:

* Identify the package that failed to build and read the bitbake log, as well as config.log if it exists
** Find a line near the bottom of your output that matches "ERROR: ... failed" or "NOTE: ... failed". The name of the package should be contained in the '...'
** Find the log file. There should be a line near the bottom of your output that matches "ERROR: see log in ...", where '...' contains the log file name. These are usually of the form log.do_compile.12345 or log.do_configure.12345, etc.
* Try to identify the root cause of the error
** In many cases, if one examines log.do_configure, only the error is reported, but not the cause of the error
** Most packages that build with autotools will also have a config.log file that contains the exact cause of the error
* If you can fix the error, and the error is local to your workstation, and not really a bug, then fix the error yourself.
* Otherwise, check the [http://bugs.openembedded.net OpenEmbedded Bugzilla] to see if the error is known.
* If a solution is already available, then try it out. If you can fix the error, then do so. If your solution is correct, please post all relevent patches to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

=== Where to Report Bugs ===

Authentic bugs should be reported to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

== Tips & Tricks ==

=== Screen is Your Friend ===

If you happen to be building all of your packages remotely on a server, using an ssh session, the session might occasionally be interrupted and the connection could be terminated. If in the process of building an image with bitbake, this means that the build process will terminate as well.

In order to ensure that a build continues in the presence of communication failures, it is advisable to use the [http://www.gnu.org/software/screen GNU Screen] utility. Screen is also very useful when performing several concurrent OpenEmbedded builds for different machine-distro combinations.

Screen installation varies with your OS and distribution.

=== BitBake Overlays ===

Bitbake overlays are useful for OpenEmbedded developers to eliminate bugs or package software without disturbiing the OpenEmbedded tree itself. Overlays are very similar in structure to the OpenEmbedded tree, but are usually only sparsely populated. Non-sparsely poplulated overlays are actually more closely relatedd to separate development branches. Good convention would suggest to always name the overlay appropriately.

Below is an example of two overlays, three build directories, a setup-env script, and a local.conf where the developer has multiple build targets as well as multiple BitBake overlays.
<pre>
oe
|-- build-beagleboard
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-om-gta02
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-ts72xx
| |-- conf
| | `-- local.conf
| `-- tmp
|-- com.somecompany.dev
| |-- conf
| | `-- machine
| `-- packages
| |-- images
| | `-- console-image.bb
| `-- rxtx
| |-- files
| |-- rxtx-fixes-from-debian.patch
| `-- rxtx_2.1-7r2.bb
|-- org.openembedded.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- images
|-- org.openmoko.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- setup-env
</pre>
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02

unset BBPATH

case "${MACHINE}" in
"beagleboard" | "ts72xx" )
BBPATH="${OE_HOME}/com.somecompany.dev"
;;
"om-gta02")
BBPATH="${OE_HOME}/org.openmoko.dev"
;;
*)
echo -e "error: unsupported machine"
exit -1
;;
esac

export BBPATH=${BBPATH}:${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>

Note that the overlay-specific BBPATH entry ''precedes'' the default BBPATH entries.

<pre>
...
BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"
BBFILES += " ${OE_HOME}/org.openmoko.dev/packages/*/*.bb"

BBFILE_COLLECTIONS = "upstream local"
BBFILE_PATTERN_upstream = "${OE_HOME}/org.openembedded.dev"
BBFILE_PRIORITY_upstream = "0"
BBFILE_PATTERN_local = "${OE_HOME}/org.openmoko.dev"
BBFILE_PRIORITY_local = "1"
...
</pre>

In order for the overlay to be detected by BitBake, the above variables need to be defined. It is possible to have more than one overlay and each one should be given a different priority.

=== Useful BitBake Commands ===

<pre>
# list all of the tasks defined for a given package_name
bitbake -c listtasks <package_name>

# clean the work directory for a specific package
bitbake -c clean <package_name>

# build a specific recipe
bitbake -b <path/to/some/recipe.bb>
</pre>

[[Category:Application Developer]]
[[Category:System Developers]]

OpenEmbedded

2009-02-10T18:38:25Z

Cfriedt: /* Detailed Instructions: OpenEmbedded */

{{Languages|OpenEmbedded}}

Openmoko, our distribution, is built using OpenEmbedded. OpenEmbedded will:

* Generate (cross-compile) software packages for multiple embedded targets.
* Handle different hardware architectures, and support multiple releases across those architectures.

For more information please see the [http://www.openembedded.org/ Open Embedded] website.

== Building the OpenMoko Distribution with OpenEmbedded ==

'''Note:''' If you are an application developer, you probably do not want to build OpenEmbedded from scratch. For compiling simple applications with few library dependencies (including boot-loader and kernel), consider using our prebuilt [[Toolchain]]. For more complex applications with many library dependencies, download a prebuilt [[OpenEmbedded Torrent]] with your favourite [http://en.wikipedia.org/wiki/BitTorrent_client BitTorrent client].

Building OpenMoko from scratch is a time-, cpu- and diskspace-consuming process which should only be done if you are a system integrator and want to customize your OpenMoko distribution.

== Simplified Instructions: MokoMakefile ==

For beginners who wish to customize their OpenMoko distribution, the facility called [[MokoMakefile]] simplifies building OpenEmbedded.

== Quick Start: OpenEmbedded Torrent ==

If you are a system developer and would like to get up-to-speed as quickly as possible, then download an [[OpenEmbedded Torrent]].

== From Scratch: OpenEmbedded ==

Beginner OpenMoko developers who would prefer to have full control over their OpenEmbedded build environment should follow the instructions below.

=== Preparations ===

Several prerequisite software components are necessary in order to have a fully functional OpenEmbedded build environment. However, setup and installation varies depending on the operating system installed on your workstation. The [http://wiki.openembedded.net/index.php OpenEmbedded Wiki] provides [http://wiki.openembedded.net/index.php/OEandYourDistro setup instructions] for FreeBSD, Mac OS X, and most major Linux distributions, of course.

For OpenEmbedded installation instructions please refer to [http://wiki.openembedded.net/index.php/OEandYourDistro OEandYourDistro].

=== ${OE_HOME} ===

Assuming that you have installed all prerequisite software, you are now ready to create a directory for all of your OpenEmbedded (OE) related work. We will refer to OE_HOME in a generic way, but for argument's sake, assume that it is equal to ${HOME}/oe. You should expect ${OE_HOME} to grow tremendously in size, up to approximately 8GB or larger in some cases. Also be aware, that a full OE build could require several hours of constant building, which may inhibit the performance of your computer while performing other tasks. Replace ${HOME}/oe with your preferred location.

For Bash users:
export OE_HOME=${HOME}/oe

For Tcsh users:
setenv OE_HOME ${HOME}/oe

Next, run 'mkdir -p ${OE_HOME}' to create the directory.

=== Synchronizing OpenEmbedded With Git ===

Just like any tree, OpenEmbedded has several branches. In this case they are called 'development branches'. Some noteworthy ones include org.openembedded.dev (the default) and org.openembedded.stable .

To syncronize the OpenEmbedded tree, run
<pre>
git clone git://git.openembedded.net/openembedded ${OE_HOME}/org.openembedded.dev
</pre>

Note that last argument could be any directory name (git will create the directory if it doesn't exist). Sticking to 'good convention', the directory name was chosen to reflect the default development branch, org.openembedded.dev . See the [http://wiki.openembedded.net/index.php/GitPhraseBook OE GitPhraseBook] for more info on checking out different branches.

To update the tree, run
<pre>
cd ${OE_HOME}/org.openembedded.dev
git pull
</pre>

For further information on Git, see [http://git-scm.com The Git Homepage].

Also, please explore the directory structure of the OpenEmbedded build tree and take a moment to open and read one of the each type of BitBake file. This helps one to become familiar with recipe syntax and the inheritance system. Of particular note, please read the file 'local.conf.sample'.
<pre>
org.openembedded.dev
|-- classes
| |-- rootfs_ipk.bbclass
| `-- xorg-module.bbclass
|-- conf
| `-- local.conf.sample
| |-- distro
| | `-- angstrom-2008.1.conf
| |-- machine
| | |-- om-gta01.conf
| | `-- om-gta02.conf
`-- packages
|-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- images
|-- console-image.bb
|-- fso-console-image.bb
|-- fso-image.bb
|-- openmoko-image.bb
|-- opie-image.bb
`-- x11-image.bb
</pre>
=== Build Configuration ===

If you explored local.conf.example, then you would be aware that there are some very important variables to be set like MACHINE, DISTRO, and BBFILES, among many others. This is done in a configuration file (local.conf) inside the build directory.

'''Note:''' Using BitBake and OE for cross-compilation require that each target-distro combination is built in a separate directory, so that no version collisions occur. Concurrent builds may safely share the same DL_DIR though. This would suggest that a safe name for build directories is of the form ${OE_HOME}/build-${MACHINE}-${DISTRO}. Of course, if you don't plan on building for more than one machine-distro combination, then the naming of this directory is arbitrary. For the purpose of this example, we will use the convention ${OE_HOME}/build-${MACHINE} .

Now, create the 'local.conf' configuration file. Notice that the CACHE and TMPDIR variables are neatly kept within the build directory while the DL_DIR variable is outside of the build directory, so that concurrent builds may reuse the same source packages.
<pre>
OE_HOME ?= "${HOME}/oe"

MACHINE = "om-gta02"
DISTRO = "angstrom-2008.1"

DL_DIR = "${OE_HOME}/downloads"

BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"

BBMASK = ""

TMPDIR = "${OE_HOME}/build-${MACHINE}/tmp"
CACHE = "${TMPDIR}/cache"

IMAGE_FSTYPES = "jffs2 tar.gz"

ENABLE_BINARY_LOCALE_GENERATION = "0"
</pre>

The BBFILES variable is also of prime importance! It tells bitbake where to locate all available recipes for a build. The OpenEmbedded build environment is almost completely ready to go, with just one more minor step left.

=== Build Environment ===

For quick and easy initialization of the OpenEmbedded build environment, it is often suggested that the developer create a 'setup-env' script to source from the command line. This script can be called to initialize the most important of environment variables. Below is a very basic example of a setup-env script.

setup-env for Bash users:
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02
export BBPATH=${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
setup-env for Tcsh users:
<pre>
[[ -z ${OE_HOME} ]] && setenv OE_HOME ${HOME}/oe
[[ -z ${MACHINE} ]] && setenv MACHINE om-gta02
setenv BBPATH ${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
To invoke the setup-env script in bash, run 'source setup-env'. In tcsh, run '. setup-env'.

=== Testing the OE Build Environment ===

That's it! Now you should be prepared to bake your first BitBake recipe.

bitbake helloworld

=== Building an Image ===

There are several full filesystem images which can be built directly with OpenEmbedded using a single command. These include openmoko-image, fso-image, and so on. The image definitions can be found under ${OE_HOME}/org.openembedded.dev/packages/images

A good place to start is with

bitbake fso-image

That concludes this introduction to BitBake and OpenEmbedded. Good luck!

=== Other References ===

Please feel free to refer to other online sources of information for [http://bitbake.berlios.de BitBake], [http://www.openembedded.org OpenEmbedded], and the [http://www.angstrom-distribution.org Angstrom Distribution] to name a few.

== Broken Builds and Bug Reporting ==

Using the org.openembedded.dev branch can often result in broken builds. For that reason, it is usually a good idea to limit synchronizing with the repository only after successfully building an image. Some may even want to archive the tree and build directory after an image is built.

Now in the case that an image does not successfully build, it is not always necessarily a bug or a new bug. The problem might have to do with some conflicting software on the workstation, and it could be a bug that is already know and being fixed.

Below are a few useful steps to follow when a build does not successfully complete:

* Identify the package that failed to build and read the bitbake log, as well as config.log if it exists
** Find a line near the bottom of your output that matches "ERROR: ... failed" or "NOTE: ... failed". The name of the package should be contained in the '...'
** Find the log file. There should be a line near the bottom of your output that matches "ERROR: see log in ...", where '...' contains the log file name. These are usually of the form log.do_compile.12345 or log.do_configure.12345, etc.
* Try to identify the root cause of the error
** In many cases, if one examines log.do_configure, only the error is reported, but not the cause of the error
** Most packages that build with autotools will also have a config.log file that contains the exact cause of the error
* If you can fix the error, and the error is local to your workstation, and not really a bug, then fix the error yourself.
* Otherwise, check the [http://bugs.openembedded.net OpenEmbedded Bugzilla] to see if the error is known.
* If a solution is already available, then try it out. If you can fix the error, then do so. If your solution is correct, please post all relevent patches to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

=== Where to Report Bugs ===

Authentic bugs should be reported to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

== Tips & Tricks ==

=== Screen is Your Friend ===

If you happen to be building all of your packages remotely on a server, using an ssh session, the session might occasionally be interrupted and the connection could be terminated. If in the process of building an image with bitbake, this means that the build process will terminate as well.

In order to ensure that a build continues in the presence of communication failures, it is advisable to use the [http://www.gnu.org/software/screen GNU Screen] utility. Screen is also very useful when performing several concurrent OpenEmbedded builds for different machine-distro combinations.

Screen installation varies with your OS and distribution.

=== BitBake Overlays ===

Bitbake overlays are useful for OpenEmbedded developers to eliminate bugs or package software without disturbiing the OpenEmbedded tree itself. Overlays are very similar in structure to the OpenEmbedded tree, but are usually only sparsely populated. Non-sparsely poplulated overlays are actually more closely relatedd to separate development branches. Good convention would suggest to always name the overlay appropriately.

Below is an example of two overlays, three build directories, a setup-env script, and a local.conf where the developer has multiple build targets as well as multiple BitBake overlays.
<pre>
oe
|-- build-beagleboard
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-om-gta02
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-ts72xx
| |-- conf
| | `-- local.conf
| `-- tmp
|-- com.somecompany.dev
| |-- conf
| | `-- machine
| `-- packages
| |-- images
| | `-- console-image.bb
| `-- rxtx
| |-- files
| |-- rxtx-fixes-from-debian.patch
| `-- rxtx_2.1-7r2.bb
|-- org.openembedded.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- images
|-- org.openmoko.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- setup-env
</pre>
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02

unset BBPATH

case "${MACHINE}" in
"beagleboard" | "ts72xx" )
BBPATH="${OE_HOME}/com.somecompany.dev"
;;
"om-gta02")
BBPATH="${OE_HOME}/org.openmoko.dev"
;;
*)
echo -e "error: unsupported machine"
exit -1
;;
esac

export BBPATH=${BBPATH}:${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>

Note that the overlay-specific BBPATH entry ''precedes'' the default BBPATH entries.

<pre>
...
BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"
BBFILES += " ${OE_HOME}/org.openmoko.dev/packages/*/*.bb"

BBFILE_COLLECTIONS = "upstream local"
BBFILE_PATTERN_upstream = "${OE_HOME}/org.openembedded.dev"
BBFILE_PRIORITY_upstream = "0"
BBFILE_PATTERN_local = "${OE_HOME}/org.openmoko.dev"
BBFILE_PRIORITY_local = "1"
...
</pre>

In order for the overlay to be detected by BitBake, the above variables need to be defined. It is possible to have more than one overlay and each one should be given a different priority.

=== Useful BitBake Commands ===

<pre>
# list all of the tasks defined for a given package_name
bitbake -c listtasks <package_name>

# clean the work directory for a specific package
bitbake -c clean <package_name>

# build a specific recipe
bitbake -b <path/to/some/recipe.bb>
</pre>

[[Category:Application Developer]]
[[Category:System Developers]]

OpenEmbedded Torrent

2009-02-10T18:35:25Z

Cfriedt:

OpenEmbedded

2009-02-10T18:22:32Z

Cfriedt: /* Building the OpenMoko Distribution with OpenEmbedded */

{{Languages|OpenEmbedded}}

Openmoko, our distribution, is built using OpenEmbedded. OpenEmbedded will:

* Generate (cross-compile) software packages for multiple embedded targets.
* Handle different hardware architectures, and support multiple releases across those architectures.

For more information please see the [http://www.openembedded.org/ Open Embedded] website.

== Building the OpenMoko Distribution with OpenEmbedded ==

'''Note:''' If you are an application developer, you probably do not want to build OpenEmbedded from scratch. For compiling simple applications with few library dependencies (including boot-loader and kernel), consider using our prebuilt [[Toolchain]]. For more complex applications with many library dependencies, download a prebuilt [[OpenEmbedded Torrent]] with your favourite [http://en.wikipedia.org/wiki/BitTorrent_client BitTorrent client].

Building OpenMoko from scratch is a time-, cpu- and diskspace-consuming process which should only be done if you are a system integrator and want to customize your OpenMoko distribution.

== Simplified Instructions: MokoMakefile ==

For beginners who wish to customize their OpenMoko distribution, the facility called [[MokoMakefile]] simplifies building OpenEmbedded.

== Detailed Instructions: OpenEmbedded ==

Beginner OpenMoko developers who would prefer to have full control over their OpenEmbedded build environment should follow the instructions below.

=== Preparations ===

Several prerequisite software components are necessary in order to have a fully functional OpenEmbedded build environment. However, setup and installation varies depending on the operating system installed on your workstation. The [http://wiki.openembedded.net/index.php OpenEmbedded Wiki] provides [http://wiki.openembedded.net/index.php/OEandYourDistro setup instructions] for FreeBSD, Mac OS X, and most major Linux distributions, of course.

For OpenEmbedded installation instructions please refer to [http://wiki.openembedded.net/index.php/OEandYourDistro OEandYourDistro].

=== ${OE_HOME} ===

Assuming that you have installed all prerequisite software, you are now ready to create a directory for all of your OpenEmbedded (OE) related work. We will refer to OE_HOME in a generic way, but for argument's sake, assume that it is equal to ${HOME}/oe. You should expect ${OE_HOME} to grow tremendously in size, up to approximately 8GB or larger in some cases. Also be aware, that a full OE build could require several hours of constant building, which may inhibit the performance of your computer while performing other tasks. Replace ${HOME}/oe with your preferred location.

For Bash users:
export OE_HOME=${HOME}/oe

For Tcsh users:
setenv OE_HOME ${HOME}/oe

Next, run 'mkdir -p ${OE_HOME}' to create the directory.

=== Synchronizing OpenEmbedded With Git ===

Just like any tree, OpenEmbedded has several branches. In this case they are called 'development branches'. Some noteworthy ones include org.openembedded.dev (the default) and org.openembedded.stable .

To syncronize the OpenEmbedded tree, run
<pre>
git clone git://git.openembedded.net/openembedded ${OE_HOME}/org.openembedded.dev
</pre>

Note that last argument could be any directory name (git will create the directory if it doesn't exist). Sticking to 'good convention', the directory name was chosen to reflect the default development branch, org.openembedded.dev . See the [http://wiki.openembedded.net/index.php/GitPhraseBook OE GitPhraseBook] for more info on checking out different branches.

To update the tree, run
<pre>
cd ${OE_HOME}/org.openembedded.dev
git pull
</pre>

For further information on Git, see [http://git-scm.com The Git Homepage].

Also, please explore the directory structure of the OpenEmbedded build tree and take a moment to open and read one of the each type of BitBake file. This helps one to become familiar with recipe syntax and the inheritance system. Of particular note, please read the file 'local.conf.sample'.
<pre>
org.openembedded.dev
|-- classes
| |-- rootfs_ipk.bbclass
| `-- xorg-module.bbclass
|-- conf
| `-- local.conf.sample
| |-- distro
| | `-- angstrom-2008.1.conf
| |-- machine
| | |-- om-gta01.conf
| | `-- om-gta02.conf
`-- packages
|-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- images
|-- console-image.bb
|-- fso-console-image.bb
|-- fso-image.bb
|-- openmoko-image.bb
|-- opie-image.bb
`-- x11-image.bb
</pre>
=== Build Configuration ===

If you explored local.conf.example, then you would be aware that there are some very important variables to be set like MACHINE, DISTRO, and BBFILES, among many others. This is done in a configuration file (local.conf) inside the build directory.

'''Note:''' Using BitBake and OE for cross-compilation require that each target-distro combination is built in a separate directory, so that no version collisions occur. Concurrent builds may safely share the same DL_DIR though. This would suggest that a safe name for build directories is of the form ${OE_HOME}/build-${MACHINE}-${DISTRO}. Of course, if you don't plan on building for more than one machine-distro combination, then the naming of this directory is arbitrary. For the purpose of this example, we will use the convention ${OE_HOME}/build-${MACHINE} .

Now, create the 'local.conf' configuration file. Notice that the CACHE and TMPDIR variables are neatly kept within the build directory while the DL_DIR variable is outside of the build directory, so that concurrent builds may reuse the same source packages.
<pre>
OE_HOME ?= "${HOME}/oe"

MACHINE = "om-gta02"
DISTRO = "angstrom-2008.1"

DL_DIR = "${OE_HOME}/downloads"

BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"

BBMASK = ""

TMPDIR = "${OE_HOME}/build-${MACHINE}/tmp"
CACHE = "${TMPDIR}/cache"

IMAGE_FSTYPES = "jffs2 tar.gz"

ENABLE_BINARY_LOCALE_GENERATION = "0"
</pre>

The BBFILES variable is also of prime importance! It tells bitbake where to locate all available recipes for a build. The OpenEmbedded build environment is almost completely ready to go, with just one more minor step left.

=== Build Environment ===

For quick and easy initialization of the OpenEmbedded build environment, it is often suggested that the developer create a 'setup-env' script to source from the command line. This script can be called to initialize the most important of environment variables. Below is a very basic example of a setup-env script.

setup-env for Bash users:
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02
export BBPATH=${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
setup-env for Tcsh users:
<pre>
[[ -z ${OE_HOME} ]] && setenv OE_HOME ${HOME}/oe
[[ -z ${MACHINE} ]] && setenv MACHINE om-gta02
setenv BBPATH ${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
To invoke the setup-env script in bash, run 'source setup-env'. In tcsh, run '. setup-env'.

=== Testing the OE Build Environment ===

That's it! Now you should be prepared to bake your first BitBake recipe.

bitbake helloworld

=== Building an Image ===

There are several full filesystem images which can be built directly with OpenEmbedded using a single command. These include openmoko-image, fso-image, and so on. The image definitions can be found under ${OE_HOME}/org.openembedded.dev/packages/images

A good place to start is with

bitbake fso-image

That concludes this introduction to BitBake and OpenEmbedded. Good luck!

=== Other References ===

Please feel free to refer to other online sources of information for [http://bitbake.berlios.de BitBake], [http://www.openembedded.org OpenEmbedded], and the [http://www.angstrom-distribution.org Angstrom Distribution] to name a few.

== Broken Builds and Bug Reporting ==

Using the org.openembedded.dev branch can often result in broken builds. For that reason, it is usually a good idea to limit synchronizing with the repository only after successfully building an image. Some may even want to archive the tree and build directory after an image is built.

Now in the case that an image does not successfully build, it is not always necessarily a bug or a new bug. The problem might have to do with some conflicting software on the workstation, and it could be a bug that is already know and being fixed.

Below are a few useful steps to follow when a build does not successfully complete:

* Identify the package that failed to build and read the bitbake log, as well as config.log if it exists
** Find a line near the bottom of your output that matches "ERROR: ... failed" or "NOTE: ... failed". The name of the package should be contained in the '...'
** Find the log file. There should be a line near the bottom of your output that matches "ERROR: see log in ...", where '...' contains the log file name. These are usually of the form log.do_compile.12345 or log.do_configure.12345, etc.
* Try to identify the root cause of the error
** In many cases, if one examines log.do_configure, only the error is reported, but not the cause of the error
** Most packages that build with autotools will also have a config.log file that contains the exact cause of the error
* If you can fix the error, and the error is local to your workstation, and not really a bug, then fix the error yourself.
* Otherwise, check the [http://bugs.openembedded.net OpenEmbedded Bugzilla] to see if the error is known.
* If a solution is already available, then try it out. If you can fix the error, then do so. If your solution is correct, please post all relevent patches to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

=== Where to Report Bugs ===

Authentic bugs should be reported to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

== Tips & Tricks ==

=== Screen is Your Friend ===

If you happen to be building all of your packages remotely on a server, using an ssh session, the session might occasionally be interrupted and the connection could be terminated. If in the process of building an image with bitbake, this means that the build process will terminate as well.

In order to ensure that a build continues in the presence of communication failures, it is advisable to use the [http://www.gnu.org/software/screen GNU Screen] utility. Screen is also very useful when performing several concurrent OpenEmbedded builds for different machine-distro combinations.

Screen installation varies with your OS and distribution.

=== BitBake Overlays ===

Bitbake overlays are useful for OpenEmbedded developers to eliminate bugs or package software without disturbiing the OpenEmbedded tree itself. Overlays are very similar in structure to the OpenEmbedded tree, but are usually only sparsely populated. Non-sparsely poplulated overlays are actually more closely relatedd to separate development branches. Good convention would suggest to always name the overlay appropriately.

Below is an example of two overlays, three build directories, a setup-env script, and a local.conf where the developer has multiple build targets as well as multiple BitBake overlays.
<pre>
oe
|-- build-beagleboard
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-om-gta02
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-ts72xx
| |-- conf
| | `-- local.conf
| `-- tmp
|-- com.somecompany.dev
| |-- conf
| | `-- machine
| `-- packages
| |-- images
| | `-- console-image.bb
| `-- rxtx
| |-- files
| |-- rxtx-fixes-from-debian.patch
| `-- rxtx_2.1-7r2.bb
|-- org.openembedded.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- images
|-- org.openmoko.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- setup-env
</pre>
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02

unset BBPATH

case "${MACHINE}" in
"beagleboard" | "ts72xx" )
BBPATH="${OE_HOME}/com.somecompany.dev"
;;
"om-gta02")
BBPATH="${OE_HOME}/org.openmoko.dev"
;;
*)
echo -e "error: unsupported machine"
exit -1
;;
esac

export BBPATH=${BBPATH}:${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>

Note that the overlay-specific BBPATH entry ''precedes'' the default BBPATH entries.

<pre>
...
BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"
BBFILES += " ${OE_HOME}/org.openmoko.dev/packages/*/*.bb"

BBFILE_COLLECTIONS = "upstream local"
BBFILE_PATTERN_upstream = "${OE_HOME}/org.openembedded.dev"
BBFILE_PRIORITY_upstream = "0"
BBFILE_PATTERN_local = "${OE_HOME}/org.openmoko.dev"
BBFILE_PRIORITY_local = "1"
...
</pre>

In order for the overlay to be detected by BitBake, the above variables need to be defined. It is possible to have more than one overlay and each one should be given a different priority.

=== Useful BitBake Commands ===

<pre>
# list all of the tasks defined for a given package_name
bitbake -c listtasks <package_name>

# clean the work directory for a specific package
bitbake -c clean <package_name>

# build a specific recipe
bitbake -b <path/to/some/recipe.bb>
</pre>

[[Category:Application Developer]]
[[Category:System Developers]]

OpenEmbedded Torrent

2009-02-10T18:20:12Z

Cfriedt: New page: List of torrents for downloading pre-compiled OpenEmbedded environments, organized by DISTRO, MACHINE and ARCH. * openmoko ** gta01 *** x86 *** x86_64 ** gta02 *** x86 *** x86_64 * fso **...

List of torrents for downloading pre-compiled OpenEmbedded environments, organized by DISTRO, MACHINE and ARCH.

* openmoko
** gta01
*** x86
*** x86_64
** gta02
*** x86
*** x86_64
* fso
** gta01
*** x86
*** x86_64
** gta02
*** x86
*** x86_64
* angstrom-2008.1
** gta01
*** x86
*** x86_64
** gta02
*** x86
*** x86_64

OpenEmbedded

2009-02-10T17:51:01Z

Cfriedt: changes made according to the devel list proposals

{{Languages|OpenEmbedded}}

Openmoko, our distribution, is built using OpenEmbedded. OpenEmbedded will:

* Generate (cross-compile) software packages for multiple embedded targets.
* Handle different hardware architectures, and support multiple releases across those architectures.

For more information please see the [http://www.openembedded.org/ Open Embedded] website.

== Building the OpenMoko Distribution with OpenEmbedded ==

'''Note:''' If you are an application developer, you probably do not want to build Openmoko with OpenEmbedded. In that case, you should use our prebuilt [[Toolchain]]. Building OpenMoko is a time-, cpu- and diskspace-consuming process which should only be done if you are a system integrator and want to customize your OpenMoko distribution.

== Simplified Instructions: MokoMakefile ==

For beginners who wish to customize their OpenMoko distribution, the facility called [[MokoMakefile]] simplifies building OpenEmbedded.

== Detailed Instructions: OpenEmbedded ==

Beginner OpenMoko developers who would prefer to have full control over their OpenEmbedded build environment should follow the instructions below.

=== Preparations ===

Several prerequisite software components are necessary in order to have a fully functional OpenEmbedded build environment. However, setup and installation varies depending on the operating system installed on your workstation. The [http://wiki.openembedded.net/index.php OpenEmbedded Wiki] provides [http://wiki.openembedded.net/index.php/OEandYourDistro setup instructions] for FreeBSD, Mac OS X, and most major Linux distributions, of course.

For OpenEmbedded installation instructions please refer to [http://wiki.openembedded.net/index.php/OEandYourDistro OEandYourDistro].

=== ${OE_HOME} ===

Assuming that you have installed all prerequisite software, you are now ready to create a directory for all of your OpenEmbedded (OE) related work. We will refer to OE_HOME in a generic way, but for argument's sake, assume that it is equal to ${HOME}/oe. You should expect ${OE_HOME} to grow tremendously in size, up to approximately 8GB or larger in some cases. Also be aware, that a full OE build could require several hours of constant building, which may inhibit the performance of your computer while performing other tasks. Replace ${HOME}/oe with your preferred location.

For Bash users:
export OE_HOME=${HOME}/oe

For Tcsh users:
setenv OE_HOME ${HOME}/oe

Next, run 'mkdir -p ${OE_HOME}' to create the directory.

=== Synchronizing OpenEmbedded With Git ===

Just like any tree, OpenEmbedded has several branches. In this case they are called 'development branches'. Some noteworthy ones include org.openembedded.dev (the default) and org.openembedded.stable .

To syncronize the OpenEmbedded tree, run
<pre>
git clone git://git.openembedded.net/openembedded ${OE_HOME}/org.openembedded.dev
</pre>

Note that last argument could be any directory name (git will create the directory if it doesn't exist). Sticking to 'good convention', the directory name was chosen to reflect the default development branch, org.openembedded.dev . See the [http://wiki.openembedded.net/index.php/GitPhraseBook OE GitPhraseBook] for more info on checking out different branches.

To update the tree, run
<pre>
cd ${OE_HOME}/org.openembedded.dev
git pull
</pre>

For further information on Git, see [http://git-scm.com The Git Homepage].

Also, please explore the directory structure of the OpenEmbedded build tree and take a moment to open and read one of the each type of BitBake file. This helps one to become familiar with recipe syntax and the inheritance system. Of particular note, please read the file 'local.conf.sample'.
<pre>
org.openembedded.dev
|-- classes
| |-- rootfs_ipk.bbclass
| `-- xorg-module.bbclass
|-- conf
| `-- local.conf.sample
| |-- distro
| | `-- angstrom-2008.1.conf
| |-- machine
| | |-- om-gta01.conf
| | `-- om-gta02.conf
`-- packages
|-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- images
|-- console-image.bb
|-- fso-console-image.bb
|-- fso-image.bb
|-- openmoko-image.bb
|-- opie-image.bb
`-- x11-image.bb
</pre>
=== Build Configuration ===

If you explored local.conf.example, then you would be aware that there are some very important variables to be set like MACHINE, DISTRO, and BBFILES, among many others. This is done in a configuration file (local.conf) inside the build directory.

'''Note:''' Using BitBake and OE for cross-compilation require that each target-distro combination is built in a separate directory, so that no version collisions occur. Concurrent builds may safely share the same DL_DIR though. This would suggest that a safe name for build directories is of the form ${OE_HOME}/build-${MACHINE}-${DISTRO}. Of course, if you don't plan on building for more than one machine-distro combination, then the naming of this directory is arbitrary. For the purpose of this example, we will use the convention ${OE_HOME}/build-${MACHINE} .

Now, create the 'local.conf' configuration file. Notice that the CACHE and TMPDIR variables are neatly kept within the build directory while the DL_DIR variable is outside of the build directory, so that concurrent builds may reuse the same source packages.
<pre>
OE_HOME ?= "${HOME}/oe"

MACHINE = "om-gta02"
DISTRO = "angstrom-2008.1"

DL_DIR = "${OE_HOME}/downloads"

BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"

BBMASK = ""

TMPDIR = "${OE_HOME}/build-${MACHINE}/tmp"
CACHE = "${TMPDIR}/cache"

IMAGE_FSTYPES = "jffs2 tar.gz"

ENABLE_BINARY_LOCALE_GENERATION = "0"
</pre>

The BBFILES variable is also of prime importance! It tells bitbake where to locate all available recipes for a build. The OpenEmbedded build environment is almost completely ready to go, with just one more minor step left.

=== Build Environment ===

For quick and easy initialization of the OpenEmbedded build environment, it is often suggested that the developer create a 'setup-env' script to source from the command line. This script can be called to initialize the most important of environment variables. Below is a very basic example of a setup-env script.

setup-env for Bash users:
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02
export BBPATH=${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
setup-env for Tcsh users:
<pre>
[[ -z ${OE_HOME} ]] && setenv OE_HOME ${HOME}/oe
[[ -z ${MACHINE} ]] && setenv MACHINE om-gta02
setenv BBPATH ${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>
To invoke the setup-env script in bash, run 'source setup-env'. In tcsh, run '. setup-env'.

=== Testing the OE Build Environment ===

That's it! Now you should be prepared to bake your first BitBake recipe.

bitbake helloworld

=== Building an Image ===

There are several full filesystem images which can be built directly with OpenEmbedded using a single command. These include openmoko-image, fso-image, and so on. The image definitions can be found under ${OE_HOME}/org.openembedded.dev/packages/images

A good place to start is with

bitbake fso-image

That concludes this introduction to BitBake and OpenEmbedded. Good luck!

=== Other References ===

Please feel free to refer to other online sources of information for [http://bitbake.berlios.de BitBake], [http://www.openembedded.org OpenEmbedded], and the [http://www.angstrom-distribution.org Angstrom Distribution] to name a few.

== Broken Builds and Bug Reporting ==

Using the org.openembedded.dev branch can often result in broken builds. For that reason, it is usually a good idea to limit synchronizing with the repository only after successfully building an image. Some may even want to archive the tree and build directory after an image is built.

Now in the case that an image does not successfully build, it is not always necessarily a bug or a new bug. The problem might have to do with some conflicting software on the workstation, and it could be a bug that is already know and being fixed.

Below are a few useful steps to follow when a build does not successfully complete:

* Identify the package that failed to build and read the bitbake log, as well as config.log if it exists
** Find a line near the bottom of your output that matches "ERROR: ... failed" or "NOTE: ... failed". The name of the package should be contained in the '...'
** Find the log file. There should be a line near the bottom of your output that matches "ERROR: see log in ...", where '...' contains the log file name. These are usually of the form log.do_compile.12345 or log.do_configure.12345, etc.
* Try to identify the root cause of the error
** In many cases, if one examines log.do_configure, only the error is reported, but not the cause of the error
** Most packages that build with autotools will also have a config.log file that contains the exact cause of the error
* If you can fix the error, and the error is local to your workstation, and not really a bug, then fix the error yourself.
* Otherwise, check the [http://bugs.openembedded.net OpenEmbedded Bugzilla] to see if the error is known.
* If a solution is already available, then try it out. If you can fix the error, then do so. If your solution is correct, please post all relevent patches to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

=== Where to Report Bugs ===

Authentic bugs should be reported to the [http://bugs.openembedded.net OpenEmbedded Bugzilla]

== Tips & Tricks ==

=== Screen is Your Friend ===

If you happen to be building all of your packages remotely on a server, using an ssh session, the session might occasionally be interrupted and the connection could be terminated. If in the process of building an image with bitbake, this means that the build process will terminate as well.

In order to ensure that a build continues in the presence of communication failures, it is advisable to use the [http://www.gnu.org/software/screen GNU Screen] utility. Screen is also very useful when performing several concurrent OpenEmbedded builds for different machine-distro combinations.

Screen installation varies with your OS and distribution.

=== BitBake Overlays ===

Bitbake overlays are useful for OpenEmbedded developers to eliminate bugs or package software without disturbiing the OpenEmbedded tree itself. Overlays are very similar in structure to the OpenEmbedded tree, but are usually only sparsely populated. Non-sparsely poplulated overlays are actually more closely relatedd to separate development branches. Good convention would suggest to always name the overlay appropriately.

Below is an example of two overlays, three build directories, a setup-env script, and a local.conf where the developer has multiple build targets as well as multiple BitBake overlays.
<pre>
oe
|-- build-beagleboard
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-om-gta02
| |-- conf
| | `-- local.conf
| `-- tmp
|-- build-ts72xx
| |-- conf
| | `-- local.conf
| `-- tmp
|-- com.somecompany.dev
| |-- conf
| | `-- machine
| `-- packages
| |-- images
| | `-- console-image.bb
| `-- rxtx
| |-- files
| |-- rxtx-fixes-from-debian.patch
| `-- rxtx_2.1-7r2.bb
|-- org.openembedded.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- images
|-- org.openmoko.dev
| |-- conf
| | `-- machine
| `-- packages
| `-- tangogps
| |-- tangogps.inc
| `-- tangogps_0.9.3.bb
`-- setup-env
</pre>
<pre>
[[ -z ${OE_HOME} ]] && export OE_HOME=${HOME}/oe
[[ -z ${MACHINE} ]] && export MACHINE=om-gta02

unset BBPATH

case "${MACHINE}" in
"beagleboard" | "ts72xx" )
BBPATH="${OE_HOME}/com.somecompany.dev"
;;
"om-gta02")
BBPATH="${OE_HOME}/org.openmoko.dev"
;;
*)
echo -e "error: unsupported machine"
exit -1
;;
esac

export BBPATH=${BBPATH}:${OE_HOME}/build-${MACHINE}:${OE_HOME}/org.openembedded.dev
</pre>

Note that the overlay-specific BBPATH entry ''precedes'' the default BBPATH entries.

<pre>
...
BBFILES := "${OE_HOME}/org.openembedded.dev/packages/*/*.bb"
BBFILES += " ${OE_HOME}/org.openmoko.dev/packages/*/*.bb"

BBFILE_COLLECTIONS = "upstream local"
BBFILE_PATTERN_upstream = "${OE_HOME}/org.openembedded.dev"
BBFILE_PRIORITY_upstream = "0"
BBFILE_PATTERN_local = "${OE_HOME}/org.openmoko.dev"
BBFILE_PRIORITY_local = "1"
...
</pre>

In order for the overlay to be detected by BitBake, the above variables need to be defined. It is possible to have more than one overlay and each one should be given a different priority.

=== Useful BitBake Commands ===

<pre>
# list all of the tasks defined for a given package_name
bitbake -c listtasks <package_name>

# clean the work directory for a specific package
bitbake -c clean <package_name>

# build a specific recipe
bitbake -b <path/to/some/recipe.bb>
</pre>

[[Category:Application Developer]]
[[Category:System Developers]]

BitBake

2009-02-10T17:43:26Z

Cfriedt: /* Get BitBake */

{{Languages|BitBake}}
BitBake is the build tool used by [[OpenEmbedded]]. [[BitBake recipe]]s are simple, declarative files. Here is an example for the openmoko-calculator2 application:

<pre>
DESCRIPTION = "A Calculator for Openmoko"
SECTION = "openmoko/tools"
DEPENDS = "libmokoui2"
PV = "0.1.0+svnr${SRCREV}"
PR = "r0"

inherit openmoko2
</pre>

The user manual is available at the [http://bitbake.berlios.de/manual/ BitBake berlios page].

[[Category:Application Developer]]

==Set Bitbake building environment==
Basically, using bitbake to build your image is very easy.
* Get bitbake
* Get OpenEmbedded tree
* Set local configuare file
* Set building environment variables.
All you need is these four things. Lets assume you are using a account named '''build''', and you are working under directory '''moko'''.

===Get BitBake===

'''Note:''' The instructions below are fairly out of date. It is not actually necessary to use bitbake-om. Any version of BitBake as recent or more recent than 1.8.12 (>=bitbake-1.8.12) is all that is necessary. OpenMoko development is largely moving upstream to the main OpenEmbedded repository. To get started, please follow the instructions available on the [http://wiki.openembedded.net/index.php OpenEmbedded Wiki] under [http://wiki.openembedded.net/index.php/OEandYourDistro OEandYourDistro]. -- [[User:Cfriedt]] 20090109

$cd ~/moko # Enter the directory
$git clone git://git.openmoko.org/git/bitbake.git bitbake-om # get the bitbake of openmoko.

Bitbake come for OpenEmbedded, however Openmoko has its own bitbake, named [http://git.openmoko.org/?p=bitbake.git;a=summary bitbake-om]. After cloning the bitbake-om, you have the kitchen comprehensive. You also need recipes to tell you how to cook.

===Get OpenEmbedded Tree===

'''Note:''' The instructions below are fairly out of date. To get started with OpenEmbedded, please follow the instructions under [[OpenEmbedded]]. -- [[User:Cfriedt]] 20090109

$git clone git://git.openmoko.org/git/openmoko.git openmoko

It will clone an [http://git.openmoko.org/?p=openmoko.git;a=summary OE tree from Openmoko git server]. This is the recipes what tell bitbake how to cook. The cloning process spend little time, get a cup of coffee is a good idea when you are waiting.

===Set Local configuare file===

$install -d /home/build/moko/local/conf #create the direcotry
$vim local/conf/local.conf # use your favorite editor

Paste these line into the file
ALLOW_EMPTY = "1"
BBFILES := "/home/build/moko/openmoko/packages/*/*.bb"
BB_GIT_CLONE_FOR_SRCREV = "1"
BBINCLUDELOGS = "yes"
BBMASK = ""
DISTRO = "openmoko"
DL_DIR := "/home/build/moko/sources"
EXTENDPE = ""
GLIBC_GENERATE_LOCALES = "en_US.UTF-8"
IMAGE_FSTYPES = "jffs2 tar.gz"
INHERIT += "om-utils"
MACHINE = "om-gta02"
PARALLEL_MAKE = "-j 4"
QA_LOG = "1"
TMPDIR := "/home/build/moko/build/"

Let me explain the meanings of some variables.
*BBFILES: It tells bitbake where those recipes are.
*DL_DIR: Bitbake fetch source code and put them here.
*MACHINE: I build packages for gta02. If you are going to build for gta01, replace it with "om-gta01"
*PARALLEL_MAKE: Please read the manual of "make" and search the -j option.
*TMPDIR: All of your building result will place here.

===Set building environment variables===

$vim build_env # use your favorite editor

Paste these lines into the file

export BBPATH="/home/build/moko/local:/home/build/moko/openmoko"
export PATH=/home/build/moko/bitbake-om/bin:$PATH

==Update environment==
bitbake-om won't change often. But the OE tree (/home/build/moko/openmoko) almost change everyday. Update them is important so you can get the latest fix.

$cd /home/build/moko/bitbake-om
$git pull
$cd /home/build/moko/openmoko
$git pull

==Starting use bitbake==
The first time you use bitbake will spend many hours. It have to fetch every source code what you need. To build the meta toolchain, and many basic libraries like glibc.

$source /home/build/moko/build_env #read in the environment variables.
$bitbake helloworld # build the simplest case.
Playing video game for 5 hours, Watching movie for 3 hours and Sleeping for 8 hours.

If you wanna try something like fso image, just ask bitbake to cook another food.

$bitbake fso-image

All the recipe are placed in '''/home/build/moko/openmoko/packages'''. For example, fso-image recipe is placed in '''/home/build/moko/openmoko/packages/images/fso-image.bb'''.

After the building process complete, the opk files are placed in '''/home/build/moko/build/deploy/glibc/opk''', and the image is in '''/home/build/moko/build/deploy/images'''.

BitBake recipe

2009-02-10T16:39:05Z

Cfriedt: /* Standard tasks in a recipe */

== Bitbake ==
BitBake is a build tool for executing tasks and managing metadata.It was inspired by Portage, the package management system used by the Gentoo Linux distribution. BitBake is the basis of the OpenEmbedded project, which is being used to build and maintain Openmoko.

For the user guide of Bitbake, please visit the site : [http://bitbake.berlios.de/manual/]

== Bitbake Recipe ==
The literal meaning of a recipe is that it is a direction to making something. Similarly, a bitbake recipe tells bitbake how to build a particular package X.
It includes all the package dependencies, sources to fetch the source code from, configuration, compilation, build, install and remove instructions. Apart from this, it also stores the meta data for the package in certain standard variables.

=== Some Standard Variables in a Bitbake recipe ===

1. ''DESCRIPTION = "This application will print hello world on your screen"'' :
Gives the description of the application that you are developing

2. ''AUTHOR = "Deepank Gupta"'' :
Gives name of the author of the package. Similar variables can be defined such as HOMEPAGE, LICENSE, SECTION etc.

3.'' PN = "Helloworld"'' :
This specifies the package name of the package excluding the version number of the package. The version number is specified by '''PV''' and revision number by PR variable.

4. ''DEPENDS = "X Y Z"'' :
With regard to dependencies, it expects the .bb to define a DEPENDS variable, which contains a space seperated list of “package names”. In the above example the package is dependent on X, Y and Z packages. The run-time dependencies of a package are specified by the variable RDEPENDS.

5. ''PROVIDES += "virtual/package"'' :
This specifies the functionality provided by the bitbake recipe.

6. ''PREFERRED_VERSION_a = "1.1"'' :
This specifies the preferred version of a package named a. This is used if there are more than 1 versions of a same package such as a-1.1.bb and a-1.2.bb

7. ''SRC_URI = "file://myhelloworld.c"'' :
This specifies the source address from where to fetch the source files. It can fetch from local disk using file:// , websites using http:// , cvs and svn using cvs:// and svn:// and others like ftp, git etc.

8. ''S = "${WORKDIR}/trunk"''
This might be used in order to specify which folder our package extracts to. Normally it looks like ${WORKDIR}/${PN}_${PV} if the package was generated by the autotools - which is the value this variable automatically points to when not set by the receipe. In the case this example shows it points to a folder named trunk - which might be useful for a reciepe that builds the last version from SVN.

=== Some variables specific to Openmoko recipes ===
$WORKDIR = $OMDIR/local/packages/<application directory>
$bindir = $OMDIR/build/tmp/work/armv4t-linux/<application directory>/image/usr/bin
$docir = $OMDIR/build/tmp/work/armv4t-linux/<application directory>/image/usr/share/doc
$D = $OMDIR/build/

=== Standard tasks in a recipe ===
1. do_fetch : Fetch the source files from the URI given in the SRC_URI.

2. do_unpack : Unpack the source files into WORKDIR.

3. do_patch : Patch the source code, if necessary, before configuration.

4. do_configure : for doing the configuration

5. do_compile : To compile the program(s) using a compiler specified by CC variable.

6. do_build : To build the package including its build-time dependencies.

7. do_install : To install the package on the filesystem i.e copy the binaries where required.

You can define your own tasks (as many as you like) which can also be python functions.
eg.

do_mytask () {
echo "Hello, world!"
}

You can list all tasks for a given recipe with 'bitbake -c listtasks <package_name>'.

For packages that are built with autotools (automake, autoconf, etc), it is often only necessary to inherit autotools.bbclass, define SRC_URI, and sometimes define do_patch in the .bb file. All BitBake classes inherit from base.bbclass, where the default implementations for most tasks are defined.

=== A Basic Bitbake Recipe [http://wiki.openmoko.org/wiki/Application_Development_Crash_Course#Filling_the_Files] ===

[[Category:Application Developer]]

BitBake recipe

2009-02-10T16:29:33Z

Cfriedt: /* Standard tasks in a recipe */ Added 'bitbake -c listtasks <package_name>'

== Bitbake ==
BitBake is a build tool for executing tasks and managing metadata.It was inspired by Portage, the package management system used by the Gentoo Linux distribution. BitBake is the basis of the OpenEmbedded project, which is being used to build and maintain Openmoko.

For the user guide of Bitbake, please visit the site : [http://bitbake.berlios.de/manual/]

== Bitbake Recipe ==
The literal meaning of a recipe is that it is a direction to making something. Similarly, a bitbake recipe tells bitbake how to build a particular package X.
It includes all the package dependencies, sources to fetch the source code from, configuration, compilation, build, install and remove instructions. Apart from this, it also stores the meta data for the package in certain standard variables.

=== Some Standard Variables in a Bitbake recipe ===

1. ''DESCRIPTION = "This application will print hello world on your screen"'' :
Gives the description of the application that you are developing

2. ''AUTHOR = "Deepank Gupta"'' :
Gives name of the author of the package. Similar variables can be defined such as HOMEPAGE, LICENSE, SECTION etc.

3.'' PN = "Helloworld"'' :
This specifies the package name of the package excluding the version number of the package. The version number is specified by '''PV''' and revision number by PR variable.

4. ''DEPENDS = "X Y Z"'' :
With regard to dependencies, it expects the .bb to define a DEPENDS variable, which contains a space seperated list of “package names”. In the above example the package is dependent on X, Y and Z packages. The run-time dependencies of a package are specified by the variable RDEPENDS.

5. ''PROVIDES += "virtual/package"'' :
This specifies the functionality provided by the bitbake recipe.

6. ''PREFERRED_VERSION_a = "1.1"'' :
This specifies the preferred version of a package named a. This is used if there are more than 1 versions of a same package such as a-1.1.bb and a-1.2.bb

7. ''SRC_URI = "file://myhelloworld.c"'' :
This specifies the source address from where to fetch the source files. It can fetch from local disk using file:// , websites using http:// , cvs and svn using cvs:// and svn:// and others like ftp, git etc.

8. ''S = "${WORKDIR}/trunk"''
This might be used in order to specify which folder our package extracts to. Normally it looks like ${WORKDIR}/${PN}_${PV} if the package was generated by the autotools - which is the value this variable automatically points to when not set by the receipe. In the case this example shows it points to a folder named trunk - which might be useful for a reciepe that builds the last version from SVN.

=== Some variables specific to Openmoko recipes ===
$WORKDIR = $OMDIR/local/packages/<application directory>
$bindir = $OMDIR/build/tmp/work/armv4t-linux/<application directory>/image/usr/bin
$docir = $OMDIR/build/tmp/work/armv4t-linux/<application directory>/image/usr/share/doc
$D = $OMDIR/build/

=== Standard tasks in a recipe ===
1. do_fetch : Fetch the source files from the URI given in the SRC_URI.

2. do_configure : for doing the configuration

3. do_compile : To compile the program(s) using a compiler specified by CC variable.

4. do_build : To build the package including its build-time dependencies.

5. do_install : To install the package on the filesystem i.e copy the binaries where required.

You can define your own tasks (as many as you like) which can also be python functions.
eg.

do_mytask () {
echo "Hello, world!"
}

You can list all tasks for a given recipe with 'bitbake -c listtasks <package_name>'.

=== A Basic Bitbake Recipe [http://wiki.openmoko.org/wiki/Application_Development_Crash_Course#Filling_the_Files] ===

[[Category:Application Developer]]

BitBake

2009-02-10T02:46:21Z

Cfriedt: /* Get OpenEmbedded Tree */

{{Languages|BitBake}}
BitBake is the build tool used by [[OpenEmbedded]]. [[BitBake recipe]]s are simple, declarative files. Here is an example for the openmoko-calculator2 application:

<pre>
DESCRIPTION = "A Calculator for Openmoko"
SECTION = "openmoko/tools"
DEPENDS = "libmokoui2"
PV = "0.1.0+svnr${SRCREV}"
PR = "r0"

inherit openmoko2
</pre>

The user manual is available at the [http://bitbake.berlios.de/manual/ BitBake berlios page].

[[Category:Application Developer]]

==Set Bitbake building environment==
Basically, using bitbake to build your image is very easy.
* Get bitbake
* Get OpenEmbedded tree
* Set local configuare file
* Set building environment variables.
All you need is these four things. Lets assume you are using a account named '''build''', and you are working under directory '''moko'''.

===Get BitBake===

'''Note:''' The instructions below are fairly out of date. It is not actually necessary to use bitbake-om. Any version of BitBake as recent or more recent than 1.8.12 (>=bitbake-1.8.12) is all that is necessary. OpenMoko development is largely moving upstream to the main OpenEmbedded repository. To get started, please follow the instructions available on the [http://wiki.openembedded.net/index.php OpenEmbedded Wiki] under [http://wiki.openembedded.net/index.php/OEandYourDistro OEandYourDistro]. -- [[Cfriedt]] 20090109

$cd ~/moko # Enter the directory
$git clone git://git.openmoko.org/git/bitbake.git bitbake-om # get the bitbake of openmoko.

Bitbake come for OpenEmbedded, however Openmoko has its own bitbake, named [http://git.openmoko.org/?p=bitbake.git;a=summary bitbake-om]. After cloning the bitbake-om, you have the kitchen comprehensive. You also need recipes to tell you how to cook.

===Get OpenEmbedded Tree===

'''Note:''' The instructions below are fairly out of date. To get started with OpenEmbedded, please follow the instructions under [[OpenEmbedded]]. -- [[User:Cfriedt]] 20090109

$git clone git://git.openmoko.org/git/openmoko.git openmoko

It will clone an [http://git.openmoko.org/?p=openmoko.git;a=summary OE tree from Openmoko git server]. This is the recipes what tell bitbake how to cook. The cloning process spend little time, get a cup of coffee is a good idea when you are waiting.

===Set Local configuare file===

$install -d /home/build/moko/local/conf #create the direcotry
$vim local/conf/local.conf # use your favorite editor

Paste these line into the file
ALLOW_EMPTY = "1"
BBFILES := "/home/build/moko/openmoko/packages/*/*.bb"
BB_GIT_CLONE_FOR_SRCREV = "1"
BBINCLUDELOGS = "yes"
BBMASK = ""
DISTRO = "openmoko"
DL_DIR := "/home/build/moko/sources"
EXTENDPE = ""
GLIBC_GENERATE_LOCALES = "en_US.UTF-8"
IMAGE_FSTYPES = "jffs2 tar.gz"
INHERIT += "om-utils"
MACHINE = "om-gta02"
PARALLEL_MAKE = "-j 4"
QA_LOG = "1"
TMPDIR := "/home/build/moko/build/"

Let me explain the meanings of some variables.
*BBFILES: It tells bitbake where those recipes are.
*DL_DIR: Bitbake fetch source code and put them here.
*MACHINE: I build packages for gta02. If you are going to build for gta01, replace it with "om-gta01"
*PARALLEL_MAKE: Please read the manual of "make" and search the -j option.
*TMPDIR: All of your building result will place here.

===Set building environment variables===

$vim build_env # use your favorite editor

Paste these lines into the file

export BBPATH="/home/build/moko/local:/home/build/moko/openmoko"
export PATH=/home/build/moko/bitbake-om/bin:$PATH

==Update environment==
bitbake-om won't change often. But the OE tree (/home/build/moko/openmoko) almost change everyday. Update them is important so you can get the latest fix.

$cd /home/build/moko/bitbake-om
$git pull
$cd /home/build/moko/openmoko
$git pull

==Starting use bitbake==
The first time you use bitbake will spend many hours. It have to fetch every source code what you need. To build the meta toolchain, and many basic libraries like glibc.

$source /home/build/moko/build_env #read in the environment variables.
$bitbake helloworld # build the simplest case.
Playing video game for 5 hours, Watching movie for 3 hours and Sleeping for 8 hours.

If you wanna try something like fso image, just ask bitbake to cook another food.

$bitbake fso-image

All the recipe are placed in '''/home/build/moko/openmoko/packages'''. For example, fso-image recipe is placed in '''/home/build/moko/openmoko/packages/images/fso-image.bb'''.

After the building process complete, the opk files are placed in '''/home/build/moko/build/deploy/glibc/opk''', and the image is in '''/home/build/moko/build/deploy/images'''.

BitBake

2009-02-10T02:38:43Z

Cfriedt: /* Get OpenEmbedded tree */

{{Languages|BitBake}}
BitBake is the build tool used by [[OpenEmbedded]]. [[BitBake recipe]]s are simple, declarative files. Here is an example for the openmoko-calculator2 application:

<pre>
DESCRIPTION = "A Calculator for Openmoko"
SECTION = "openmoko/tools"
DEPENDS = "libmokoui2"
PV = "0.1.0+svnr${SRCREV}"
PR = "r0"

inherit openmoko2
</pre>

The user manual is available at the [http://bitbake.berlios.de/manual/ BitBake berlios page].

[[Category:Application Developer]]

==Set Bitbake building environment==
Basically, using bitbake to build your image is very easy.
* Get bitbake
* Get OpenEmbedded tree
* Set local configuare file
* Set building environment variables.
All you need is these four things. Lets assume you are using a account named '''build''', and you are working under directory '''moko'''.

===Get BitBake===

'''Note:''' The instructions below are fairly out of date. It is not actually necessary to use bitbake-om. Any version of BitBake as recent or more recent than 1.8.12 (>=bitbake-1.8.12) is all that is necessary. OpenMoko development is largely moving upstream to the main OpenEmbedded repository. To get started, please follow the instructions available on the [http://wiki.openembedded.net/index.php OpenEmbedded Wiki] under [http://wiki.openembedded.net/index.php/OEandYourDistro OEandYourDistro]. -- [[Cfriedt]] 20090109

$cd ~/moko # Enter the directory
$git clone git://git.openmoko.org/git/bitbake.git bitbake-om # get the bitbake of openmoko.

Bitbake come for OpenEmbedded, however Openmoko has its own bitbake, named [http://git.openmoko.org/?p=bitbake.git;a=summary bitbake-om]. After cloning the bitbake-om, you have the kitchen comprehensive. You also need recipes to tell you how to cook.

===Get OpenEmbedded Tree===

'''Note:''' The instructions below are fairly out of date. To get started with OpenEmbedded, please follow the instructions under [OpenEmbedded]. -- [[User:Cfriedt]] 20090109

$git clone git://git.openmoko.org/git/openmoko.git openmoko

It will clone an [http://git.openmoko.org/?p=openmoko.git;a=summary OE tree from Openmoko git server]. This is the recipes what tell bitbake how to cook. The cloning process spend little time, get a cup of coffee is a good idea when you are waiting.

===Set Local configuare file===

$install -d /home/build/moko/local/conf #create the direcotry
$vim local/conf/local.conf # use your favorite editor

Paste these line into the file
ALLOW_EMPTY = "1"
BBFILES := "/home/build/moko/openmoko/packages/*/*.bb"
BB_GIT_CLONE_FOR_SRCREV = "1"
BBINCLUDELOGS = "yes"
BBMASK = ""
DISTRO = "openmoko"
DL_DIR := "/home/build/moko/sources"
EXTENDPE = ""
GLIBC_GENERATE_LOCALES = "en_US.UTF-8"
IMAGE_FSTYPES = "jffs2 tar.gz"
INHERIT += "om-utils"
MACHINE = "om-gta02"
PARALLEL_MAKE = "-j 4"
QA_LOG = "1"
TMPDIR := "/home/build/moko/build/"

Let me explain the meanings of some variables.
*BBFILES: It tells bitbake where those recipes are.
*DL_DIR: Bitbake fetch source code and put them here.
*MACHINE: I build packages for gta02. If you are going to build for gta01, replace it with "om-gta01"
*PARALLEL_MAKE: Please read the manual of "make" and search the -j option.
*TMPDIR: All of your building result will place here.

===Set building environment variables===

$vim build_env # use your favorite editor

Paste these lines into the file

export BBPATH="/home/build/moko/local:/home/build/moko/openmoko"
export PATH=/home/build/moko/bitbake-om/bin:$PATH

==Update environment==
bitbake-om won't change often. But the OE tree (/home/build/moko/openmoko) almost change everyday. Update them is important so you can get the latest fix.

$cd /home/build/moko/bitbake-om
$git pull
$cd /home/build/moko/openmoko
$git pull

==Starting use bitbake==
The first time you use bitbake will spend many hours. It have to fetch every source code what you need. To build the meta toolchain, and many basic libraries like glibc.

$source /home/build/moko/build_env #read in the environment variables.
$bitbake helloworld # build the simplest case.
Playing video game for 5 hours, Watching movie for 3 hours and Sleeping for 8 hours.

If you wanna try something like fso image, just ask bitbake to cook another food.

$bitbake fso-image

All the recipe are placed in '''/home/build/moko/openmoko/packages'''. For example, fso-image recipe is placed in '''/home/build/moko/openmoko/packages/images/fso-image.bb'''.

After the building process complete, the opk files are placed in '''/home/build/moko/build/deploy/glibc/opk''', and the image is in '''/home/build/moko/build/deploy/images'''.

BitBake

2009-02-10T02:27:36Z

Cfriedt: /* Get BitBake */

{{Languages|BitBake}}
BitBake is the build tool used by [[OpenEmbedded]]. [[BitBake recipe]]s are simple, declarative files. Here is an example for the openmoko-calculator2 application:

<pre>
DESCRIPTION = "A Calculator for Openmoko"
SECTION = "openmoko/tools"
DEPENDS = "libmokoui2"
PV = "0.1.0+svnr${SRCREV}"
PR = "r0"

inherit openmoko2
</pre>

The user manual is available at the [http://bitbake.berlios.de/manual/ BitBake berlios page].

[[Category:Application Developer]]

==Set Bitbake building environment==
Basically, using bitbake to build your image is very easy.
* Get bitbake
* Get OpenEmbedded tree
* Set local configuare file
* Set building environment variables.
All you need is these four things. Lets assume you are using a account named '''build''', and you are working under directory '''moko'''.

===Get BitBake===

'''Note:''' The instructions below are fairly out of date. It is not actually necessary to use bitbake-om. Any version of BitBake as recent or more recent than 1.8.12 (>=bitbake-1.8.12) is all that is necessary. OpenMoko development is largely moving upstream to the main OpenEmbedded repository. To get started, please follow the instructions available on the [http://wiki.openembedded.net/index.php OpenEmbedded Wiki] under [http://wiki.openembedded.net/index.php/OEandYourDistro OEandYourDistro]. -- [[Cfriedt]] 20090109

$cd ~/moko # Enter the directory
$git clone git://git.openmoko.org/git/bitbake.git bitbake-om # get the bitbake of openmoko.

Bitbake come for OpenEmbedded, however Openmoko has its own bitbake, named [http://git.openmoko.org/?p=bitbake.git;a=summary bitbake-om]. After cloning the bitbake-om, you have the kitchen comprehensive. You also need recipes to tell you how to cook.

===Get OpenEmbedded tree===

$git clone git://git.openmoko.org/git/openmoko.git openmoko

It will clone an [http://git.openmoko.org/?p=openmoko.git;a=summary OE tree from Openmoko git server]. This is the recipes what tell bitbake how to cook. The cloning process spend little time, get a cup of coffee is a good idea when you are waiting.

===Set Local configuare file===

$install -d /home/build/moko/local/conf #create the direcotry
$vim local/conf/local.conf # use your favorite editor

Paste these line into the file
ALLOW_EMPTY = "1"
BBFILES := "/home/build/moko/openmoko/packages/*/*.bb"
BB_GIT_CLONE_FOR_SRCREV = "1"
BBINCLUDELOGS = "yes"
BBMASK = ""
DISTRO = "openmoko"
DL_DIR := "/home/build/moko/sources"
EXTENDPE = ""
GLIBC_GENERATE_LOCALES = "en_US.UTF-8"
IMAGE_FSTYPES = "jffs2 tar.gz"
INHERIT += "om-utils"
MACHINE = "om-gta02"
PARALLEL_MAKE = "-j 4"
QA_LOG = "1"
TMPDIR := "/home/build/moko/build/"

Let me explain the meanings of some variables.
*BBFILES: It tells bitbake where those recipes are.
*DL_DIR: Bitbake fetch source code and put them here.
*MACHINE: I build packages for gta02. If you are going to build for gta01, replace it with "om-gta01"
*PARALLEL_MAKE: Please read the manual of "make" and search the -j option.
*TMPDIR: All of your building result will place here.

===Set building environment variables===

$vim build_env # use your favorite editor

Paste these lines into the file

export BBPATH="/home/build/moko/local:/home/build/moko/openmoko"
export PATH=/home/build/moko/bitbake-om/bin:$PATH

==Update environment==
bitbake-om won't change often. But the OE tree (/home/build/moko/openmoko) almost change everyday. Update them is important so you can get the latest fix.

$cd /home/build/moko/bitbake-om
$git pull
$cd /home/build/moko/openmoko
$git pull

==Starting use bitbake==
The first time you use bitbake will spend many hours. It have to fetch every source code what you need. To build the meta toolchain, and many basic libraries like glibc.

$source /home/build/moko/build_env #read in the environment variables.
$bitbake helloworld # build the simplest case.
Playing video game for 5 hours, Watching movie for 3 hours and Sleeping for 8 hours.

If you wanna try something like fso image, just ask bitbake to cook another food.

$bitbake fso-image

All the recipe are placed in '''/home/build/moko/openmoko/packages'''. For example, fso-image recipe is placed in '''/home/build/moko/openmoko/packages/images/fso-image.bb'''.

After the building process complete, the opk files are placed in '''/home/build/moko/build/deploy/glibc/opk''', and the image is in '''/home/build/moko/build/deploy/images'''.

BitBake

2009-02-10T02:26:27Z

Cfriedt: /* Get BitBake */ Updated instructions to reflect that most of the work is being done upstream in OE - see devel@lists.openmoko.org for more info

{{Languages|BitBake}}
BitBake is the build tool used by [[OpenEmbedded]]. [[BitBake recipe]]s are simple, declarative files. Here is an example for the openmoko-calculator2 application:

<pre>
DESCRIPTION = "A Calculator for Openmoko"
SECTION = "openmoko/tools"
DEPENDS = "libmokoui2"
PV = "0.1.0+svnr${SRCREV}"
PR = "r0"

inherit openmoko2
</pre>

The user manual is available at the [http://bitbake.berlios.de/manual/ BitBake berlios page].

[[Category:Application Developer]]

==Set Bitbake building environment==
Basically, using bitbake to build your image is very easy.
* Get bitbake
* Get OpenEmbedded tree
* Set local configuare file
* Set building environment variables.
All you need is these four things. Lets assume you are using a account named '''build''', and you are working under directory '''moko'''.

===Get BitBake===

'''Note:''' The instructions below are fairly out of date. It is not actually necessary to use bitbake-om. Any version of BitBake as recent or more recent than 1.8.12 (>=bitbake-1.8.12) is all that is necessary. Please follow the instructions available on the [http://wiki.openembedded.net/index.php OpenEmbedded Wiki] under [http://wiki.openembedded.net/index.php/OEandYourDistro OEandYourDistro]. -- [[Cfriedt]] 20090109

$cd ~/moko # Enter the directory
$git clone git://git.openmoko.org/git/bitbake.git bitbake-om # get the bitbake of openmoko.

Bitbake come for OpenEmbedded, however Openmoko has its own bitbake, named [http://git.openmoko.org/?p=bitbake.git;a=summary bitbake-om]. After cloning the bitbake-om, you have the kitchen comprehensive. You also need recipes to tell you how to cook.

===Get OpenEmbedded tree===

$git clone git://git.openmoko.org/git/openmoko.git openmoko

It will clone an [http://git.openmoko.org/?p=openmoko.git;a=summary OE tree from Openmoko git server]. This is the recipes what tell bitbake how to cook. The cloning process spend little time, get a cup of coffee is a good idea when you are waiting.

===Set Local configuare file===

$install -d /home/build/moko/local/conf #create the direcotry
$vim local/conf/local.conf # use your favorite editor

Paste these line into the file
ALLOW_EMPTY = "1"
BBFILES := "/home/build/moko/openmoko/packages/*/*.bb"
BB_GIT_CLONE_FOR_SRCREV = "1"
BBINCLUDELOGS = "yes"
BBMASK = ""
DISTRO = "openmoko"
DL_DIR := "/home/build/moko/sources"
EXTENDPE = ""
GLIBC_GENERATE_LOCALES = "en_US.UTF-8"
IMAGE_FSTYPES = "jffs2 tar.gz"
INHERIT += "om-utils"
MACHINE = "om-gta02"
PARALLEL_MAKE = "-j 4"
QA_LOG = "1"
TMPDIR := "/home/build/moko/build/"

Let me explain the meanings of some variables.
*BBFILES: It tells bitbake where those recipes are.
*DL_DIR: Bitbake fetch source code and put them here.
*MACHINE: I build packages for gta02. If you are going to build for gta01, replace it with "om-gta01"
*PARALLEL_MAKE: Please read the manual of "make" and search the -j option.
*TMPDIR: All of your building result will place here.

===Set building environment variables===

$vim build_env # use your favorite editor

Paste these lines into the file

export BBPATH="/home/build/moko/local:/home/build/moko/openmoko"
export PATH=/home/build/moko/bitbake-om/bin:$PATH

==Update environment==
bitbake-om won't change often. But the OE tree (/home/build/moko/openmoko) almost change everyday. Update them is important so you can get the latest fix.

$cd /home/build/moko/bitbake-om
$git pull
$cd /home/build/moko/openmoko
$git pull

==Starting use bitbake==
The first time you use bitbake will spend many hours. It have to fetch every source code what you need. To build the meta toolchain, and many basic libraries like glibc.

$source /home/build/moko/build_env #read in the environment variables.
$bitbake helloworld # build the simplest case.
Playing video game for 5 hours, Watching movie for 3 hours and Sleeping for 8 hours.

If you wanna try something like fso image, just ask bitbake to cook another food.

$bitbake fso-image

All the recipe are placed in '''/home/build/moko/openmoko/packages'''. For example, fso-image recipe is placed in '''/home/build/moko/openmoko/packages/images/fso-image.bb'''.

After the building process complete, the opk files are placed in '''/home/build/moko/build/deploy/glibc/opk''', and the image is in '''/home/build/moko/build/deploy/images'''.

BitBake

2009-02-10T02:24:40Z

Cfriedt: /* Get bitbake */

{{Languages|BitBake}}
BitBake is the build tool used by [[OpenEmbedded]]. [[BitBake recipe]]s are simple, declarative files. Here is an example for the openmoko-calculator2 application:

<pre>
DESCRIPTION = "A Calculator for Openmoko"
SECTION = "openmoko/tools"
DEPENDS = "libmokoui2"
PV = "0.1.0+svnr${SRCREV}"
PR = "r0"

inherit openmoko2
</pre>

The user manual is available at the [http://bitbake.berlios.de/manual/ BitBake berlios page].

[[Category:Application Developer]]

==Set Bitbake building environment==
Basically, using bitbake to build your image is very easy.
* Get bitbake
* Get OpenEmbedded tree
* Set local configuare file
* Set building environment variables.
All you need is these four things. Lets assume you are using a account named '''build''', and you are working under directory '''moko'''.

===Get BitBake===

'''Note:'''' The instructions below are fairly out of date. It is not actually necessary to use bitbake-om. Any version of BitBake as recent or more recent than 1.8.12 (>=bitbake-1.8.12) is all that is necessary. Please follow the instructions available on the [http://wiki.openembedded.net/index.php OpenEmbedded Wiki] under [http://wiki.openembedded.net/index.php/OEandYourDistro OEandYourDistro]. -- [[Cfriedt]] 20090109

$cd ~/moko # Enter the directory
$git clone git://git.openmoko.org/git/bitbake.git bitbake-om # get the bitbake of openmoko.

Bitbake come for OpenEmbedded, however Openmoko has its own bitbake, named [http://git.openmoko.org/?p=bitbake.git;a=summary bitbake-om]. After cloning the bitbake-om, you have the kitchen comprehensive. You also need recipes to tell you how to cook.

===Get OpenEmbedded tree===

$git clone git://git.openmoko.org/git/openmoko.git openmoko

It will clone an [http://git.openmoko.org/?p=openmoko.git;a=summary OE tree from Openmoko git server]. This is the recipes what tell bitbake how to cook. The cloning process spend little time, get a cup of coffee is a good idea when you are waiting.

===Set Local configuare file===

$install -d /home/build/moko/local/conf #create the direcotry
$vim local/conf/local.conf # use your favorite editor

Paste these line into the file
ALLOW_EMPTY = "1"
BBFILES := "/home/build/moko/openmoko/packages/*/*.bb"
BB_GIT_CLONE_FOR_SRCREV = "1"
BBINCLUDELOGS = "yes"
BBMASK = ""
DISTRO = "openmoko"
DL_DIR := "/home/build/moko/sources"
EXTENDPE = ""
GLIBC_GENERATE_LOCALES = "en_US.UTF-8"
IMAGE_FSTYPES = "jffs2 tar.gz"
INHERIT += "om-utils"
MACHINE = "om-gta02"
PARALLEL_MAKE = "-j 4"
QA_LOG = "1"
TMPDIR := "/home/build/moko/build/"

Let me explain the meanings of some variables.
*BBFILES: It tells bitbake where those recipes are.
*DL_DIR: Bitbake fetch source code and put them here.
*MACHINE: I build packages for gta02. If you are going to build for gta01, replace it with "om-gta01"
*PARALLEL_MAKE: Please read the manual of "make" and search the -j option.
*TMPDIR: All of your building result will place here.

===Set building environment variables===

$vim build_env # use your favorite editor

Paste these lines into the file

export BBPATH="/home/build/moko/local:/home/build/moko/openmoko"
export PATH=/home/build/moko/bitbake-om/bin:$PATH

==Update environment==
bitbake-om won't change often. But the OE tree (/home/build/moko/openmoko) almost change everyday. Update them is important so you can get the latest fix.

$cd /home/build/moko/bitbake-om
$git pull
$cd /home/build/moko/openmoko
$git pull

==Starting use bitbake==
The first time you use bitbake will spend many hours. It have to fetch every source code what you need. To build the meta toolchain, and many basic libraries like glibc.

$source /home/build/moko/build_env #read in the environment variables.
$bitbake helloworld # build the simplest case.
Playing video game for 5 hours, Watching movie for 3 hours and Sleeping for 8 hours.

If you wanna try something like fso image, just ask bitbake to cook another food.

$bitbake fso-image

All the recipe are placed in '''/home/build/moko/openmoko/packages'''. For example, fso-image recipe is placed in '''/home/build/moko/openmoko/packages/images/fso-image.bb'''.

After the building process complete, the opk files are placed in '''/home/build/moko/build/deploy/glibc/opk''', and the image is in '''/home/build/moko/build/deploy/images'''.

Android

2008-10-31T04:02:45Z

Cfriedt: /* Source Files in Android that Use the ARMv5TE ISA */

{{Distributions|Android}}

= Updates =

* 20081021 [[User:Cfriedt]] Android -> FreeRunner updates on my [http://perpetual-notion.blogspot.com/search/label/android blog]
* 20081022 [[User:Cfriedt]] I was able to 'trivially' compile all of the Android source code without error for the ARMv4T architecture by removing v5TE instructions. Although it will definitely not run anything predictably, at least now that I know the build system will work with a few simple substitutions in build/core/combo/arm-linux.mk. At this point I am able to go ahead and re-implement v5TE instructions as v4T instruction sequences instead (or re-implement entire sections of assembly with hand-optimized v4T instructions).
* 20081023 [[User:Bricode]] To track the status of which parts of the Android source tree contain ARMv5 specific code, I've created a table of where it is contained, and the status of patches. It can be found at: http://spreadsheets.google.com/pub?key=pzDEXnU19gkeTjpD28t-7fw
* 20081029 [[User:Cfriedt]] [http://benno.id.au Benno] has modified Android's build system so that it will output a JFFS2 image instead of YAFFS . Unlike JFFS2, which [http://64.233.169.104/search?q=cache:e8czlAdKTn0J:gentoo-wiki.com/JFFS2/Mounting+gentoo+jffs2&hl=en&ct=clnk&cd=1&gl=ca&client=firefox-a can be mounted read-only from an image], mounting a YAFFS image is not possible unless it's already been written to flash (it complains about the block device being of type '1' and not 'NAND'). JFFS2 also has the benefit that it's a standard OpenMoko image format (See [[Flashing the Neo FreeRunner]] or [[Flashing the Neo 1973]])

= Introduction =
This page is dedicated to porting the [http://www.android.com Android OS] to the [[Neo 1973]] and [[Neo FreeRunner]] handsets. Since the Android OS was [http://source.android.com/posts/opensource publically released] on 20081021, [http://benno.id.au/blog/2007/11/21/android-neo1973 work] [http://perpetual-notion.blogspot.com/search/label/android is] [http://groups.google.com/group/android-porting currently underway] to port Android to the [[Neo1973 Hardware|Neo 1973]] and [[Neo_FreeRunner_GTA02_Hardware|FreeRunner]] handsets.

== Goals ==
# Systematically introduce patches for ARMv4T in the Android codebase
# Provide Neo1973 and Neo FreeRunner hardware-dependent patches in the Android codebase, leveraging the work already done by the Openmoko developers, without forcing Android-specific changes upstream
# Provide a useable Android filesystem and kernel on the [[Distributions]] page that conform to current Openmoko installation routines

== Early Attempts ==
As [http://benno.id.au Ben Leslie] had pointed out on his [http://benno.id.au/blog/2007/11/21/android-neo1973 blog] far before the source code was released, [http://www.android.com Android] was originally designed to work with the ARMv5TE [http://en.wikipedia.org/wiki/Instruction_set_architecture instruction set architecture] (ISA), which allows for [http://en.wikipedia.org/wiki/ARM_architecture#DSP_Enhancement_Instructions DSP enhanced instructions]. Contrary to the ARMv5TE ISA, the Neo1973 and FreeRunner handsets both feature an arm920t core, which comply to the ARMv4T ISA.

Before the source code was released, kernel trap handlers were implemented to 'emulate' the ARMv5TE ISA. Although the results worked in many cases, trapping is costly and performance suffered as a result. Moreover, without explicitly knowing which conditions were set by various instructions, such as Thumb Mode execution, the result became nondeterministic.

== Current State ==

With the release of the Android [http://source.android.com source code], the Open Source community is no longer limited to dealing with a binary-only product. The Open Handset Alliance (OHA) has let their source code become their product for everyone enrich and benefit from.

Currently, porting efforts are underway in many circles. Patches should be submitted via the [http://source.android.com/submit-patches official Android channels].

To track the status of which parts of the Android source tree contain ARMv5 specific code, I've created a table of where it is contained, and the status of patches. It can be found at: http://spreadsheets.google.com/pub?key=pzDEXnU19gkeTjpD28t-7fw [[User:Bricode]]

[[User:Seanmcneil3|Sean McNeil]] said that he was able to get Androind running (including telephony) in his Freerunner [http://3v1n0.tuxfamily.org/tumblelog/post/368 source].

Ben Leslie mentioned on the android-porting list that he was able to get the 'Android' logo to appear on his Neo 1973.

= How to Help =

== Getting Started ==

You can start by following the instructions to download and build the Android source from scratch. Please see [http://source.android.com/download http://source.android.com/download] and follow the instructions for your architecture.

== Publicize Your Efforts ==

It's generally a good idea to make your efforts known via wiki systems, public mailing lists, forums, and publically open version control systems.

Always take credit for your work but please don't do it in the form of comments. Some code is already hard enough to read without comments polluting the text. The best thing to do is to create a patch and put a header with your information at the top. Collaboration systems such as git might already do this for you (??).

If you create something new and have the ability to designate the license for it, please consider license compatibility issues.

== Porting Strategy ==

* Analysis and leverage of the existing build system
** buid/core/combo/arm-linux.mk
*** -D__ARCH_ARM_4__ -D__ARCH_ARM_4T__
*** -march=armv4t -mcpu=arm920t
** fix various static references to 'armv5'
* Isolating ARMv5TE ISA dependent code
** e.g. grep -n -R -i "${armv5te_isa_pattern}" ~/android
* Abstracting
** ( C/C++ )
*** Use inlined functions / #ifdef statments to implement functions in a portable manner
*** For inlined assembler calls, it's acceptable for now to use generic C code instead, so long as later on we optimize it by hand.
** ( ASM )
*** Proprocessor statements based on ISA / architecture, e.g. #ifdef __ARCH_ARM_5__ ... #endif #ifdef __ARCH_ARM_4__ ... #endif
*** It's highly suggested that preprocessor statements should not be nested (i.e. make them mutually exclusive)
*** Some people have suggested that we should not do #ifdef's based on ARCH or ISA, but rather based on an AndroidConfig.h which would define macros like PLD(...) #ifdef HAVE_ARM_PLD pld #else ... #endif .

For each ARMv5TE instruction, one could potentially
* Implement the instruction using general registers instead of DSP calls (i.e. eabi / softfloat)
* If that is a) nondeterministic, or b) slow, then sections of code need to be analyzed and hand-optimized for the ARMv4T isa

== List of Unsupported Instructions ==

This is a list of opcodes, extracted from the Android source, that are unsupported for ARMv4T compliant processors (specifically the arm920t). The opcodes represent instructions available for ARMv5, ARMv5T, and ARMv5TE architectures, which are not present in the ARMv4T ISA. The list was obtained by exhaustively editing the recompiling the Android source code until it compiled without error.

Please keep in mind, that in some cases, translating these instructions into a sequence of ARMv4T instructions will be impossible and / or result in nondeterministic execution because of
* the requirement of additional context
* the tendencies of certain opcodes to change condition registers that may or may not be present in the arm920t core

=== Opcodes ===

{{scroll box|height=480px|text=
<TABLE BORDER="1">
<TR>
<TH>Opcode</TH>
<TH>Desription</TH>
<TH>[[http://www.arm.com/miscPDFs/14128.pdf PDF]] Page Number</TH>
<TH>C</TH>
<TH>ASM</TH>
</TR>
<TR>
<TH VALIGN="TOP">BLX(1)</TH>
<TD>Branch, Link, and Exchange</TD>
<TD>166</TD>
<TD>N/A (Unused in Android)</TD>
<TD>N/A (Unused in Android)</TD>
</TR>
<TR>
<TH VALIGN="TOP">BLX(2)</TH>
<TD>Branch, Link, and Exchange</TD>
<TD>168</TD>
<TD>
[[User:Cfriedt]] 20081028
Remove from inline assembly with something like
<pre>
#ifdef HAVE_BLX
... (inline asm) ...
#else
... (inline asm with equivalent blx code, as shown to the right) ...
#endif
</pre>
</TD>
<TD>
[[User:Cfriedt]] 20081028
Substitute with a macro reference such as
<pre>
#ifdef HAVE_BLX
#define BLX(a) \
blx a
#else
#define BLX(a) \
mov pc,lr \
bx a
#endif
</pre>
</TD>
</TR>
<TR>
<TH VALIGN="TOP">CLZ</TH>
<TD>Count Leading Zeros</TD>
<TD>175</TD>
<TD>
[[User:Cfriedt]] 20081028
Remove from inline assembly with something like
<pre>
#ifdef HAVE_CLZ
... (inline asm) ...
#else
... (inline asm with equivalent clz code, as shown to the right) ...
#endif
</pre>
</TD>
<TD>
[[User:Cfriedt]] 20081029
<pre>
#ifdef HAVE_CLZ
#define CLZ(Rd,Rm) \
clz Rd,Rm
#else
#define CLZ(Rd,Rm) \
...
#endif
...
CLZ(Rd,Rm)
</pre>
</TD>
</TR>
<TR>
<TH VALIGN="TOP">LDRD</TH>
<TD>Load Registers Doubleword</TD>
<TD>200</TD>
<TD>
[[User:Cfriedt]] 20081028
Substitute different inline assembly code with something like
<pre>
#ifdef HAVE_LDRD
... (inline asm) ...
#else
... (inline asm with ldrd substituted) ...
#endif
</pre>
</TD>
<TD>
[[User:Cfriedt]] 20081028
Substitute with a macro reference such as
<pre>
#ifdef HAVE_LDRD
#define LDRD(a,b) \
ldrd a,b
#else
#define LDRD(a,b) \
...
#endif
</pre>
</TD>
</TR>
<TR>
<TH VALIGN="TOP">PLD</TH>
<TD>Preload Data</TD>
<TD>240</TD>
<TD>
[[User:Cfriedt]] 20081028
Remove from inline assembly with something like
<pre>
#ifdef HAVE_PLD
... (inline asm) ...
#else
... (inline asm with pld removed) ...
#endif
</pre>
</TD>
<TD>
[[User:Cfriedt]] 20081028
Remove or substitute with a macro reference such as
<pre>
#ifdef HAVE_PLD
#define PLD(a,b) \
pld a,b
#else
#define PLD(a,b)
#endif
...
PLD(r0,#0)
</pre>
</TD>
</TR>
<TR>
<TH VALIGN="TOP">SMLA<x><y></TH>
<TD>Signed Multiply-Accumulate</TD>
<TD>291</TD>
<TD></TD>
<TD></TD>
</TR>
<TR>
<TH VALIGN="TOP">SMLAL<x><y></TH>
<TD>Signed Multiply Accumulate Long</TD>
<TD>298</TD>
<TD></TD>
<TD></TD>
</TR>
<TR>
<TH VALIGN="TOP">SMLAW<y></TH>
<TD>Signed Multiply-Accumulate Word</TD>
<TD>302</TD>
<TD></TD>
<TD></TD>
</TR>
<TR>
<TH VALIGN="TOP">SMUL<x><y></TH>
<TD>Signed Multiply</TD>
<TD>316</TD>
<TD></TD>
<TD></TD>
</TR>
<TR>
<TH VALIGN="TOP">SMULW<y></TH>
<TD>Signed Multiply Word</TD>
<TD>320</TD>
<TD></TD>
<TD></TD>
</TR>
<TR>
<TH VALIGN="TOP">QADD</TH>
<TD>Saturating Add</TD>
<TD>242</TD>
<TD></TD>
<TD></TD>
</TR>
<TR>
<TH VALIGN="TOP">QDADD</TH>
<TD>Saturating Double and Add</TD>
<TD>249</TD>
<TD></TD>
<TD></TD>
</TR>
<TR>
<TH VALIGN="TOP">QDSUB</TH>
<TD>Saturating Double and Subtract</TD>
<TD>251</TD>
<TD></TD>
<TD></TD>
</TR>
<TR>
<TH VALIGN="TOP">QSUB</TH>
<TD>Saturating Subtract</TD>
<TD>253</TD>
<TD></TD>
<TD></TD>
</TR>
<TR>
<TH VALIGN="TOP">STRD</TH>
<TD>Store Registers Doubleword</TD>
<TD>349</TD>
<TD>
[[User:Cfriedt]] 20081028
Substitute different inline assembly code with something like
<pre>
#ifdef HAVE_STRD
... (inline asm) ...
#else
... (inline asm without strd) ...
#endif
</pre>
</TD>
<TD>
[[User:Cfriedt]] 20081028
Substitute with a macro reference such as
<pre>
#ifdef HAVE_STRD
#define STRD(a,b) \
strd a,b
#else
#define STRD(a,b) \
...
#endif
</pre>

</TD>
</TR>
</TABLE>
}}

=== Scanning for Files That Use the ARMv5TE ISA ===

Using the above list of opcodes, one can scan the Android source code for ARMv4T-incompatible instruction sequences.

'''Code:'''
{{scroll box|height=240px|text=
<pre>
#!/bin/sh

# $1 is the android directory

if [ $# -ne 1 ]; then
exit -1
fi

cd "${1}"

opcodes="blx clz ldrd pld smlabb smlabt smlatt
smlal smlawb smlawt smulbb smulbt smultt smulwb
smulwt qadd qdadd qdsub qsub strd"

for op in ${opcodes}; do

echo "* ${op} ====================================="

if [ ! -e .files.${op} ]; then

files="$(grep -R -i "${op} " * 2>/dev/null)"
files="$(echo $files | grep -v "^Binary file" | sed -e 's/:.*//')"
files="$(echo $files| grep -v "CREDIT\|README\|^$kernel/\|.git/$\|$\.txt$$" | sort -u)"

echo "${files}" > .files.${op}

else
files="$(cat .files.${op})"
fi

for fil in ${files}; do
lines="$(grep -n -i "${op} " ${fil} | sed -e 's/:.*//g' )"
lines="$(echo $lines | sed -e 's/ /,/g')"
echo "** ${fil}: lines {${lines}}"
done
done
</pre>
}}

=== Source Files in Android that Use the ARMv5TE ISA ===

The list of files below may or may not be complete. There might also be some assembly code that is generated with a python script (verification?).

{{scroll box|height=150px|text=
* blx =====================================
** bionic/libc/tools/gensyscalls.py: lines {168,186}
** bootloader/legacy/nandwrite/init.S: lines {77}
** bootloader/legacy/usbloader/init.S: lines {95}
** dalvik/vm/arch/arm/CallEABI.S: lines {239}
** dalvik/vm/arch/arm/CallOldABI.S: lines {145}
** development/emulator/qtools/thumbdis.cpp: lines {187,265}
** external/qemu/target-arm/translate.c: lines {1151,1971,2444}
** external/qemu/trace.c: lines {774,1353,1358}
** system/core/libpixelflinger/codeflinger/disassem.c: lines {416}
* clz =====================================
** development/emulator/qtools/armdis.cpp: lines {654}
** external/opencore/codecs_v2/audio/aac/dec/src/pv_normalize.h: lines {67,84}
** external/opencore/codecs_v2/audio/gsm_amr/amr_nb/common/include/norm_l.h: lines {137}
** external/opencore/codecs_v2/audio/gsm_amr/amr_wb/dec/src/normalize_amr_wb.h: lines {78,95}
** external/opencore/codecs_v2/audio/mp3/dec/src/pvmp3_normalize.h: lines {67,84}
** external/opencore/codecs_v2/video/avc_h264/dec/src/vlc.cpp: lines {23}
** external/opencore/codecs_v2/video/m4v_h263/enc/src/vlc_encode_inline.h: lines {125,162,168,204,218}
** external/qemu/target-arm/translate.c: lines {1247}
** external/skia/libcorecg/Sk64.cpp: lines {340,341,343}
** external/skia/libcorecg/SkMatrix.cpp: lines {500,501}
** external/skia/libsgl/effects/SkColorMatrixFilter.cpp: lines {135}
** external/skia/libsgl/sgl/SkBitmap.cpp: lines {945,946,947}
** external/skia/libsgl/sgl/SkBitmapShader.cpp: lines {32,33,34}
** external/skia/libsgl/sgl/SkGraphics.cpp: lines {429,437}
* ldrd =====================================
** dalvik/vm/mterp/armv5/OP_AGET_WIDE.S: lines {28}
** dalvik/vm/mterp/armv5/OP_IGET_WIDE.S: lines {37}
** dalvik/vm/mterp/armv5/OP_IGET_WIDE_QUICK.S: lines {10}
** dalvik/vm/mterp/armv5/OP_SGET_WIDE.S: lines {17}
** dalvik/vm/mterp/out/InterpAsm-armv5.S: lines {2653,7464,8318,8390}
** system/core/libpixelflinger/rotate90CW_4x4_16v6.S: lines {40,41,42,43}
* pld =====================================
** bionic/libc/arch-arm/bionic/memcmp.S: lines {37,44,45,56,57,107,108,195,196}
** bionic/libc/arch-arm/bionic/memcmp16.S: lines {37,44,45,67,68,116,117,198,199}
** bionic/libc/arch-arm/bionic/memcpy.S: lines {55,56,57,145,266,293,320}
** bionic/libc/arch-arm/bionic/strlen.c: lines {59,65}
** bionic/libc/kernel/arch-arm/asm/arch/irqs.h: lines {162}
** external/elfutils/src/Makefile: lines {243}
** external/elfutils/src/Makefile.am: lines {32}
** external/elfutils/src/Makefile.in: lines {243}
** external/jpeg/jidctfst.S: lines {69,235,247}
** external/qemu/target-arm/translate.c: lines {1149}
** system/core/libpixelflinger/codeflinger/ARMAssembler.cpp: lines {368}
** system/core/libpixelflinger/codeflinger/ARMAssemblerInterface.cpp: lines {104,108,117}
** system/core/libpixelflinger/t32cb16blend.S: lines {111,112,134,143}
* smlabb =====================================
** external/jpeg/jidctfst.S: lines {110,115,155,156}
** external/neven/Embedded/common/src/b_BasicEm/Math.c: lines {584,589}
** external/opencore/codecs_v2/audio/aac/dec/src/fxp_mul32_arm_gcc.h: lines {147,166}
** external/opencore/codecs_v2/audio/aac/dec/src/fxp_mul32_arm_v5.h: lines {120,129}
** external/opencore/codecs_v2/audio/gsm_amr/amr_nb/common/include/basic_op_arm_gcc_v5.h: lines {514,533}
** external/opencore/codecs_v2/audio/gsm_amr/amr_nb/common/include/basic_op_arm_v5.h: lines {418,429}
** external/opencore/codecs_v2/audio/gsm_amr/amr_wb/dec/src/pvamrwbdecoder_basic_op_armv5.h: lines {202}
** external/opencore/codecs_v2/audio/gsm_amr/amr_wb/dec/src/pvamrwbdecoder_basic_op_gcc_armv5.h: lines {250}
** external/opencore/codecs_v2/video/m4v_h263/enc/src/dct_inline.h: lines {119,155,167,278,326,341}
** external/opencore/codecs_v2/video/m4v_h263/enc/src/fastquant_inline.h: lines {178,225,437,517}
** frameworks/base/libs/audioflinger/AudioMixer.cpp: lines {405,436}
* smlabt =====================================
** external/opencore/codecs_v2/audio/aac/dec/src/fxp_mul32_arm_gcc.h: lines {184}
** external/opencore/codecs_v2/audio/aac/dec/src/fxp_mul32_arm_v5.h: lines {138}
** external/opencore/codecs_v2/video/m4v_h263/enc/src/dct_inline.h: lines {131,143,294,310}
* smlatt =====================================
** external/neven/Embedded/common/src/b_BasicEm/Math.c: lines {585,590}
** external/opencore/codecs_v2/audio/aac/dec/src/fxp_mul32_arm_v5.h: lines {157}
** frameworks/base/libs/audioflinger/AudioMixer.cpp: lines {441}
* smlal =====================================
** external/opencore/codecs_v2/audio/aac/dec/src/fxp_mul32_arm_v4.h: lines {179,223,236,257,267}
** external/opencore/codecs_v2/audio/aac/dec/src/fxp_mul32_arm_v4_gcc.h: lines {264,341}
** external/opencore/codecs_v2/audio/aac/dec/src/fxp_mul32_arm_v5.h: lines {178,188,198}
** external/opencore/codecs_v2/audio/mp3/dec/src/asm/pvmp3_dct_9.s: lines {84,90,96,101,109,114,116,118,121,132,138,150,163,165,167,174,176,178}
** external/opencore/codecs_v2/audio/mp3/dec/src/asm/pvmp3_dct_9_gcc.s: lines {73,79,86,90,98,103,105,107,110,121,127,139,152,154,156,163,165,167}
** external/opencore/codecs_v2/audio/mp3/dec/src/asm/pvmp3_mdct_18.asm: lines {143,162,178,188,192,199,207,217,225,231,237,241,244}
** external/opencore/codecs_v2/audio/mp3/dec/src/asm/pvmp3_mdct_18.s: lines {145,164,180,190,194,201,209,219,227,233,239,243,246}
** external/opencore/codecs_v2/audio/mp3/dec/src/asm/pvmp3_mdct_18_gcc.s: lines {143,162,178,188,192,199,207,217,225,231,237,241,244}
** external/opencore/codecs_v2/audio/mp3/dec/src/asm/pvmp3_polyphase_filter_window.asm: lines {62,63,66,72,76,77,81,82,85,90,94,97,99,100,103,108,113,114,118,119,122,129,136,137,176,179,183,187,190,193}
** external/opencore/codecs_v2/audio/mp3/dec/src/asm/pvmp3_polyphase_filter_window.s: lines {67,68,71,77,81,82,86,87,90,95,99,102,104,105,108,113,118,119,123,124,127,134,141,142,181,184,188,192,195,198}
** external/opencore/codecs_v2/audio/mp3/dec/src/asm/pvmp3_polyphase_filter_window_gcc.s: lines {65,66,69,75,79,80,84,85,88,93,97,100,102,103,106,111,116,117,121,122,125,132,139,140,179,182,186,190,193,196}
** external/opencore/codecs_v2/audio/mp3/dec/src/pv_mp3dec_fxd_op_arm.h: lines {148}
** external/qemu/trace.c: lines {813}
** frameworks/base/opengl/libagl/iterators.S: lines {66,67}
** frameworks/base/opengl/libagl/matrix.h: lines {67,68,96,126,127,282,283,314,315,316}
* smlawb =====================================
** external/opencore/codecs_v2/audio/aac/dec/src/fxp_mul32_arm_gcc.h: lines {203,259}
** external/opencore/codecs_v2/audio/aac/dec/src/fxp_mul32_arm_v5.h: lines {166,416}
** frameworks/base/libs/audioflinger/AudioResamplerSinc.cpp: lines {93,109}
** frameworks/base/opengl/libagl/matrix.h: lines {163,203}
* smlawt =====================================
** frameworks/base/libs/audioflinger/AudioResamplerSinc.cpp: lines {114}
** frameworks/base/opengl/libagl/matrix.h: lines {162,202,243,244}
* smulbb =====================================
** external/jpeg/jidctfst.S: lines {109,114,151,153}
** external/opencore/codecs_v2/audio/aac/dec/src/fxp_mul32_arm_gcc.h: lines {79}
** external/opencore/codecs_v2/audio/aac/dec/src/fxp_mul32_arm_v5.h: lines {71,81}
** external/opencore/codecs_v2/audio/gsm_amr/amr_nb/common/include/basic_op_arm_gcc_v5.h: lines {207,251,297,348,361,375,427,440,487}
** external/opencore/codecs_v2/audio/gsm_amr/amr_nb/common/include/basic_op_arm_v5.h: lines {199,234,274,314,316,326,367,369,404}
** external/opencore/codecs_v2/audio/gsm_amr/amr_nb/common/include/l_mac.h: lines {121,137}
** external/opencore/codecs_v2/audio/gsm_amr/amr_nb/common/include/l_msu.h: lines {123,142}
** external/opencore/codecs_v2/audio/gsm_amr/amr_nb/common/include/l_mult.h: lines {122,140}
** external/opencore/codecs_v2/audio/gsm_amr/amr_nb/common/include/mpy_32.h: lines {132,134,138,164,177,191}
** external/opencore/codecs_v2/audio/gsm_amr/amr_nb/common/include/mpy_32_16.h: lines {127,129,150,163}
** external/opencore/codecs_v2/audio/gsm_amr/amr_nb/common/include/mult.h: lines {121,141}
** external/opencore/codecs_v2/audio/gsm_amr/amr_wb/dec/src/pvamrwbdecoder_basic_op_armv5.h: lines {115,139,151,163,189,190,212}
** external/opencore/codecs_v2/audio/gsm_amr/amr_wb/dec/src/pvamrwbdecoder_basic_op_gcc_armv5.h: lines {112,113,164,183,201,218,265}
** external/opencore/codecs_v2/video/m4v_h263/enc/src/fastquant_inline.h: lines {250,457,531}
** external/skia/include/corecg/SkMath.h: lines {170}
** frameworks/base/libs/audioflinger/AudioMixer.cpp: lines {420,462}
** system/core/libpixelflinger/t32cb16blend.S: lines {39,66,74,82}
* smulbt =====================================
** external/opencore/codecs_v2/audio/aac/dec/src/fxp_mul32_arm_gcc.h: lines {115}
** external/opencore/codecs_v2/audio/aac/dec/src/fxp_mul32_arm_v5.h: lines {109}
** system/core/libpixelflinger/codeflinger/texturing.cpp: lines {1091}
** system/core/libpixelflinger/t32cb16blend.S: lines {47,55}
* smultt =====================================
** external/opencore/codecs_v2/audio/aac/dec/src/fxp_mul32_arm_gcc.h: lines {131}
** external/opencore/codecs_v2/audio/aac/dec/src/fxp_mul32_arm_v5.h: lines {100}
** frameworks/base/libs/audioflinger/AudioMixer.cpp: lines {467}
** frameworks/base/libs/audioflinger/AudioResamplerSinc.cpp: lines {73}
* smulwb =====================================
** external/opencore/codecs_v2/audio/aac/dec/src/fxp_mul32_arm_gcc.h: lines {221}
** external/opencore/codecs_v2/audio/aac/dec/src/fxp_mul32_arm_v5.h: lines {373}
** external/opencore/codecs_v2/audio/gsm_amr/amr_wb/dec/src/pvamrwbdecoder_basic_op_armv5.h: lines {222}
** external/opencore/codecs_v2/audio/gsm_amr/amr_wb/dec/src/pvamrwbdecoder_basic_op_gcc_armv5.h: lines {283}
** external/opencore/codecs_v2/audio/sbc/enc/src/sbcenc_filter.h: lines {33}
** frameworks/base/opengl/libagl/matrix.h: lines {161,201,242}
* smulwt =====================================
** external/opencore/codecs_v2/audio/aac/dec/src/fxp_mul32_arm_gcc.h: lines {202,240}
** external/opencore/codecs_v2/audio/aac/dec/src/fxp_mul32_arm_v5.h: lines {385,415}
* qadd =====================================
** external/opencore/codecs_v2/audio/aac/dec/src/fxp_mul32_arm_gcc.h: lines {64}
** external/opencore/codecs_v2/audio/aac/dec/src/fxp_mul32_arm_v5.h: lines {60}
** external/opencore/codecs_v2/audio/gsm_amr/amr_nb/common/include/basic_op_arm_gcc_v5.h: lines {130,256}
** external/opencore/codecs_v2/audio/gsm_amr/amr_nb/common/include/basic_op_arm_v5.h: lines {128,235}
** external/opencore/codecs_v2/audio/gsm_amr/amr_nb/common/include/l_add.h: lines {122,137}
** external/opencore/codecs_v2/audio/gsm_amr/amr_nb/common/include/l_mult.h: lines {123,145}
** external/opencore/codecs_v2/audio/gsm_amr/amr_wb/dec/src/pvamrwbdecoder_basic_op_armv5.h: lines {71,102,152,176,192}
** external/opencore/codecs_v2/audio/gsm_amr/amr_wb/dec/src/pvamrwbdecoder_basic_op_gcc_armv5.h: lines {91,115,148,202,234}
** external/openssl/crypto/bn/bn_prime.c: lines {454,455}
* qdadd =====================================
** external/opencore/codecs_v2/audio/aac/dec/src/calc_sbr_synfilterbank.cpp: lines {116,162}
** external/opencore/codecs_v2/audio/aac/dec/src/trans4m_freq_2_time_fxp.cpp: lines {472,494}
** external/opencore/codecs_v2/audio/gsm_amr/amr_nb/common/include/basic_op_arm_gcc_v5.h: lines {212,356,370,385,435,449}
** external/opencore/codecs_v2/audio/gsm_amr/amr_nb/common/include/basic_op_arm_v5.h: lines {200,315,321,331,368,371}
** external/opencore/codecs_v2/audio/gsm_amr/amr_nb/common/include/l_mac.h: lines {122,142}
** external/opencore/codecs_v2/audio/gsm_amr/amr_nb/common/include/mpy_32.h: lines {133,136,140,172,186,201}
** external/opencore/codecs_v2/audio/gsm_amr/amr_nb/common/include/mpy_32_16.h: lines {128,131,158,172}
** external/opencore/codecs_v2/audio/gsm_amr/amr_wb/dec/src/pvamrwbdecoder_basic_op_armv5.h: lines {116}
** external/opencore/codecs_v2/audio/gsm_amr/amr_wb/dec/src/pvamrwbdecoder_basic_op_gcc_armv5.h: lines {184}
* qdsub =====================================
** external/opencore/codecs_v2/audio/gsm_amr/amr_nb/common/include/basic_op_arm_gcc_v5.h: lines {302}
** external/opencore/codecs_v2/audio/gsm_amr/amr_nb/common/include/basic_op_arm_v5.h: lines {275}
** external/opencore/codecs_v2/audio/gsm_amr/amr_nb/common/include/l_msu.h: lines {124,147}
** external/opencore/codecs_v2/audio/gsm_amr/amr_wb/dec/src/pvamrwbdecoder_basic_op_armv5.h: lines {140}
** external/opencore/codecs_v2/audio/gsm_amr/amr_wb/dec/src/pvamrwbdecoder_basic_op_gcc_armv5.h: lines {165}
* qsub =====================================
** external/opencore/codecs_v2/audio/gsm_amr/amr_nb/common/include/basic_op_arm_gcc_v5.h: lines {167}
** external/opencore/codecs_v2/audio/gsm_amr/amr_nb/common/include/basic_op_arm_v5.h: lines {162}
** external/opencore/codecs_v2/audio/gsm_amr/amr_nb/common/include/l_sub.h: lines {121,138}
** external/opencore/codecs_v2/audio/gsm_amr/amr_wb/dec/src/pvamrwbdecoder_basic_op_armv5.h: lines {88,127}
** external/opencore/codecs_v2/audio/gsm_amr/amr_wb/dec/src/pvamrwbdecoder_basic_op_gcc_armv5.h: lines {70,133}
* strd =====================================
** dalvik/vm/mterp/armv5/OP_APUT_WIDE.S: lines {31}
** dalvik/vm/mterp/armv5/OP_IPUT_WIDE.S: lines {39}
** dalvik/vm/mterp/armv5/OP_IPUT_WIDE_QUICK.S: lines {14}
** dalvik/vm/mterp/armv5/OP_SPUT_WIDE.S: lines {21}
** dalvik/vm/mterp/out/InterpAsm-armv5.S: lines {2834,7530,8331,8542}
** dalvik/vm/oo/Object.h: lines {589}
** external/opencore/fileformats/avi/parser/include/pv_avifile_streamlist.h: lines {179}
** external/opencore/fileformats/avi/parser/src/pv_avifile_streamlist.cpp: lines {153}
** system/core/libpixelflinger/rotate90CW_4x4_16v6.S: lines {47,52,56,60}
}}

=== Discussion ===
=== Notes ===
The file
<pre>
system/core/libpixelflinger/codeflinger/ARMAssembler.cpp
</pre>

will need special attention. It's responsible for dynamic generation of DSP code.

== Suggestions ==
* [[User:Cfriedt]] 20081024 I'm not sure how feasible this is, given that the [http://wiki.openmoko.org/wiki/Neo_FreeRunner_Hardware_Issues#SMedia_3362_Documentation_.26_OpenGL_ES_Drivers SMedia 3362 is heavily NDA'd]. However, since the arm920t lacks a floating-point unit / DSP core, is it possible to use the SMedia chip for general-purpose math? This would help in the Android platform, at least, for things like audio and video codecs. Aside from an OpenGL ES driver, OpenMoko documentation for the SMedia would be highly appreciated.

= Important Links =
(Please Update Me)

== Documentation ==
* [http://source.android.com/documentation Android Documentation]
* [http://www.arm.com/documentation/ ARM Documentation], (keywords: armv4t, armv5t, armv5te, arm920t, arm926ej-s)
* [http://www.arm.com/miscPDFs/9658.pdf ARM Assembly Language Programming]
* [http://www.cse.unsw.edu.au/~cs3221/labs/assembler-intro.pdf An Introduction to the GNU Assembler]
* [http://www.heyrick.co.uk/assembler/apcsintro.html ARM Procedure Call Standard], [http://en.wikipedia.org/wiki/Calling_convention#ARM ARM Calling Conventions]

== Instruction Set References ==
* [http://www.arm.com/miscPDFs/14128.pdf ARM Architecture Reference Manual], The definitive ISA documentation
* [http://www.simplemachines.it/doc/QRC0001H_rvct_v2.1_arm.pdf ARM Instruction Set Quick Reference Card]
* [http://infocenter.arm.com/help/topic/com.arm.doc.qrc0001l/QRC0001_UAL.pdf ARM and Thumb -2 Instruction Set Quick Reference Card]
* [http://infocenter.arm.com/help/topic/com.arm.doc.dvi0025b/DVI0025.pdf ARMv4T] (See section 1.4.13)
* [http://infocenter.arm.com/help/topic/com.arm.doc.dvi0014a/DVI0014A_ARM10T_PO.pdf ARMv5T] (See section 4.16)
* [http://www.arm.com/pdfs/ARM-DSP.pdf ARM DSP Enhanced Instruction Set]
* [http://infocenter.arm.com/help/topic/com.arm.doc.ihi0042c/IHI0042C_aapcs.pdf Procedure Call Standard for the ARM Architecture]

== Hardware Reference ==

* [[Neo1973 Hardware]]
* [[Neo FreeRunner GTA02 Hardware]]

== Communities ==
* [http://source.android.com/discuss Android Public Mailing Lists]
** Specifically, [http://groups.google.com/group/android-porting android-porting]
* [http://lists.openmoko.org/mailman/listinfo OpenMoko Mailing Lists]
** Specifically, [http://lists.openmoko.org/mailman/listinfo/openmoko-kernel openmoko-kernel]
* [http://forum.koolu.org/viewforum.php?f=10 Android on FreeRunner] at KoolU.com
* [[Openmoko Local Groups]]
* [[Openmoko:Community_Portal]]

= See also =

* [[Debug_Board]]

= External Links =

[[Category:Distributions]]