Software development for the OpenMoko Linux phone A free and open platform for mobile communications Skill Level: Intermediate Peter Seebach ([email protected]) Freelance writer Freelance 13 Nov 2007 The OpenMoko environment provides a completely free development environment for running application and system code on supported phone hardware, eliminating all dependency on proprietary code. This tutorial introduces the OpenEmbedded build environment used to create filesystem images for OpenMoko phones, such as the Neo 1973. Section 1. Before you start About this tutorial This tutorial introduces the OpenMoko development platform and shows the details of using it to target the Neo 1973, a unique cell phone developed and sold with the intent of working anywhere, on any network, and running whatever software you want to develop for it. Tutorial objectives After a brief overview of the configuration and flashing process, I show you the files you need and what to do with them. Following that, I get into the details of software Software development for the OpenMoko Linux phone © Copyright IBM Corporation 1994, 2007. All rights reserved. Page 1 of 26 developerWorks® ibm.com/developerWorks development. Rather than duplicate existing documentation, this tutorial shows you the big picture and brings everything together. Prerequisites This tutorial is for Linux developers with basic software development experience, and either experience with or interest in telephony and embedded systems. Some basic familiarity with the command line is assumed. You don't need a Neo 1973 phone (or any other) to understand the tutorial, but it will be most rewarding if you have at least a working OpenMoko target, even if it's emulated. I wrote the tutorial using Ubuntu as a host environment, but virtually any Linux® system should work. It's also possible to use Mac OS X or even Windows® as host environments. Section 2. Platform overview Is it a phone or is it software? First International Computer produces the Neo 1973, which is often referred to as "an OpenMoko." In fact, OpenMoko is a Linux platform and associated applications, not a phone. It is, however, a Linux application for phones, and as of this writing, the Neo 1973 is the only fully viable phone to run it on. You can also build an emulated environment for software development, which I cover in this tutorial, but it won't connect to a phone network very well. OpenEmbedded OpenMoko is built using OpenEmbedded for cross-compilation (see Resources for a link to more information on OpenEmbedded). OpenEmbedded provides tools and support for build and release functions, whether you're trying to build a native program with debugging or an optimized target binary. As a result, developing for OpenMoko requires getting a feel for how to use OpenEmbedded. MokoMakefile Software development for the OpenMoko Linux phone Page 2 of 26 © Copyright IBM Corporation 1994, 2007. All rights reserved. ibm.com/developerWorks developerWorks® One of the difficulties of a new environment is getting everything set up, files in the right places, and so on. Enter the MokoMakefile (see Resources for a link), a huge makefile that does all of this for you for the OpenMoko environment. The MokoMakefile is being developed and maintained by Rod Whitby; it's not yet part of the official OpenMoko environment. Set up an emulator As I mentioned, if you don't have a phone handy, you can also set up an emulator. The QEMU emulator provides a fairly full-featured emulation of the OpenMoko phone environment. One of the options is a branch of QEMU that provides nearly complete emulation of the phone's hardware, lacking only the GPS unit. For more information about setting up a QEMU-based emulator, have a look at the OpenMoko Wiki page on "OpenMoko under QEMU" (see Resources for a link). While it's obviously most convenient to use an actual phone, there's something to be said for running an emulator. Most noticeably, the emulator can be downloaded right away, for free. The OpenMoko wiki (see Resources for a link) has additional information on configuring an emulator. This tutorial was developed using both the emulator and an actual phone, but not every function can be tested on the emulator. Set up the phone If you do have a Neo 1973, you should flash it to a current version of the OpenMoko software. Rather than duplicate here the excellent instructions from the OpenMoko wiki, look for the link to "Flashing openmoko" in Resources. Once your phone is set up, you can turn it on now or go ahead and set up an emulator as well. Booting for the first time If you're using the emulator, you won't be able to see this screen for a while, but here is what you're looking for: Figure 1. OpenMoko splash screen Software development for the OpenMoko Linux phone © Copyright IBM Corporation 1994, 2007. All rights reserved. Page 3 of 26 developerWorks® ibm.com/developerWorks Software development for the OpenMoko Linux phone Page 4 of 26 © Copyright IBM Corporation 1994, 2007. All rights reserved. ibm.com/developerWorks developerWorks® Section 3. Getting your environment together Collect your tools You need to have a number of tools handy to run OpenMoko; different Linux distributions have some of them installed already, but rarely all of them, so be prepared to fetch a few things. Perhaps most importantly, you must have gcc 3.4—not gcc 4.anything—to build and run QEMU. (This is almost certainly a bug, somewhere, but it hasn't been fixed in some time.) You also need subversion, various documentation-related tools such as texinfo, development headers for ncurses, a compression library (zlib or libz), OpenSSL, and GTK++. You may need additional things based on your system. The MokoMakefile wiki page has more information on a few systems. Download the MokoMakefile Make a new directory named whatever you want, and put it wherever you want on your system. I named mine "om" and put it in my home directory. Change to that directory and download the MokoMakefile. Prepare for the build The MokoMakefile can build everything you need, from scratch. This will take some time, so be prepared to wander off and do something else for a while. If you have a multicore system, you can save time by creating a file named build/conf/local.conf (create the build/conf subdirectory of your working directory first) containing two lines specifying a parallel build: PARALLEL_MAKE = "-j 4" BB_NUMBER_THREADS = "4" The number 4, in this case, was calculated for a dual-core system; some people recommend running one more thread than your system has cores, and some recommend two threads per core. Four threads will work reasonably on a dual-core system. Software development for the OpenMoko Linux phone © Copyright IBM Corporation 1994, 2007. All rights reserved. Page 5 of 26 developerWorks® ibm.com/developerWorks Run the build The first thing to do is run make setup for initial setup and configuration. Then run make openmoko-devel-image, and watch as a complete OpenMoko environment is built—but you may not want to watch the whole thing, as it can easily take five hours or longer. If you plan to use the QEMU emulator, build it now as well, using make build-qemu. Section 4. The directory tree, as built What's all this stuff? When you typed make setup, you were probably in a directory containing only a makefile, or possibly a makefile and a single configuration file. Now, you should have directories with names like "bitbake," "images," and "sources." These are the working structure of an OpenEmbedded build environment. The bitbake directory Bitbake (the tool used to actually build target binaries and so on) has its own directory containing tools, documentation, and more. This directory holds the bitbake distribution; don't mess with it unless you know exactly what you're doing. The build directory The build directory holds configuration files (build/conf), QEMU stuff (build/qemu), and a temporary directory used for intermediate states. The temporary directory (build/tmp) holds its own selection of subdirectories; cache, cross, deploy, rootfs, staging, stamps, and work. When you're building, whether for the host or target environment, files end up in here. Of particular interest are the subdirectories of fic-gta01-angstrom-linux-gnueabi, which correspond to the Neo 1973 phone. In general, you will poke around in here only when debugging the build; you may want to pay special attention to the stamps directory, which indicates when each task was last performed. The openembedded directory Software development for the OpenMoko Linux phone Page 6 of 26 © Copyright IBM Corporation 1994, 2007. All rights reserved. ibm.com/developerWorks developerWorks® This directory contains the OpenEmbedded distribution, including all of the packages available. The openembedded/packages directory is where new packages will be added—you'll need that a little later on. Mostly, though, this is internal architecture for OpenEmbedded, and you don't need to do much to it. The openmoko directory The openmoko directory contains additional files and documentation specific to OpenMoko, not just related to OpenEmbedded. Once again, you shouldn't have to interact with this too much directly. The patches directory As of this writing, this directory contains a tree structure providing for patches against openmoko, bitbake, or openembedded, but none are in it to begin with. The sources directory The sources directory is where source files are downloaded to for use in building the target filesystem. It holds actual distribution tarballs, as well as lock files and checksums. The sources/svn subdirectory holds Subversion checkouts for things that were downloaded via Subversion rather than as tarballs.