Customizing the Openmoko Distribution

From Openmoko

(Difference between revisions)
Jump to: navigation, search
(Your First Compilation)
m (Filling in the files: fixed typo)
Line 241: Line 241:
 
Kidding aside, next is the all important <code> packages/pyhelloworld/pyhelloworld.bb:</code>
 
Kidding aside, next is the all important <code> packages/pyhelloworld/pyhelloworld.bb:</code>
 
<pre>
 
<pre>
DESCRIPTION = "A pythonic hello world applicaiton"
+
DESCRIPTION = "A pythonic hello world application"
 
AUTHOR = "Tyler Laing"
 
AUTHOR = "Tyler Laing"
 
HOMEPAGE = ""
 
HOMEPAGE = ""

Revision as of 11:28, 5 August 2007

Contents

What's the goal?

The goal of this page is to teach you how to take an application that you've coded (or the sample app) and properly get it included in your rootfs. This article is a bit of an aggregate page, it's going to take information from MokoMakefile, Using a local overlay, Building a hello world application, and Create a package from existing sources. So as you can see the goal is for it to be a very thorough introduction, and will take you from "Idea to Inclusion" of your application.


Setting Up the OpenMoko Environment

*If you already have the environment setup then it is imperative that you update your Makefile.

Do this by running:

make update-makefile

This part of the tutorial is going to be pretty basic. I absolutely love MokoMakefile, it's fantastic, the creator has done and continues to do a fantastic job with this. I see absolutely no reason not to use it I put my OpenMoko development directory in /home/bryce/mokodev/ and that works great for me. You can feel free to do the same or put it anywhere else in your user directory (or anywhere on your system if you're feeling daring and a little nutty).

To get your environment setup please get it setup according to MokoMakefile however if you do have the build environment setup manually and you're sure you know what you're doing then feel free to go forward with this.

Setting Up a Local Overlay

If you're at the point for setting up a local overlay this means a couple things. First: You've had a brilliant idea for an application that you just need to have on the OpenMoko platform. Second: You realize that this killer app of yours needs to be done properly and you're not going to do anything silly like include it in the actual tree for the OpenMoko distro because it would probably end up just getting overwritten eventually, or you just realize that it's bad practice!

If you're wondering why and what a local overlay is then let me take this time to explain it to you. A local overlay is where you, as a developer keep your local files in an OE style setup so that you can simply pull your updated code into the tree. You add your overlay tree into the bitbake setup so that when you call bitbake it will pull your own or your customized packages before going to the OE or OpenMoko trees.This keeps everything nice and organized for you and also allows you to build/rebuild/include you apps by using the MokoMakefile

Thank you to User:CesarB for this part of the wiki.

To create a local overlay:

  • Create a "local" directory and its subdirectories
mkdir local local/conf local/classes local/packages
  • Copy site.conf from the openmoko tree to local/conf
cp oe/conf/site.conf local/conf/site.conf
  • Edit the site.conf you copied to add the new tree as a source for bitbake recipes.

Change the current BBFILES to look like this:

BBFILES := "${OMDIR}/openembedded/packages/*/*.bb ${OMDIR}/oe/packages/*/*.bb ${OMDIR}/local/packages/*/*.bb"

Change your BBFILE_COLLECTIONS line to look like this:

BBFILE_COLLECTIONS = "upstream local overlay"

Add this line:

BBFILE_PATTERN_overlay = "^${OMDIR}/local/"

Add this line:

BBFILE_PRIORITY_overlay = "20"

The BBFILE_PRIORITY should be greater than all the other BBFILE_PRIORITY variables on the same file.

  • Change your BBPATH environment variable to add the new tree before the two others in your setup-env file.setup-env is created by MokoMakefile automatically and is located in your ${OMDIR} directory.
export BBPATH="${OMDIR}/build:${OMDIR}/local:${OMDIR}/oe:${OMDIR}/openembedded"

Using Your New Local Overlay

Changing files in conf/

To change a file in conf/, just copy the file to the overlay tree (preserving the directory structure) and edit it.

Changing files in classes/

To change a file in classes/, just copy the file to the overlay tree and edit it.

Changing packages

Changing a package's recipe is a bit more complex. You have to copy over (or symlink) not only the .bb file for the package, but also all the files it includes with require, and the FILESDIR directories (all directories referred to by FILESDIR, usually named either package-version or files). If you forget one of them, the build will give an error (either when parsing the recipe in the case of require, or when trying to build in the case of the FILESDIR directories).

Adding a new package

You can add a new package (or a recipe for a new version of a package) to the overlay tree simply by creating it on the overlay tree.

Your First Application

I know that I said I'd have a GDK application in here, however, I'd really like to get this whole course done first and have you guys starting to code instead of just looking at what I've written!

This will be a very simple CLI hello world.

Before We Code

Like a good coder you want to make sure that you're not just doing things, but that you're doing them the right way!

Now change directories into your local/packages directory.The following commands expect you'll be in that directory so don't change unless you know what you're doing!

You'll want to make a directory with the name of your application, and a subdirectory called files.

 mkdir myhelloworld myhelloworld/files

Now you'll want to create two files in the files directory

 touch myhelloworld/files/README.txt myhelloworld/files/myhelloworld.c

And finally you'll want to create a bitbake file.

 touch myhelloworld/myhelloworld.bb

Alrighty now all your necessary files are created so lets go over this real quick.

$HOME
 +- $OMDIR (contains the official openmoko tree)
 |  +- local/
 |     +- packages/
 |        +- myhelloworld/
 |           +- myhelloworld.bb
 |           +- files/
 |              +- myhelloworld.c
 |              +- README.txt

That should be your structure, if it's not you should go and fix it up.

Filling the Files

So you've got your sample files all laid out now it's time to make them actually do something.

myhelloworld.c

#include <stdio.h>

int main(int argc, char** argv)
{
        printf("Ello Poppet!\n");
        return 0;
}

README.txt

This is a command line application. It prints a simple Hello World! To stdout.

myhelloworld.bb

DESCRIPTION = "A killer hello world application"
AUTHOR = "Bryce Leo"
HOMEPAGE = ""
SECTION = "console/applications"
PRIORITY = "optional"
LICENSE = "MIT"
#DEPENDS = ""
#RDEPENDS = ""
#RRECOMMENDS = ""
#RCONFLICTS = ""
#SRCDATE = "20070729"
#PV = "0.1"
#PR = "r0"
SRC_URI = "file://myhelloworld.c \
          file://README.txt "

S = "${WORKDIR}/myhelloworld/"

do_compile() {
        ${CC} ${CFLAGS} ${LDFLAGS} ${WORKDIR}/myhelloworld.c -o myhelloworld
}

do_install() {
        install -m 0755 -d ${D}${bindir} ${D}${docdir}/myhelloworld
        install -m 0755 ${S}/myhelloworld ${D}${bindir}
        install -m 0644 ${WORKDIR}/README.txt ${D}${docdir}/myhelloworld
}

Your First Compilation

This is where the MokoMakefile comes in very very handy. Change to your ${OMDIR} directory, You'll know it by the fact that it is where Makefile resides.

make build-package-myhelloworld

(make sure you run make openmoko-devel-image at least once before building your own packages)

This should all come back and not return any error messages, The output should end in something similar to

NOTE: package myhelloworld-1.0: completed
NOTE: build 200707291926: completed
Build statistics:
  Attempted builds: 1

Now that no errors were thrown we are happily done!

Adding Your Application to the Image

So you've had an idea, you've setup the build environment, you've setup your local overlay, you've laid out your application tree, you've put code into those fantastic files of yours and now it compiles.There's only one thing left to do. Add that application to your image.

Now lets go over in words and whys what we're about to do. First we need to make modify the ${OMDIR}/build/conf/local.conf. We add in the variable DISTRO_EXTRA_RDEPENDS and set its value to include myhelloworld. If you'd like to include other packages from your own overlay or the OM tree just add them inseparated by spaces. After this gets added as a dependency to build the Distro (in this case OpenMoko). Now we have to re-build the task-base package. This essentially just generates an ipk file that will "Merge machine and distro options to create a basic machine task/package." It pretty much builds a file with a list of packages to be installed that are required for the distro to work correctly. So then you just go through and make openmoko-devel-image, build-qemu, flash-qemu-local, and run-qemu. Then calibrate your stylus, head over to the terminal, and run your application!

Modifying Your local.conf

Now, go into your build config directory ${OMDIR}/build/conf/ and now you'll be editing local.conf Add this line to you local.conf

 DISTRO_EXTRA_RDEPENDS += "myhelloworld"

With this line you can also include other applications from the OE tree. For instance my local.conf looks like this.

MACHINE = "fic-gta01"
DISTRO = "openmoko"
BUILD_ARCH = "i686"
SRCDATE_eds-dbus = "now"
DISTRO_EXTRA_RDEPENDS += "lua dillo myhelloworld"

Now that you've fixed your local.conf it's time to go through all the necessary tasks to add and re-build you image and have your sweet package included.

Building

Now come the easy part thanks to MokoMakefile.

 make rebuild-package-task-base
 make openmoko-devel-image
 make build-qemu
 make flash-qemu-local

Now all you have to do is run qemu.

 make run-qemu

From here after you calibrate your stylus, you click on the Menu in the top right, click down to terminal, then just run your program.

root@fic-gta02:/$ myhelloworld
Ello Poppet!

Adding Python scripts as applications

This is for adding python scripts/packages to the image for your own use.

First steps

First, you need to modify the local.conf file as described above. You need to modify

 DISTRO_EXTRA_RDEPENDS += "myhelloworld"

to

 DISTRO_EXTRA_RDEPENDS += "myhelloworld python"

This is because python is not included by default in the openmoko image. Or you can use python-gtk if you wish.

Next, you need to perform these actions from the $OMDIR/local directory.

 mkdir packages/pyhelloworld packages/pyhelloworld/files
 touch packages/pyhelloworld/files/pyhello packages/pyhelloworld/README.txt
 touch packages/pyhelloworld/pyhelloworld.bb

Filling in the files

Now, edit packages/pyhelloworld/files/pyhello to contain:

  
#!/usr/bin/python

print "hello world!"
print "shutting down now. Farewell oh cruel, cruel world!"

Next up, is editing packages/pyhelloworld/files/README.txt to say:

 This is the most awesome helloworld application ever. Know why? It has SNAKES!

Kidding aside, next is the all important packages/pyhelloworld/pyhelloworld.bb:

DESCRIPTION = "A pythonic hello world application"
AUTHOR = "Tyler Laing"
HOMEPAGE = ""
SECTION = "console/applications"
PRIORITY = "optional"
LICENSE = "MIT"
#DEPENDS = ""
#RDEPENDS = ""
#RRECOMMENDS = ""
#RCONFLICTS = ""
#SRCDATE = "20070729"
#PV = "0.1"
#PR = "r0"
SRC_URI = "file://pyhello \
          file://README.txt "

S = "${WORKDIR}/pyhelloworld/"


do_install() {
        install -m 0755 -d ${D}${bindir} ${D}${docdir}/pyhelloworld
        install -m 0755 ${WORKDIR}/pyhello ${D}${bindir}
        install -m 0644 ${WORKDIR}/README.txt ${D}${docdir}/pyhelloworld
}

I'll explain each of the parts right here, for future reference.

Meanings of variables in .bb files

 $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/

Final steps

Complete the last steps as per the above instructions, from the point of altering DISTRO_EXTRA_RDEPENDS.

And your done!

Personal tools

What's the goal?

The goal of this page is to teach you how to take an application that you've coded (or the sample app) and properly get it included in your rootfs. This article is a bit of an aggregate page, it's going to take information from MokoMakefile, Using a local overlay, Building a hello world application, and Create a package from existing sources. So as you can see the goal is for it to be a very thorough introduction, and will take you from "Idea to Inclusion" of your application.


Setting Up the OpenMoko Environment

*If you already have the environment setup then it is imperative that you update your Makefile.

Do this by running:

make update-makefile

This part of the tutorial is going to be pretty basic. I absolutely love MokoMakefile, it's fantastic, the creator has done and continues to do a fantastic job with this. I see absolutely no reason not to use it I put my OpenMoko development directory in /home/bryce/mokodev/ and that works great for me. You can feel free to do the same or put it anywhere else in your user directory (or anywhere on your system if you're feeling daring and a little nutty).

To get your environment setup please get it setup according to MokoMakefile however if you do have the build environment setup manually and you're sure you know what you're doing then feel free to go forward with this.

Setting Up a Local Overlay

If you're at the point for setting up a local overlay this means a couple things. First: You've had a brilliant idea for an application that you just need to have on the OpenMoko platform. Second: You realize that this killer app of yours needs to be done properly and you're not going to do anything silly like include it in the actual tree for the OpenMoko distro because it would probably end up just getting overwritten eventually, or you just realize that it's bad practice!

If you're wondering why and what a local overlay is then let me take this time to explain it to you. A local overlay is where you, as a developer keep your local files in an OE style setup so that you can simply pull your updated code into the tree. You add your overlay tree into the bitbake setup so that when you call bitbake it will pull your own or your customized packages before going to the OE or OpenMoko trees.This keeps everything nice and organized for you and also allows you to build/rebuild/include you apps by using the MokoMakefile

Thank you to User:CesarB for this part of the wiki.

To create a local overlay:

  • Create a "local" directory and its subdirectories
mkdir local local/conf local/classes local/packages
  • Copy site.conf from the openmoko tree to local/conf
cp oe/conf/site.conf local/conf/site.conf
  • Edit the site.conf you copied to add the new tree as a source for bitbake recipes.

Change the current BBFILES to look like this:

BBFILES := "${OMDIR}/openembedded/packages/*/*.bb ${OMDIR}/oe/packages/*/*.bb ${OMDIR}/local/packages/*/*.bb"

Change your BBFILE_COLLECTIONS line to look like this:

BBFILE_COLLECTIONS = "upstream local overlay"

Add this line:

BBFILE_PATTERN_overlay = "^${OMDIR}/local/"

Add this line:

BBFILE_PRIORITY_overlay = "20"

The BBFILE_PRIORITY should be greater than all the other BBFILE_PRIORITY variables on the same file.

  • Change your BBPATH environment variable to add the new tree before the two others in your setup-env file.setup-env is created by MokoMakefile automatically and is located in your ${OMDIR} directory.
export BBPATH="${OMDIR}/build:${OMDIR}/local:${OMDIR}/oe:${OMDIR}/openembedded"

Using Your New Local Overlay

Changing files in conf/

To change a file in conf/, just copy the file to the overlay tree (preserving the directory structure) and edit it.

Changing files in classes/

To change a file in classes/, just copy the file to the overlay tree and edit it.

Changing packages

Changing a package's recipe is a bit more complex. You have to copy over (or symlink) not only the .bb file for the package, but also all the files it includes with require, and the FILESDIR directories (all directories referred to by FILESDIR, usually named either package-version or files). If you forget one of them, the build will give an error (either when parsing the recipe in the case of require, or when trying to build in the case of the FILESDIR directories).

Adding a new package

You can add a new package (or a recipe for a new version of a package) to the overlay tree simply by creating it on the overlay tree.

Your First Application

I know that I said I'd have a GDK application in here, however, I'd really like to get this whole course done first and have you guys starting to code instead of just looking at what I've written!

This will be a very simple CLI hello world.

Before We Code

Like a good coder you want to make sure that you're not just doing things, but that you're doing them the right way!

Now change directories into your local/packages directory.The following commands expect you'll be in that directory so don't change unless you know what you're doing!

You'll want to make a directory with the name of your application, and a subdirectory called files.

 mkdir myhelloworld myhelloworld/files

Now you'll want to create two files in the files directory

 touch myhelloworld/files/README.txt myhelloworld/files/myhelloworld.c

And finally you'll want to create a bitbake file.

 touch myhelloworld/myhelloworld.bb

Alrighty now all your necessary files are created so lets go over this real quick.

$HOME
 +- $OMDIR (contains the official openmoko tree)
 |  +- local/
 |     +- packages/
 |        +- myhelloworld/
 |           +- myhelloworld.bb
 |           +- files/
 |              +- myhelloworld.c
 |              +- README.txt

That should be your structure, if it's not you should go and fix it up.

Filling the Files

So you've got your sample files all laid out now it's time to make them actually do something.

myhelloworld.c

#include <stdio.h>

int main(int argc, char** argv)
{
        printf("Ello Poppet!\n");
        return 0;
}

README.txt

This is a command line application. It prints a simple Hello World! To stdout.

myhelloworld.bb

DESCRIPTION = "A killer hello world application"
AUTHOR = "Bryce Leo"
HOMEPAGE = ""
SECTION = "console/applications"
PRIORITY = "optional"
LICENSE = "MIT"
#DEPENDS = ""
#RDEPENDS = ""
#RRECOMMENDS = ""
#RCONFLICTS = ""
#SRCDATE = "20070729"
#PV = "0.1"
#PR = "r0"
SRC_URI = "file://myhelloworld.c \
          file://README.txt "

S = "${WORKDIR}/myhelloworld/"

do_compile() {
        ${CC} ${CFLAGS} ${LDFLAGS} ${WORKDIR}/myhelloworld.c -o myhelloworld
}

do_install() {
        install -m 0755 -d ${D}${bindir} ${D}${docdir}/myhelloworld
        install -m 0755 ${S}/myhelloworld ${D}${bindir}
        install -m 0644 ${WORKDIR}/README.txt ${D}${docdir}/myhelloworld
}

Your First Compilation

This is where the MokoMakefile comes in very very handy. Change to your ${OMDIR} directory, You'll know it by the fact that it is where Makefile resides.

make build-package-myhelloworld

(make sure you run make openmoko-devel-image at least once before building your own packages)

This should all come back and not return any error messages, The output should end in something similar to

NOTE: package myhelloworld-1.0: completed
NOTE: build 200707291926: completed
Build statistics:
  Attempted builds: 1

Now that no errors were thrown we are happily done!

Adding Your Application to the Image

So you've had an idea, you've setup the build environment, you've setup your local overlay, you've laid out your application tree, you've put code into those fantastic files of yours and now it compiles.There's only one thing left to do. Add that application to your image.

Now lets go over in words and whys what we're about to do. First we need to make modify the ${OMDIR}/build/conf/local.conf. We add in the variable DISTRO_EXTRA_RDEPENDS and set its value to include myhelloworld. If you'd like to include other packages from your own overlay or the OM tree just add them inseparated by spaces. After this gets added as a dependency to build the Distro (in this case OpenMoko). Now we have to re-build the task-base package. This essentially just generates an ipk file that will "Merge machine and distro options to create a basic machine task/package." It pretty much builds a file with a list of packages to be installed that are required for the distro to work correctly. So then you just go through and make openmoko-devel-image, build-qemu, flash-qemu-local, and run-qemu. Then calibrate your stylus, head over to the terminal, and run your application!

Modifying Your local.conf

Now, go into your build config directory ${OMDIR}/build/conf/ and now you'll be editing local.conf Add this line to you local.conf

 DISTRO_EXTRA_RDEPENDS += "myhelloworld"

With this line you can also include other applications from the OE tree. For instance my local.conf looks like this.

MACHINE = "fic-gta01"
DISTRO = "openmoko"
BUILD_ARCH = "i686"
SRCDATE_eds-dbus = "now"
DISTRO_EXTRA_RDEPENDS += "lua dillo myhelloworld"

Now that you've fixed your local.conf it's time to go through all the necessary tasks to add and re-build you image and have your sweet package included.

Building

Now come the easy part thanks to MokoMakefile.

 make rebuild-package-task-base
 make openmoko-devel-image
 make build-qemu
 make flash-qemu-local

Now all you have to do is run qemu.

 make run-qemu

From here after you calibrate your stylus, you click on the Menu in the top right, click down to terminal, then just run your program.

root@fic-gta02:/$ myhelloworld
Ello Poppet!

Adding Python scripts as applications

This is for adding python scripts/packages to the image for your own use.

First steps

First, you need to modify the local.conf file as described above. You need to modify

 DISTRO_EXTRA_RDEPENDS += "myhelloworld"

to

 DISTRO_EXTRA_RDEPENDS += "myhelloworld python"

This is because python is not included by default in the openmoko image. Or you can use python-gtk if you wish.

Next, you need to perform these actions from the $OMDIR/local directory.

 mkdir packages/pyhelloworld packages/pyhelloworld/files
 touch packages/pyhelloworld/files/pyhello packages/pyhelloworld/README.txt
 touch packages/pyhelloworld/pyhelloworld.bb

Filling in the files

Now, edit packages/pyhelloworld/files/pyhello to contain:

  
#!/usr/bin/python

print "hello world!"
print "shutting down now. Farewell oh cruel, cruel world!"

Next up, is editing packages/pyhelloworld/files/README.txt to say:

 This is the most awesome helloworld application ever. Know why? It has SNAKES!

Kidding aside, next is the all important packages/pyhelloworld/pyhelloworld.bb:

DESCRIPTION = "A pythonic hello world applicaiton"
AUTHOR = "Tyler Laing"
HOMEPAGE = ""
SECTION = "console/applications"
PRIORITY = "optional"
LICENSE = "MIT"
#DEPENDS = ""
#RDEPENDS = ""
#RRECOMMENDS = ""
#RCONFLICTS = ""
#SRCDATE = "20070729"
#PV = "0.1"
#PR = "r0"
SRC_URI = "file://pyhello \
          file://README.txt "

S = "${WORKDIR}/pyhelloworld/"


do_install() {
        install -m 0755 -d ${D}${bindir} ${D}${docdir}/pyhelloworld
        install -m 0755 ${WORKDIR}/pyhello ${D}${bindir}
        install -m 0644 ${WORKDIR}/README.txt ${D}${docdir}/pyhelloworld
}

I'll explain each of the parts right here, for future reference.

Meanings of variables in .bb files

 $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/

Final steps

Complete the last steps as per the above instructions, from the point of altering DISTRO_EXTRA_RDEPENDS.

And your done!