Toolchain

From Openmoko

(Difference between revisions)
Jump to: navigation, search
(Packaging your application)
Line 11: Line 11:
 
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.
 
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.
  
= Prerequisites =  
+
=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 <tt>/usr/local/</tt>. If this is not the case, please call your local administrator for help.
 
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 <tt>/usr/local/</tt>. If this is not the case, please call your local administrator for help.
Line 23: Line 25:
 
** ccache
 
** ccache
  
=Downloading and installing =
+
==Downloading and installing==
  
 
The prebuilt toolchain can be downloaded from [[http://downloads.openmoko.org/toolchains downloads.openmoko.org]]:
 
The prebuilt toolchain can be downloaded from [[http://downloads.openmoko.org/toolchains downloads.openmoko.org]]:
Line 48: Line 50:
 
  source /usr/local/openmoko/arm/setup-env
 
  source /usr/local/openmoko/arm/setup-env
  
= Building a sample project =
+
==Building a sample project==
  
 
In your home directory:
 
In your home directory:
Line 62: Line 64:
 
  make install
 
  make install
  
== Packaging your application ==
+
==Packaging your application==
  
We have included a script to make an ipkg out of 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
 
  om-make-ipkg openmoko-sample2
  
 
Now you got openmoko-sample2_0.1_armv4t.ipk , you can `scp' it to your
 
Now you got openmoko-sample2_0.1_armv4t.ipk , you can `scp' it to your
neo and install it:
+
Neo and install it:
  
 
  scp openmoko-sample2_0.1_armv4t.ipk root@192.168.0.202:
 
  scp openmoko-sample2_0.1_armv4t.ipk root@192.168.0.202:
 
  ssh root@192.168.0.202 ipkg install openmoko-sample2_0.1_armv4t.ipk
 
  ssh root@192.168.0.202 ipkg install openmoko-sample2_0.1_armv4t.ipk
  
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.
+
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 could supply the version number, a description, and an author / contacts string in a control file if you know how to use it:
+
You can also supply the version number, a description, and an author / contacts string in a control file:
  
 
  om-make-ipkg myapp myapp_control
 
  om-make-ipkg myapp myapp_control
Line 93: Line 95:
 
  Source: ${SRC}
 
  Source: ${SRC}
  
= Where to go from here =
+
==Where to go from here==
  
 
{{todo|write}}
 
{{todo|write}}
  
= Advanced topics =
+
=Advanced topics=
  
== Installing additional libraries into the toolchain ==
+
==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.
 
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.
Line 113: Line 115:
 
That's it.
 
That's it.
  
= Troubleshooting =
+
==Getting your application packaged by OE==
 +
 
 +
If you have written a cool application which you want to share with others, the best way to do that is to submit a [[BitBake]] recipe to [[OpenEmbedded]].
 +
 
 +
{{todo||finish}}
 +
 
 +
==Troubleshooting==
  
 
{{todo|write}}
 
{{todo|write}}

Revision as of 16:14, 20 December 2007

Contents

Introduction

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

  • Developing a single application

For this, you should use a prebuilt toolchain from the OpenMoko project. Here 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.

  • 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/. If 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:
    • autoconf, automake
    • binutils, gcc, gcc-c++
    • libtool
    • ccache

Downloading and installing

The prebuilt toolchain can be downloaded from [downloads.openmoko.org]:

mkdir ~/sources
cd ~/sources
wget http://downloads.openmoko.org/toolchains/openmoko-x86_64-arm-linux-gnueabi-toolchain.tar.bz2

or

wget http://downloads.openmoko.org/toolchains/openmoko-i686-arm-linux-gnueabi-toolchain.tar.bz2

Next, you want to extract it on your filesystem. This toolchain is not relocatable, it needs to be installed into /usr/local/openmoko/:

cd /
tar xjvf ~/sources/openmoko-XYZ-arm-linux-gnueabi-toolchain.tar.bz2

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:

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

Building a sample project

In your home directory:

cp -r /usr/local/openmoko/arm/share/openmoko-sample2 ~/
. /usr/local/openmoko/arm/setup-env
om-conf openmoko-sample2
<modify it if you want and make>

If you want to install this project on host for staging usage later, a shared library, for example, you can then call make install to install it into the configured prefix.

om-conf --prefix=/usr/local/openmoko openmoko-sample2
make install

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:

scp openmoko-sample2_0.1_armv4t.ipk root@192.168.0.202:
ssh root@192.168.0.202 ipkg install openmoko-sample2_0.1_armv4t.ipk

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:

om-make-ipkg myapp myapp_control

A template of myapp_control:

Package: $appname
Version: 0.1
Description: package built by openmoko toolchain
Section: openmoko/applications
Priority: optional
Maintainer: $USER
Architecture: armv4t
Homepage: http://www.openmoko.org/
Depends: 
Source: ${SRC}

Where to go from here

TODO: write (See: To-Do List)

Advanced topics

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:

cd ~/source
wget http://downloads.sourceforge.net/uriparser/uriparser-0.6.0.tar.bz2
./configure --host=arm-angstrom-linux-gnueabi --prefix=/usr/local/openmoko/arm
make
make install

That's it.

Getting your application packaged by OE

If you have written a cool application which you want to share with others, the best way to do that is to submit a BitBake recipe to OpenEmbedded.

TODO: (See: To-Do List)

Troubleshooting

TODO: write (See: To-Do List)
Personal tools

Introduction

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

  • Developing a single application

For this, you should use a prebuilt toolchain from the OpenMoko project. Here 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.

  • 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.

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/. If 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:
    • autoconf, automake
    • binutils, gcc, gcc-c++
    • libtool
    • ccache

Downloading and installing

The prebuilt toolchain can be downloaded from [downloads.openmoko.org]:

mkdir ~/sources
cd ~/sources
wget http://downloads.openmoko.org/toolchains/openmoko-x86_64-arm-linux-gnueabi-toolchain.tar.bz2

or

wget http://downloads.openmoko.org/toolchains/openmoko-i686-arm-linux-gnueabi-toolchain.tar.bz2

Next, you want to extract it on your filesystem. This toolchain is not relocatable, it needs to be installed into /usr/local/openmoko/:

cd /
tar xjvf ~/sources/openmoko-XYZ-arm-linux-gnueabi-toolchain.tar.bz2

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:

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

Building a sample project

In your home directory:

cp -r /usr/local/openmoko/arm/share/openmoko-sample2 ~/
. /usr/local/openmoko/arm/setup-env
om-conf openmoko-sample2
<modify it if you want and make>

If you want to install this project on host for staging usage later, a shared library, for example, you can then call make install to install it into the configured prefix.

om-conf --prefix=/usr/local/openmoko openmoko-sample2
make install

Packaging your application

We have included a script to make an ipkg out of your application.

om-make-ipkg openmoko-sample2

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

scp openmoko-sample2_0.1_armv4t.ipk root@192.168.0.202:
ssh root@192.168.0.202 ipkg install openmoko-sample2_0.1_armv4t.ipk

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.

You could supply the version number, a description, and an author / contacts string in a control file if you know how to use it:

om-make-ipkg myapp myapp_control

A template of myapp_control:

Package: $appname
Version: 0.1
Description: package built by openmoko toolchain
Section: openmoko/applications
Priority: optional
Maintainer: $USER
Architecture: armv4t
Homepage: http://www.openmoko.org/
Depends: 
Source: ${SRC}

Where to go from here

TODO: write (See: To-Do List)

Advanced topics

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:

cd ~/source
wget http://downloads.sourceforge.net/uriparser/uriparser-0.6.0.tar.bz2
./configure --host=arm-angstrom-linux-gnueabi --prefix=/usr/local/openmoko/arm
make
make install

That's it.

Troubleshooting

TODO: write (See: To-Do List)