edit packages/tasks/task-openmoko-scaredycat.bb - this is where we put the things we want to include in our image, above and beyond the standard image. This example includes '''[http://wiki.openmoko.org/wiki/Scummvm scummvm]''' and '''[http://www.handhelds.org/moin/moin.cgi/kbdd kbdd]'''. If you modify this file, make sure you update the '''PR''' by incrementing the number each time.

+

edit local/packages/tasks/task-openmoko-scaredycat.bb - this is where we put the things we want to include in our image, above and beyond the standard image. This example includes '''[http://wiki.openmoko.org/wiki/Scummvm scummvm]''' and '''[http://www.handhelds.org/moin/moin.cgi/kbdd kbdd]'''. If you modify this file, make sure you update the '''PR''' by incrementing the number each time.

Setting Up the OpenMoko Environment

*If you already have the environment set up 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 it 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 set up, please get it set up according to MokoMakefile. However, if you do have the build environment set up 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 of 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 your apps by using the MokoMakefile

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. Bitbake only seems to use the first site.conf file it finds. setup-env is created by MokoMakefile automatically and is located in your ${OMDIR} directory.

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.

Creating your own images

To create you own images we'll use the base openmoko .bb files and modify them to suit. Where you see scaredycat replace this with something to identify your own images.

edit local/packages/tasks/task-openmoko-scaredycat.bb - this is where we put the things we want to include in our image, above and beyond the standard image. This example includes scummvm and kbdd. If you modify this file, make sure you update the PR by incrementing the number each time.

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.

Setting Up the OpenMoko Environment

*If you already have the environment set up 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 it 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 set up, please get it set up according to MokoMakefile. However, if you do have the build environment set up 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 of 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 your apps by using the MokoMakefile

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. Bitbake only seems to use the first site.conf file it finds. setup-env is created by MokoMakefile automatically and is located in your ${OMDIR} directory.

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.

Creating your own images

To create you own images we'll use the base openmoko .bb files and modify them to suit. Where you see scaredycat replace this with something to identify your own images.

edit local/packages/tasks/task-openmoko-scaredycat.bb - this is where we put the things we want to include in our image, above and beyond the standard image. This example includes scummvm and kbdd. If you modify this file, make sure you update the PR by incrementing the number each time.

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.