Introduction

A toolchain is a set of tools that allows you to compile code. For Openmoko, we have to differentiate between the following use-cases:

(a) Developing a single application

For this, you should use a prebuilt toolchain from the Openmoko project. On this page you can find a recipe to get started with this toolchain leading you through a series of steps to compile a project and run it on your target device. (You might have heard about OpenEmbedded, however as an application programmer, you should not be using OpenEmbedded.)

(b) System Integration and customizing a distribution

For this task, you should use OpenEmbedded which builds its own cross compiler during the bootstrapping/build process. System Integration and customizing a distribution is out of scope of this page.

Basic toolchain usage

Prerequisites

You should be reasonably familiar with Linux and its command line tools, have an x86-compatible computer with at least 1G of free disk space. You should have experience with compiling programs from source using your local compiler. The remainder of this document will also assume you have write access in your home directory (~) and /usr/local/ (becoming root if needed). If any of this is not the case, please call your local administrator for help.

Last but not least you should have a working setup that allows you to compile native software packages using the autotools build system (the triade of ./configure, make, make install).

A (partial) list of required packages -- please append as necessary:

For most Linux version you might only need to install the packages

autoconf, automake

binutils, gcc, gcc-c++

libtool

ccache

intltool

For Ubuntu 8.04 ( Previous versions don't support libmokoui2 ) the following is required:

The prebuilt toolchain is for x86_64 or i686. If you wanted, you could build it on your own with OE:

bitbake meta-toolchain-openmoko

Finally, everytime you want to use this toolchain, you need to alter some environment variables, so that your tools will be found. The toolchain provides a script to do that, so the only thing you need to do is to source it.
Note that if you are not using a "sh" or "bash" shell (check with "echo $SHELL") that you need
to start "sh" or "bash" first.

. /usr/local/openmoko/arm/setup-env

At least, you should add /usr/local/openmoko/arm/bin to your $PATH variable, otherwise the next steps won't work (om-conf and make).

export PATH=$PATH:/usr/local/openmoko/arm/bin
Note: This is will only last for your current session. Add it to your shell startup scripts to make it permenant (~/.bashrc for instance).

Installing New Libraries

Openmoko toolchain didn't include many libraries in default. However, it can download and install library what has already existed in Openmoko repository. (It refer to Testing Repository by default.)

You need to alter some environment variables before you download libraries.

. /usr/local/openmoko/arm/environment-setup

First, update the opkg database (Notice, you should use alias opkg-target but not opkg)

opkg-target update

Second, select a package what you want. Let's use edje as an example. If you want develop an project which use edje of Enlightenment, you can use opkg-target list to print out how many packages you can have. Of course, command grep will help you a lot.(Remember, you should install -dev package but not only libedje.)

opkg-target list |grep edje-dev

Third, install it

opkg-target install libedje-dev

Fourth, have a cup of coffee and wait.

Building a sample project

In a chosen destination directory (in this example ~/):

copy the downloaded sample application source:

cp -r /usr/local/openmoko/source/openmoko-sample2 ~/

Remember to set the proper environment variables (again with "sh" or "bash") for openmoko:

. /usr/local/openmoko/arm/setup-env

You need to create a build configuration for this application. This also checks if all needed libraries, tools, etc.. is available on your system. If this fails see the notes about the needed packages in the section "Prerequisites" mentioned earlier.

om-conf openmoko-sample2

Optionally now you can modify the source code in openmoko-sample2/src. Before the next step, go into the sample directory.

cd openmoko-sample2

If you are using an older version of the toolchain, you may have to create the makefile by running "./autogen.sh". Otherwise, to build the application from the source code just type:

make

If there are errors (i.e. "You need to install gnome-common from the GNOME CVS") deal with them. Also see "Troubleshooting" section at the end of this page for known issues.

If you want to install this project on host for staging usage later, a shared library, for example, you can do the following to install it into a given configured prefix.
om-conf --prefix=/usr/local/openmoko openmoko-sample2
cd openmoko-sample2
make install

How to create your own project from the sample project

In order to build your own project by using openmoko-sample2 files, some changes are needed:

copy the downloaded sample application source

cp -r /usr/local/openmoko/source/openmoko-sample2 ~/

rename the folder with the name of your project (in this example your-project-name) and delete old sample files

be sure to put instead of main.c all your .c and .h files and modify all the '-' characters with '_' in the variable names

Packaging your application

We have included a script to make an ipkg out of your application. Note that this is not needed to test your application on the Neo (for that you can just scp the resulting binary and data over), however it's very handy if you want to distribute your application to others.

om-make-ipkg openmoko-sample2

Now you got openmoko-sample2_0.1_armv4t.ipk , you can `scp' it to your
Neo and install it:

Note that while you can redistribute the generated ipkg, be aware that this is a bare-bones ipk that contains no further information, i.e. you will lack library dependencies. See below how to fix this.

You can also supply the version number, a description, and an author / contacts string in a control file:

Advanced topics

Building Openmoko Kernel from git repo using Toolchain

Will fail with error message "arm-angstrom-linux-gnueabi-ld: unrecognized option '-Wl,-rpath-link,/usr/local/openmoko/arm/arm-angstrom-linux-gnueabi/lib'" until /usr/local/openmoko/arm/setup-env is modified. LDFLAGS should be changed from:

I also had to change the 'build' script to hardcode the path to the compiler.

Using toolchain provided libraries

Add the necessary libraries to the _LDADD field in src/Makefile.am, for example:
openmoko_sample2_LDADD = @DEPENDENCIES_LIBS@ -lmokogsmd2

make sure to run om-conf again after this.

Installing additional libraries into the toolchain

Sooner or later you will want to compile an application that has dependencies which can't be fulfilled by the precompiled toolchain, e.g. some obscure libraries.

In that case, feel free to request the inclusion of additional libraries into the next release of the Openmoko toolchain. Until then, here is how you enhance your already installed toolchain. Say, we want to add the library called liburiparse:

Troubleshooting

Some Versions of the Toolchain have corrupt .la files. If you compile an application using the Toolchain and you receive a '/space/fic/openmoko-daily/neo1973/work/armv4t-angstrom-linux-gnueabi/pango-1.18.3-r0/pango-1.18.3/pango/libpangoft2-1.0.la' error, you are affected. To fix that you should go to your "/usr/local/openmoko/arm/arm-angstrom-linux-gnueabi/usr/lib" directory and open the affected .la files and change "/space/fic..." to "/usr/local/openmoko/arm/arm-angstrom-linux-gnueabi/usr/lib". You have to fix more than one .la file. For the pango error you have to change "libpangocairo-1.0.la", but there are more corrupt .la files.

Attached is a beta fix for the .la problem. Untar the .tar.bz2 as root, and execute the following bash script as root:

Introduction

A toolchain is a set of tools that allows you to compile code. For Openmoko, we have to differentiate between the following use-cases:

(a) Developing a single application

For this, you should use a prebuilt toolchain from the Openmoko project. On this page you can find a recipe to get started with this toolchain leading you through a series of steps to compile a project and run it on your target device. (You might have heard about OpenEmbedded, however as an application programmer, you should not be using OpenEmbedded.)

(b) System Integration and customizing a distribution

For this task, you should use OpenEmbedded which builds its own cross compiler during the bootstrapping/build process. System Integration and customizing a distribution is out of scope of this page.

Basic toolchain usage

Prerequisites

You should be reasonably familiar with Linux and its command line tools, have an x86-compatible computer with at least 1G of free disk space. You should have experience with compiling programs from source using your local compiler. The remainder of this document will also assume you have write access in your home directory (~) and /usr/local/ (becoming root if needed). If any of this is not the case, please call your local administrator for help.

Last but not least you should have a working setup that allows you to compile native software packages using the autotools build system (the triade of ./configure, make, make install).

A (partial) list of required packages -- please append as necessary:

For most Linux version you might only need to install the packages

autoconf, automake

binutils, gcc, gcc-c++

libtool

ccache

intltool

For Ubuntu 8.04 ( Previous versions don't support libmokoui2 ) the following is required:

The prebuilt toolchain is for x86_64 or i686. If you wanted, you could build it on your own with OE:

bitbake meta-toolchain-openmoko

Finally, everytime you want to use this toolchain, you need to alter some environment variables, so that your tools will be found. The toolchain provides a script to do that, so the only thing you need to do is to source it.
Note that if you are not using a "sh" or "bash" shell (check with "echo $SHELL") that you need
to start "sh" or "bash" first.

. /usr/local/openmoko/arm/setup-env

At least, you should add /usr/local/openmoko/arm/bin to your $PATH variable, otherwise the next steps won't work (om-conf and make).

export PATH=$PATH:/usr/local/openmoko/arm/bin
Note: This is will only last for your current session. Add it to your shell startup scripts to make it permenant (~/.bashrc for instance).

Installing New Libraries

Openmoko toolchain didn't include many libraries in default. However, it can download and install library what has already existed in Openmoko repository. (It refer to Testing Repository by default.)

You need to alter some environment variables before you download libraries.

. /usr/local/openmoko/arm/environment-setup

First, update the opkg database (Notice, you should use alias opkg-target but not opkg)

opkg-target update

Second, select a package what you want. Let's use edje as an example. If you want develop an project which use edje of Enlightenment, you can use opkg-target list to print out how many packages you can have. Of course, command grep will help you a lot.(Remember, you should install -dev package but not only libedje.)

opkg-target list |grep edje-dev

Third, install it

opkg-target install libedje-dev

Fourth, have a cup of coffee and wait.

Building a sample project

In a chosen destination directory (in this example ~/):

copy the downloaded sample application source:

cp -r /usr/local/openmoko/source/openmoko-sample2 ~/

Remember to set the proper environment variables (again with "sh" or "bash") for openmoko:

. /usr/local/openmoko/arm/setup-env

You need to create a build configuration for this application. This also checks if all needed libraries, tools, etc.. is available on your system. If this fails see the notes about the needed packages in the section "Prerequisites" mentioned earlier.

om-conf openmoko-sample2

Optionally now you can modify the source code in openmoko-sample2/src. Before the next step, go into the sample directory.

cd openmoko-sample2

If you are using an older version of the toolchain, you may have to create the makefile by running "./autogen.sh". Otherwise, to build the application from the source code just type:

make

If there are errors (i.e. "You need to install gnome-common from the GNOME CVS") deal with them. Also see "Troubleshooting" section at the end of this page for known issues.

If you want to install this project on host for staging usage later, a shared library, for example, you can do the following to install it into a given configured prefix.
om-conf --prefix=/usr/local/openmoko openmoko-sample2
cd openmoko-sample2
make install

How to create your own project from the sample project

In order to build your own project by using openmoko-sample2 files, some changes are needed:

copy the downloaded sample application source

cp -r /usr/local/openmoko/source/openmoko-sample2 ~/

rename the folder with the name of your project (in this example your-project-name) and delete old sample files

be sure to put instead of main.c all your .c and .h files and modify all the '-' characters with '_' in the variable names

Packaging your application

We have included a script to make an ipkg out of your application. Note that this is not needed to test your application on the Neo (for that you can just scp the resulting binary and data over), however it's very handy if you want to distribute your application to others.

om-make-ipkg openmoko-sample2

Now you got openmoko-sample2_0.1_armv4t.ipk , you can `scp' it to your
Neo and install it:

Note that while you can redistribute the generated ipkg, be aware that this is a bare-bones ipk that contains no further information, i.e. you will lack library dependencies. See below how to fix this.

You can also supply the version number, a description, and an author / contacts string in a control file:

Advanced topics

Building Openmoko Kernel from git repo using Toolchain

Will fail with error message "arm-angstrom-linux-gnueabi-ld: unrecognized option '-Wl,-rpath-link,/usr/local/openmoko/arm/arm-angstrom-linux-gnueabi/lib'" until /usr/local/openmoko/arm/setup-env is modified. LDFLAGS should be changed from:

I also had to change the 'build' script to hardcode the path to the compiler.

Using toolchain provided libraries

Add the necessary libraries to the _LDADD field in src/Makefile.am, for example:
openmoko_sample2_LDADD = @DEPENDENCIES_LIBS@ -lmokogsmd2

make sure to run om-conf again after this.

Installing additional libraries into the toolchain

Sooner or later you will want to compile an application that has dependencies which can't be fulfilled by the precompiled toolchain, e.g. some obscure libraries.

In that case, feel free to request the inclusion of additional libraries into the next release of the Openmoko toolchain. Until then, here is how you enhance your already installed toolchain. Say, we want to add the library called liburiparse:

Troubleshooting

Some Versions of the Toolchain have corrupt .la files. If you compile an application using the Toolchain and you receive a '/space/fic/openmoko-daily/neo1973/work/armv4t-angstrom-linux-gnueabi/pango-1.18.3-r0/pango-1.18.3/pango/libpangoft2-1.0.la' error, you are affected. To fix that you should go to your "/usr/local/openmoko/arm/arm-angstrom-linux-gnueabi/usr/lib" directory and open the affected .la files and change "/space/fic..." to "/usr/local/openmoko/arm/arm-angstrom-linux-gnueabi/usr/lib". You have to fix more than one .la file. For the pango error you have to change "libpangocairo-1.0.la", but there are more corrupt .la files.

Attached is a beta fix for the .la problem. Untar the .tar.bz2 as root, and execute the following bash script as root: