Cross-compiling
[Tutorials]

Introduction

While Player is most often used on laptop- or workstation-class machines, it is also intended to run on less powerful embedded systems. Over the years, Player has been used on a variety of such systems, including the iPaq, Intel Stayton, nanoEngine, and Gumstix. These systems are not powerful enough to run a compiler, and they generally have a different architecture from your desktop machine (e.g., ARM instead of x86), which means that you need to cross-compile programs to run on them.

This document gives some guidance to help in cross-compiling Player. Beware that cross-compiling is fairly complicated, and that the information given here is by no means a complete treatment of the subject.

An example to work with

When cross-compiling, the build system is the one where the compiling is happening, and the host system is the one where the compiled program will eventually run. Throughout this document, we'll assume that you your build system is x86-linux (e.g., a Linux workstation or laptop) and that your host system is arm-linux (e.g., a Gumstix). This is probably the most common setup. If your situation is different, then just mentally translate the system-specific names used below.

Prerequisites

First, you need an x86-linux to arm-linux toolchain. There are a variety of ways to get a toolchain, including building it yourself from scratch. Unless you're looking to grow hair on your chest, I suggest getting a pre-built toolchain.

The toolchain must include C++ support, since much of Player is written in C++.

Note:: (Gumstix): In gumstix-buildroot/Makefile, set INSTALL_LIBSTDCPP:=true.

Player uses XDR for data marshaling, so the toolchain also must have a full RPC implementation that includes all the xdr_*() functions, in particular xdr_float() and xdr_double().

Note:: (uClibc): Set UCLIBC_HAS_FULL_RPC=y in the uClibc .config file.
(Gumstix): To effect the above change, set UCLIBC_HAS_FULL_RPC=y in gumstix-buildroot/uClibc.config.

Your toolchain will have a bin directory where the cross-compiling executable tools, such as arm-linux-gcc and arm-linux-ld reside. Add this directory to your PATH.

Note:: (Gumstix) : These tools are in gumstix-buildroot/build_arm_nofpu/staging_dir/bin.

Configuration

We'll use the builtin autotools support for cross-compilation. Basic configuration of Player goes like this:

$ ./configure --build=x86-linux --host=arm-linux

The configure script will automatically look for the arm-linux- tools, which should already be in your PATH.

The above configuration will build the default configuration of Player, which means that all drivers that can be built will be included. If you're looking to minimize the footprint of Player for your embedded system, you can enable just the drivers you'll need. For example, when I build Player to control a Roomba that is equipped with a Hokuyo URG laser, I configure it like so:

$ ./configure --build=x86-linux --host=arm-linux --disable-alldrivers --enable-roomba --enable-urglaser

Then only the roomba and urglaser drivers will be included. If you're only using your own plugin drivers, then you wouldn't need to --enable any drivers at all.

The default configuration also uses shared libraries if possible. This can complicate transferring Player to the embedded system because you have to copy a bunch of supporting files. I usually disable shared library support:

$ ./configure --build=x86-linux --host=arm-linux --disable-shared --disable-alldrivers --enable-roomba --enable-urglaser

Then I get a player binary that is statically linked and self-contained.

Compilation

Assuming configuration went well, all you need to do is:

$ make

One final step to save space is to strip the symbol/debug information out of the binary:

$ arm-linux-strip server/player

Then you're done: scp the binary to the embedded system and start playing with it.