• View
• Edit
• History
• Print
• Login

Build

Prev Next Edit this page to change styles

--- Boxes and outlines ---

--- Headers beyond ordinary "!" level headers

--- Stegi specific stylings ---

--- Text warnings, notices, hilights ---

--- Directory paths ---

--- Calendar specific --- The BeagleBox build system is a cross-compiling metabuild based on GNU Make and is designed to allow building any software stack component simply by specifying the appropriate make target. This includes building everything from the cross toolchain up through the applications.

Overview

The build system includes a help target that provides information on available targets. This page provides information on how to configure the build system.

The build system is based on GNU Make. It contains a Makefile that drives the build, a configuration include file called config.mk and a utility include file called util.mk. Additional software stack components are configured and managed by their respective "*.cfg" and "*.mk" files under the configs directory. Any changes to the build configuration should be handled through the respective files under configs. References to new configurations should be appended to the appropriate sections of the top level config.mk file.

Build Configuration Files

BeagleBox has five major software components that it builds: a cross compiler, a bootloader, the Linux Kernel, a core root file system and BeagleBox specific applications.

The build configuration is handled by *.cfg files in the configs directory. Software components may be built based on different source repositories on the Internet. Examples are gitorious.org or kernel.org. The *.cfg files are meant to allow an easy way to build for specific repositories using nothing more than a single environment variable setting on the make command line.

Some software components have multiple configurations. If you're familiar with OpenEmbedded, Angstrom or Yocto you can think of the configurations as recipes. There is one default recipe for each software component. Other recipes can be selected by providing the recipe name in the component's environment variable.

The following components currently offer multiple recipes.

The value of the environment variable selects a configuration found in the file

   configs/<component>-<value>.cfg

For example, KSRC=git selects conigs/kernel-git.cfg when doing the build of the Linux kernel.

To add new configurations, create a configuration file under configs and make sure it is added to the appropriate configuration header, such as configs/uboot.cfg or configs/kernel.cfg.

Overview of the build process

The order of build is important. Each component is listed here with its GNU Make target prefix.

1. Cross Compiler (xcc-)
2. Bootloaders (uboot-)
3. Linux kernel (kernel-)
4. Root File System (buildroot-)
5. Applications (TBD)

The cross compiler must be built first. All other build targets depend on it and it will get built if it is not already built.

The boot loader is builds a version of Das U-Boot, an open source boot loader that has extensive OMAP and BeagleBoard support.

The kernel targets build a kernel appropriate for the type of support required by the user. By default, the kernel must support S-Video (re: TV out) displays using DSS2, which is the latest version of the TI OMAP display support in the kernel.

The root file system utilizes Buildroot, an open source utility that makes creating embedded root file systems easy. The default root file system is targeted at basic services support for BeagleBox and is used to integrate additional applications such as BUI, the BeagleBox user interface.

All components have a build target that will show the current configuration. The displayed configuration may depend on environment variables set on the command line. For example, to see the configuration being used when building the Linux kernel using the kernel.org git repository, use the following command.

   make KSRC=git kernel-showconfig

Most software components have a target that allows editing and saving the configuration file given the selected repository configuration. The following example shows how to edit the kernel configuration, compare it with the currently saved configuration, and then save the updates. Once saved, future builds will use that configuration.

   make KSRC=git kernel-menuconfig
   make KSRC=git kernel-meld
   make KSRC=git kernel-menuconfig

Default Build

A default build can be run by simply running the make command.

   make 
   make pkg

This will build each component, in order as listed above. It will also use the default configurations which should be appropriate for user intending to use BeagleBox as it is intended to be used. Only BeagleBox developers need doing builds any other way.

The pkg target will collect the build files required to be placed on the SD card. These files will be in $GM_PKG.

   cdp
   ls -l 
   mjhammel(tty5)$ ls -l
   total 70016
   -rw-rw-r-- 1 mjhammel mjhammel     2814 Dec  1 20:29 boot.scr
   -rw-rw-r-- 1 mjhammel mjhammel 68368733 Dec  1 20:29 ramdisk.gz
   -rwxrwxr-x 1 mjhammel mjhammel   196908 Dec  1 20:29 u-boot.bin
   -rw-rw-r-- 1 mjhammel mjhammel  3035456 Dec  1 20:29 uImage.bin

Make the SD card

The SD card should be formatted with two partitions. The first is a FAT16 partition and the second does not need to be formatted. Copy the following files, in this order (one at a time) to the first partition on the SD card.

1. u-boot.bin
2. uImage.bin
3. boot.scr

Then copy the root file system to the second partition.

   gzip -d ramdisk.gz
   dd if=ramdisk if=/dev/mmcblk0p2 bs=16384

BeagleBox is a Metabuild

BeagleBox is a metabuild. That means that while the project includes code in its source tree its main purpose is to download and compile packages from the Internet. One level up from the BeagleBox source are directories used to store downloaded files (known as the component archives) and unpacked source packages and their compiled binaries. When a component build starts it checks the component archive for the configured source. If not found, the source is downloaded. Then the source is unpacked in the build tree and compiled. The build tree may contain a directory for the unpacked source and a directory where the compiled source ends up.

Getting Started with a Build

If you've saved your environment setup script properly, you're ready to start. The steps for the first build are as follows:

1. Invoke the environment setup script
2. Grab the source
3. Change into the project src directory
4. Start your build!

The commands to use if you download a released source package are as follows. We assume you've named your environment setup script function beaglebox as in the example above.

 > beaglebox
 > cdh
 > wget http://voxel.dl.sourceforge.net/sourceforge/beaglebox/PhaseII-BeagleBoard/V0.4.0/beaglebox-0.4.0.tar.gz
 > tar xvzf beaglebox-0.4.0.tar.gz
 > mv beaglebox src
 > cdx
 > ls
 CVS  ChangeLog  Makefile  config.mk  configs  docs  scripts  src  util.mk

The commands to use if you check the code out of CVS are as follows:

 > beaglebox
 > cdh
 > cvs -d:pserver:anonymous@beaglebox.cvs.sourceforge.net:/cvsroot/beaglebox login
 > cvs -z3 -d:pserver:anonymous@beaglebox.cvs.sourceforge.net:/cvsroot/beaglebox co -P -d src beaglebox
 > cdx
 > ls
 CVS  ChangeLog  Makefile  config.mk  configs  docs  scripts  src  util.mk

At this point, in the future, you just need to open a terminal window, type the shell function name and start working.

 > beaglebox
 > cdx
 > ls
 CVS  ChangeLog  Makefile  config.mk  configs  docs  scripts  src  util.mk

The BeagleBox Source Tree

The top level Makefile is used to drive the BeagleBox build. It is very terse, intended only to provide the most common targets and to provide the base from which software stack component configurations and make targets can be included. It is highly unlikely you'll ever need to edit the top level Makefile. At least, that's the goal.

The companion file to the top level Makefile is the top level config.mk. This include file provides common configuration as well is including configurations and make targets for all other components of the BeagleBox software stack.

Another companion configuration file in the top level directory is util.mk. This include file provides utility targets and definitions. This includes targets for downloading files from a remote archive and definitions which can add color to your output based on xterm escape sequences. There is nothing in this file that requires changes to make the build work though updates to it are welcome to extend the capabilities of download and archive management utilities.

The current BeagleBox software stack components are as follows.

1. Cross Compiler
2. Boot loader
3. Linux Kernel
4. Root file system
5. Applications

Cross Compiler

The Crosstools-NG cross compiler toolchain is used to generate the appropriate ARM cross compilers for BeagleBox. Different compiler toolchains are built depending on whether you are building for QEMU or the BeagleBoard.

The default is to build a toolchain appropriate for use with building software for the BeagleBoard. To build for QEMU set the HW environment variable on the make command line, as in the following example.

   make HW=qemu xcc

Notes for building the cross compiler:

• Fedora 11: You must install glibc-static package. If you don't then the ncurses build performed by Crosstool-NG fails with the following in the build.log:

• Any Fedora: Crosstools-NG requires gcj. It doesn't recognize Sun's java. On Fedora, install gcc-java.
• Any platform: Downloading of some packages required by Crosstool-NG, usually ejc-latest, can hang. If this happens, make note of which package is currently being downloaded (displayed where the build is running/hung), kill the build with Ctrl-c and then remove that package from the download archive and restart the build:
  • cdb; cd crosstool-ng-*.bld/work/tarballs
  • rm <package>.<suffix>
  • cdx
  • make xcc

Boot loader

There are two boot loaders for the BeagleBoard. The first is called the X-Loader. It's purpose is to provide minimal support for loading the second boot loader, u-boot.

X-Loader

The X-Loader gets run by the hardware at boot time. It's known as a 2nd stage loader (the 1st stage is the boot rom which is unlikely to ever be modified by BeagleBox). It exists in order to create a common boot loader for all OMAP hardware. It is intended to call a 3rd stage boot loader such as u-boot.

The X-Loader is unlikely to require modification for use under BeagleBox. Therefore it's build and source management is left to external resources. BeagleBox is simply a user of that product. Chances are good that you will seldom have to update the X-Loader on your BeagleBoard.

Notes on the X-Loader

• Most C4 and later BeagleBoards provide a boot loader capable of booting directly off the SD card. Because this is sufficient for use with BeagleBox you should not have to upgrade the X-Loader. However, you are welcome to upgrade the X-Loader if you want. Compiled binaries of the X-Loader can be found in the Angstrom archives.

Das U-Boot

The 3rd stage boot loader for BeagleBox is u-boot. This boot loader will provide initialization of hardware components required by BeagleBox specifically on the Beagle Board. BeagleBox defaults to using the mainline version of Das U-Boot as most board support has been pushed upstream from developer repositories. BeagleBox also provides recipes for building from various other u-boot related repositories.

Linux Kernel

The Linux Kernel provides the base operating system for Beagle Box. Current and fairly good TI OMAP and specifically Beagle Board support can be found in the 2.6.34 or later kernels however there are multiple repositories that provide varying levels of support for different board features.

The default configuration for the Linux kernel is to use the repository managed by the developer of the OMAP DSS2 support, Tomi Valkeinen. This repository provides the best S-Video (re: TV out) display support utilizing the newer DSS2 driver design.

On top of the DSS2 support are requirements to utilize the PowerVR SGX graphics accelerator and video hardware acceleration through the DSP core in the OMAP processor. SGX support will provide 3D and OpenGL/ES features to BeagleBox, which in turn may be utilized by Flash in web videos. Original support for SGX kernel drivers exists only in TI's PSP SDK which is based on the 2.6.32 kernel. The SGX kernel driver support is currently being ported from TI's PSP SDK into the Linux kernel mainline. If this upstream push is delayed then BeagleBox may forward port the support manually to Tomi's tree which uses a more recent 2.6.37 kernel. User space libraries for the SGX driver are binary only and must be pullled from the TI PSP SDK. The root file system build handles this user-space library installation.

OMAP DSP support requires use of a bridge driver. This driver is not yet integrated into BeagleBox but is planned.

Notes on the Linux Kernel

• Applying collections of patches to the Linux kernel requires the use of quilt. You must install this for you distribution. On fedora:
  • sudo yum -y install quilt

Root file system

The root file system is built using Buildroot. This is a metabuild system that can build the cross compiler, kernel and root filesystem. However, BeagleBox builds these components separately to make it easier to make changes to any one of them without affecting the others. BeagleBox uses Buildroot strictly for creating the root filesystem.

The base root file system will build a generic X.org based interface running a stock window manager. This will form the basis of further development of the BeagleBox UI.

The 2010.05 stable release of Buildroot provides a baseline for BeagleBox root file system builds. This requires some patches to work properly.

Patches

The Buildroot build includes a variety of patches. Some of these address build errors within Buildroot itself. Others apply new packages to the build, such as xterm and surf. These patches are applied automatically by the BeagleBox build system.

Applications

TBD

Why Not OpenEmbedded/Meego/Linaro/Yocto?

There are a plethora of metabuild systems for various platforms available for the TI OMAP based boards like the BeagleBoard: OpenEmbedded, Linaro, Meego, etc. A metabuild is a high level build system designed to produce a specific product. The product is a collection of software from multiple locations, including custom software contained within the metabuild or retrieved from private archives. The goal of the metabuild is generate the files and/or images that are placed on a platform to get it to run.

Desktop distributions such as Fedora and Ubuntu use their own metabuilds. A project like BeagleBox has a very specific purpose unlike a general purpose desktop. The metabuild must be very specific to the end product. OpenEmbedded is the Swiss Army Knife of embedded distributions. But one size does not fit all in the embedded world and OpenEmbedded can be daunting to deal with considering the excess weight it carries with respect to the goals of BeagleBox.

Therefore, BeagleBox is built from the ground up so that only the components desired for BeagleBox are part of the metabuild. BeagleBox is not intended to support a large number of hardware platforms. It is targeted specifically at one: the BeagleBoard (and its derivatives, most likely).

There are other reasons, of course. Angstrom and Yocto are based (at least in part) on OpenEmbedded and OpenEmbedded is based on bitbake, a build system similar to make that is based on Python. Python is an excellent general purpose scripting language. GNU Make is a build environment. I prefer to use tools for which they are intended. Python can be very useful in builds. Make is a better top level driver of build tools. It provides structure and format specific to building software that Python, by its general purpose nature, does not. I don't mind calling python from Make, but the driving environment should be Make and not Python.

Scons is another build tool. It's description of the limitations of Make seem meaningful but not applicable to BeagleBox goals. Therefore, I chose not to use Scons either.

Another reason for not using other metabuilds is that I believe in understanding things from the ground up. BeagleBox could use existing images from OpenEmbedded and build on top of them. But where is the fun in that? Wouldn't you rather know what is happening under the hood? If, after all, all you want to do is use the system, then BeagleBox is not the place to hang out. We're here because we're DIYers. And we want to know why things work.