Updated: 7th June to expand the setup scripts section and tell people to get them from GIT.
This is the 1st of 2 articles I will be publishing on getting started with building the Linux distribution installed on the OpenPandora, from source code, from scratch.
Note: This is not a guide to using OpenEmbedded or bitbake, or writing package recipes. It’s just a guide to getting an OpenPandora build setup running.
This 1st article will cover the basic setup of OpenEmbedded environment and the building of our Ångström distribution derived ROOTFS, the 2nd will detail how you can run the resulting images on your OpenPandora from SD cards, or if you really want to, the NAND.
I also plan to write a separate related article will show how you can setup toolchains and SDK’s to help you develop applications for (and natively on) the OpenPandora using some of the strengths of OpenEmbedded to make this easier.
As I write these posts in my own time I can’t promise to do anything quickly. Nor can I make any promises about how accurate they may be ;). As always, feedback is welcome.
Most application developers/porters will only be interested in the related article on setting up SDK’s and toolchains, these 2 are really for the hardened Linux hackers who want to mess about with the ROOTFS/distribution development.
Health (and sanity) warning: Building the entire ROOTFS from scratch is pretty technical in nature, if you have no desire to rebuild the ROOTFS or hack with the inner workings of you’re OpenPandora this is probably not for you.
You can’t really damage anything on your OpenPandora but if your not familiar with compiling your own apps, kernels etc. and fixing things when they don’t work this will present a VERY steep learning curve. You also have the potential to make a mess of your build host if you are not careful with the setup.
I’ll focus showing how you can build a ‘one <> one’ version of the 1st official release (GIT tag: “Release-2010-05/1”).
Once you have that going feel free to build the tips of the metadata GIT’s if you want to work with the latest and greatest or get stuck in modifying the metadata to suit whatever purpose you may have in mind.
Closed source prerequisites:
Before we start you will need to collect up the few closed source components used in the ROOTFS, thankfully Texas Instruments and Imagination Technologies at least make getting the closed source binaries and SDK for the PowerVR SGX quite easy these days.
PowerVR SGX Binaries and SDK:
You will need to download version 3.01.00.02 of the Ti Graphics SDK (OMAP35x_Graphics_SDK_setuplinux_3_01_00_02.bin) from http://software-dl.ti.com/dsps/forms/export.html?prod_no=/OMAP35x_Graphics_SDK_setuplinux_3_01_00_02.bin
You will have to create a Ti account to download the software and agree to a license/export agreement but once you have done this Ti normally instantly grant access to the download. After you download this store it in a safe place, you will need to drop it into a folder in the build system later on.
The other closed source components are the firmware that is run on the WL1251 wireless chip and Bluetooth chip (the drivers themselves are open source and in mainline Linux). However our build system will automatically downloads these closed source firmware binary firmwares and places them into the appropriate place in the ROOTFS.
Host OS for building the ROOTFS:
Note: all my OpenEmbedded build boxes are 32bit Ubuntu Linux 10.04 servers with PAE enabled kernels, building on most other Linux distributions should be (and is) simple enough however some small adjustments may need to be made to suit your distribution. The OpenEmbedded and Ångström documentation can help with this.
You will need to install a number of packages onto your host PC before you start building OpenEmbedded images.
Try the command below, this should get most of the major prerequisite packages installed that you will need to start building using OpenEmbedded on a Ubuntu/Debian derived distribution.
Note: The OpenEmbedded Required Software page also details this very well and is a must read.
One last thing to consider if your using a Ubuntu derivative is that they use dash as the default shell not bash.
This can cause a few issues with some of the packages we want to try and build, it’s not a problem with the build system per-say but issues with the individual packages assuming bash hacks in whatever /bin/sh is on the system.
Still, the fix is pretty easy, just set your default shell to bash using the command below.
Important GIT repositories (GITWeb links):
All the metadata (and custom source code etc.) is held on a publically accessible GIT server (git.openpandora.org).
For the purposes of building a working ROOTFS the following GIT repositories are of interest.
Important remote branches are pandora-27-omap1 (Our ‘default’ kernel as of now) and linux-omap (synced with top of the mainline Linux-OMAP tree).
The important remote branch is master. This is our OpenEmbedded overlay (i.e. custom OpenPandora specific stuff we lay on top of OpenEmbedded/Angstrom to build our images).
The important remote branch is op.openembedded.dev, this is a snap shot from mainline OpenEmbedded with our queued patches stuffed on top. This serves as our feed tree for getting stuff into mainline OpenEmbedded/Angstrom (with a few clearly marked exceptions, look for checkins with HACK: in the commit message, these won’t be going to mainline ;)).
Should you with to manually clone any of the OpenPandora GIT repositories for whatever reason you can by issuing.
But if you just plan to build an image you have no need to do this as the setup script will take care of it for you.
Setting up your build environment for OpenEmbedded:
Using OpenEmbedded to build images is actually a pretty simple affair if done right however often steps are missed or done in the wrong order leading to all manner of spurious issues and resulting pain.
Security Warning: Never build your images as the ‘root’ user, there is no need to use a root account and doing so is a really bad idea, just make sure your normal user has control of the folder containing your OpenEmbedded environment.
To make the process as simple as possible I have knocked up a few simple support scripts that can just be installed to an appropriate place and run, hopefully setting up the environment correctly as they go.
These scripts are pretty crude and lack robust error checking and such so should be run with a note of caution. The idea is to improve them as we go.
Note: You will need LOTS of space to undertake a complete build of the ROOTFS, my typical build folders are often in excess of 100Gbyte :o. Make sure you have the space before you start ;).
1st off you need to pick somewhere on your system to construct the OpenEmbedded environment, this should be a path with no symlinks above it, a rebound mount point is fine however.
The user you want to use for builds will need control of this folder.
Open a terminal and change into the above folder that you wish to become the top level for your OpenEmbedded environment.
Get a copy of the setup scripts by running…
Once you have the files checked out run the environment script (you must run it with . ./op-env-oe.sh so it goes into the calling shells environment).
Now you have all the environment variables setup you can run the script that initialises the environment (creates folders, checks out the GIT’s etc.).
This will take a while to run as it creates directories, clones the necessary GIT trees and populates the environment. Now is a good time for the 1st coffee ;).
The next step is to switch from the tip of our GIT trees to the “Release-2010-05/1” tag.
This will ensure you are working with exactly the same metadata as the 1st release.
You can skip this step if you want to work with the latest and greatest code.
Note: If you want to you can later switch back to the tip of the GIT trees (development metadata) using ./use-tip.sh.
Be careful if you have uncommitted changes in your local GIT tree as the scripts will try and ‘git stash’ them but I suspect that may not be what you want.
Now your environment is all setup (assuming the scripts worked ok ;)) your build folder should look like the breakdown below, more folders will be created as soon as you run a build (folders for sources, package staging and temp data for example).
top of build area \
bitbake \ < Bitbake lives here.
local.conf < This is the file that tells OpenEmbedded about our setup.
openpandora.oe.git \ < Checkout of master from openpandora.oe.git
openembedded.git \ < Checkout of op.openembedded.dev from
user.collection \ < Area for any user created package recipes.
tmp \ < The temp area that all the building is done under.
The next step is to copy in the copy the PowerVR SDK you downloaded earlier into the right place in the build folder.
You need to copy OMAP35x_Graphics_SDK_setuplinux_3_01_00_02.bin into metadata/openembedded.git/recipes/powervr-drivers (so it ends up in the same folder as libgles-omap3_3.01.00.02.bb).
The command below should do it if you run it from the folder you downloaded the SDK into.
Now you want to do a simple test to check everything is working as expected.
From the top of your build directory run…
After a fair period of time (it will download and build a version of GCC to target the OpenPandora GCC so it can then use that GCC to build NANO ;)) you should have a successful build of the NANO text editing package.
Note: You can check this by looking in tmp/angstrom.5/deploy/glibc/ipk/armv7a to see the NANO ipk package (nano_2.0.9-r0.5_armv7a.ipk).
The ‘angstrom.5’ part of the path comes from the concatenation of angstrom and it’s internal distribution revision (currently 5).
Your now ready to move on to building something a little more complex…
Building the OpenPandora ROOTFS images using OpenEmbedded.
Now you have a suitable environment setup you can move on to building your 1st image.
Every time you open a new shell/terminal you will need to call the environment setup script to create the necessary environment variables, the rest of the setup is already done.
You have the full Angstrom and OpenEmbedded metadata at your disposal but for the purposes in hand there are a 2 main types of OpenPandora image stored in our OpenEmbedded overlay and 2 additional ones showcasing other Desktop environments.
You can see if a package is in a given image by looking at the corresponding recipe task file (found in metadata/openpandora.oe.git/recipes/tasks).
They are as follows (image name – task used).
- pandora-core-image – task-pandora-core
This image contains all of the core packages for the OpenPandora but lacks any GUI/X Server etc. – It is lightweight (reasonably) and obviously CLI. Ideal if your working on hardware drivers etc. and don’t need a GUI layered on top. It also features things like libPND baked in.
- pandora-xfce-image – task-pandora-xfce
This is the default OpenPandora image that ships on the NAND. It contains everything in the core image above and adds XOrg, Xfce and MiniMenu as the GUI elements. It also contains a myriad of GUI applications, scripts and the like as you would expect.
- pandora-desktop-image – task-pandora-desktop
This is an Enlightenment (E17) based variant of the Xfce image above, it’s not had much love for a little while but should broadly be comparable to the Xfce image if you swapped out Xfce for E17 ;). I am hoping this image will get a little love ‘post release’ to bring it in line with the Xfce image.
- pandora-gui-image – task-pandora-gui
This is a Matchbox based variant of the Xfce image above, it’s not had much love for a little while but should broadly be comparable to the Xfce image if you swapped out Xfce for Matchbox ;). This image feels very ‘PDA’ like and less ‘pocket Linux system’.
pandora-desktop-image and pandora-gui-image are not really images intended for end users but rather then remove them from the tree they have been left so interested parities can mess about with them.
Remember that building any of these images from scratch is going to take several hours even on the fastest of boxes.
Building the OpenPandora release image is now is as simple as running
from the top level folder of your newly created build tree. Make sure you have run the environment setup script first or it wont find your metadata.
If all goes well just go away and have a coffee (or 20) and check every now and then to see how things are going.
It’s going to take a good few hours to build everything and there may be the odd snags along the way, if you run into troubles drop me a line and I’ll see if I can help.
Note: Once the build finishes you can check the output in tmp/angstrom.5/deploy/glibc/images/omap3-pandora, with a little luck you should have a version of the pandora-xfce-image image ready to go. A tar.bz2 (ideal for extracting to an EXT 2/3 SD card) and a .ubifs.img (ready to flash to the NAND).
I’ll cover what you should do to get your newly generated ROOTFS running on the OpenPandora in the next article.
OpenEmbedded is a complex beast at the best of times and can often throw up issues when you least expect things. As long as your building on recent, fairly standard, Debian based (so Ubuntu et. all) type distributions you should not run into much trouble.
I can’t speak for distributions like SuSE, Arch, Fedora etc. as I don’t use them.
One known issue that seems to crop up (especially with the release-2010-05-1 metadata, I have a fix lined up for the trunk) is that the build will fail complaining about an issue with the ‘encodings’ package.
Should you see that issue the fix is very simple.
Then you just need to rerun whatever command you had run before (don’t worry, it won’t run all the steps again) and everything should be just fine.
The encodings issue is caused by mixed up dependences and cleaning it out and letting OpenEmbedded rebuild it sorts out those issues.
If you notice other issues do please let me know (or better still send patches).