Cross compilation occurs when a compiler running on one system produces executables for another system — this is an important concept when the target system doesn't have a native set of compilation tools, or when the host system is faster or has greater resources. In this how-to article, Peter Seebach discusses the initial setup of a cross compilation environment (using the Sharp Zaurus handheld as focus)… and covers the installation of tools, basic compilation, installing programs on the handheld, and such advanced issues as building programs that use configure scripts.

Other than the obvious benefit of compatibility, cross compilation is quite important for two reasons:

1. When the target system doesn't have a native set of compilation tools available to it.
2. When the host system is dramatically faster, or has greater available resources, than the target system.

In this article, I'll discuss the initial setup of a cross-compilation environment, using the Sharp Zaurus series of handheld computers as a focus. I'll cover the installation of tools, basic compilation issues, how to install programs on the handheld, and such advanced issues as building programs that use configure scripts. You'll benefit most if you follow the article as it is structured because the article is written similar to a tutorial, with steps that follow each other in logical order.

First, I'll give you a concise overview of cross compilation.

Understanding cross compilation

If you're familiar with cross compilation environments, you can skip this section. However, if cross compilation is new to you, read on.

The development system I used is an x86-architecture Linux system. I tested these instructions on SuSE Linux 8.2. The target systems tested were the Sharp Zaurus SL-5600 and C700. This article assumes that you have a working knowledge of the basics of Unix development practices, including using the command line.

As I mentioned earlier, cross compilation occurs when a compiler running on one system produces executables for use on another system and the systems do not use the same operating environment. Also, this is useful when the target system doesn't have its own compilation tools or when the developer can leverage the host system's potentially better performance or greater resources.

When referring to a cross-compiler, I not only mean just the software that translates code in a programming language into object code, but also the rest of the necessary development tools:

• An assembler, which is part of the back end of the compiler tool chain
• A linker, which is the other part of a compiler tool-chain back end
• Some basic tools for manipulating executables and libraries, such as strings

For instance, the strings utility (which prints the text strings of an object module) might be useful, but a host-environment version won't do much good for target-environment binaries. The cross-development tools for the Zaurus include strings.

It is possible to run compilers natively on a Zaurus, but the system's limitations are barriers to efficient work, another reason that makes cross compilation such a boon for developers. The display and keyboard of a typical desktop machine deliver a substantial advantage for editing work. Also, the memory, processor, and storage of a desktop machine are more suited to the resource needs of compilation.

Now, let's install the required tools.

Installing the tools

1. To start, you must download several packages. These packages are available from Sharp's Web site (see Resources for a link), and must be downloaded as RPMs. You need the following main packages:
   • The cross compiler (gcc)
   • The libraries (glibc)
   • The include files (header files)
   • The “other tools” — a package containing commonly-used tools for the cross-development environment

2. Next, you'll install the RPMs. To do this, you need root privileges. The suggested installation method is rpm -Uvh filename.rpm repeated for each file.

   The files are installed in a /opt/Embedix directory. This directory has a slightly unusual structure — the actual binaries are installed in the /opt/Embedix/tools/bin directory, with symbolic links to these binaries installed in a the /opt/Embedix/tools/arm-linux/bin directory. For example, /opt/Embedix/tools/arm-linux/bin/gcc is a symbolic link to /opt/Embedix/tools/bin/arm-linux-gcc. Either can be used.

3. Quickly test that the tools have been correctly installed by compiling a simple test program. I recommend the traditional “Hello, world!”, which is easy enough to test:
   

   #include int main(void) { printf("Hello, world!"); return 0; }

4. Save this in a file called hello.c and compile it. Either path to the compiler will work — I prefer to use /opt/Embedix/tools/arm-linux/bin/gcc. After you have compiled the program, check the type of the output file with the file command.

Listing 2. Using the file command to check type of output

$ /opt/Embedix/tools/arm-linux/bin/gcc -o hello hello.c
$ file hello
hello: ELF 32-bit LSB executable, ARM, version 1 (ARM), 
dynamically linked (uses shared libs), not stripped

This brief digression might be of interest to you. Remember when I mentioned the strings program? Let's try it.

First, run the native strings program on your binary:

Listing 3. Running the native strings program

$ /usr/bin/strings hello

Next, run the ARM version on the same binary:
Listing 4. ARM version

$ /opt/Embedix/tools/arm-linux/bin/strings hello

On my test system, these produced slightly different results. The ARM-specific strings program found a few strings the i386-specific version didn't. Neat!

Now, let's test the program on the target system.

Installing applications on the target system

There are several ways to move files to the target system. They can be:

• Transferred using the standard Zaurus sync software
• Copied onto media
• Moved over a network

Using a wireless card or Ethernet adapter is probably the easiest way to move files. Failing that, copying them onto CompactFlash or SecureDigital media is fairly convenient. Unfortunately, as of this publishing, Sharp doesn't officially support sync under Linux, but copying to media works everywhere.

Depending on the ROM version on your Zaurus, the system might not recognize or mount ext2fs cards. Therefore, it might be more practical to copy files over on FAT16-formatted cards. CF and SD cards generally ship formatted this way, so they should work right out of the box.

(A quick glossary tip: An ext2fs card is a storage card formatted for the Linux filesystem. A FAT16-formatted card is a storage card formatted for the old MS-DOS filesystem. A CF card is CompactFlash, a media standard used with some digital cameras; most CF devices are storage, but CF Ethernet, wireless, and serial adapters also exist. An SD, or Secure Digital card, is a relation of the MultiMediaCard technology and for our purposes, an SD card is like an MMC card with about 10 percent of its space permanently reserved.)

Just copy your executable file over to a mounted card. When you move the card to the Zaurus, it should be automatically mounted as /usr/mnt.rom/cf. You can now run your application from the card.

Listing 5. Run the application from the card

$ /usr/mnt.rom/cf/hello
Hello, world!

Now that you've tried this, you'll probably appreciate the Zaurus's ipkg binary package format more. An ipkg file is simply a tar file containing three other files:

• The first file, data.tar.gz, is a compressed tar file containing the files to be installed in the correct directory structure.
• The second file, control.tar.gz, is a compressed tar file containing installation scripts and information.
• The third file, debian-binary, is a plain text file containing the string “2.0”. This file might not actually do anything at the moment, but some tools expect it to be available.

Although there's a convenient script available to do the work for you, you can manually create ipkg files. In case you do want to manually create one, I'll discuss the format of the package briefly. This package will install the “hello” program correctly, using the standard software installer that you would use.

1. Create a new directory named h to store the files in. The name doesn't matter, but you'll type it a lot so use a short one.
2. Create a subdirectory called h/opt/QtPalmtop/bin and copy your “hello” executable file to it. This is a good directory for installed programs to show up in.
3. Create a directory called h/CONTROL. This directory forms the contents of the control.tar.gz file; everything else in h is put into the data.tar.gz file. In this directory, you need only one file, called control. Put the following data in this file:

   Listing 6. The info that goes in the control file

   Package: hello Priority: optional Section: Misc Version: 1.0 Architecture: arm Maintainer: Your name ([email protected]) Depends: libc6 Description: Just as stores have greeters, so to do PDAs have greeters. This is a longer description, separate from the first one, which can be multiple lines long, with each line indented by a single space.

   There are other files you can put in the CONTROL directory, but you don't need them. Refer to Resources for additional information on this in the Zaurus developer documentation.

4. Run ipkg_build.sh h. If you've done everything correctly, you should get a file called hello_1.0_arm.ipk. Copy this file to your Zaurus — it doesn't matter how — and run the Add/Remove Software program on the Zaurus.
5. Install the hello, version 1.0 file that you should see in your list of packages. You can now run it from the command line; it's been copied into the /opt/QtPalmtop/bin directory. If you install it to one of the media slots instead of to internal flash, it will be in the QtPalmtop/bin directory on that card. For instance, if you install to SD, it will be installed as /usr/mnt.rom/card/QtPalmtop/bin/hello.

The ipkg_build.sh shell script is pretty efficient about generating error messages, but they might be a bit confusing. In particular, if you try to put comments in your control file (as I did!), the # character is interpreted as a field name, producing the following error message:
Listing 5. Oops! Keep the comments out of the control file

*** Error: The following fields in CONTROL/control are missing a ':'
		###
ipkg-build: This may be due to a missing initial space for a multi-line field value

This was a bit confusing the first time I saw it.

Complex compiles

Once you have the compiler creating executables that run correctly on the target system, you might start running into the exciting problems.

Programs that use autoconf might not support cross building. The only really hard-and-fast case occurs when compiled binaries are used in the build process. Unfortunately, for programs that use autoconf, this can be a fairly common situation.

For a fairly standard program without too many dependencies, you can probably just override the selection of the C compiler. FIGlet, a program for making large letters out of ordinary text, as in Figure 1, can be built by changing the CC=… line in the makefile. However, the installation is a little more interesting.

Figure 1. Sample FIGlet output for text “like this”

FIGlet wants to find some data files, so you must install both the data files and the program. The relevant line in the makefile is DEFAULTFONTDIR = /usr/local/share/figlet. (Note that there are two lines setting DEFAULTFONTDIR; make sure you only have one line setting it when you're done.)

Once you've built figlet with the changed makefile, it's time to build a package of it. Create a new directory (here called f).

This time, create a binary directory and a data directory. The binary directory is f/opt/QtPalmtop/bin, and the data directory is f/usr/local/share/figlet. Copy figlet, chkfont, and showfigfonts into f/QtPalmtop/bin; then copy fonts/* into f/usr/local/share/figlet.Copy in the CONTROL directory from the last project and edit the control file to give the package name and version. Once again, build-ipkg.sh can do the dirty work for you.

Some programs might require a bit more trickery. For instance, to build pdksh, you use CC=/opt/Embedix/tools/bin/arm-linux-gcc sh configure. This build makes one small mistake — it defines two macros, SIZEOF_INT and SIZEOF_LONG, both to 0. They need to be 4.

These macros are defined by trying to compile and run test programs that print sizeof(int), but of course, the arm-processor programs don't run on the x86 host, so these tests fail. In this case, you can just edit the confdefs.h file, change the macros, and continue. This is not hard to fix once you know what's wrong, but what's wrong isn't immediately obvious. It might have been nicer of the configure script to abort with a fatal error when it determined that a type appeared to have a size of zero.

More recent versions of autoconf might be able to work around this problem using a clever hack. Simply rerunning a current autoconf on the configure.in file might help some problems, especially if a package is out of date, but there's occasionally some bit rot in old configure.in files.

In the more general case, you might simply have to manually edit configuration scripts or setup programs to force them to yield the correct results. In extreme circumstances, it might be necessary to try elaborate hacking, such as running the configuration script locally on a Zaurus with native development tools installed, then move all the files back to a desktop development system, change the compiler path, and start from there.

The wind-up

A lot of developers are hesitant to try cross compilation, because it sounds a lot harder than it is. This article has hopefully gotten you started by delivering an overview of cross compilation, offered some examples of setting up a system to implement cross-compiled programs, and provided resources to help you set up a system to develop for the Sharp Zaurus handheld.

Resources

• The Zaurus source code is Embedix Plus, the Embedix Linux (kernel 2.4.x) from Lineo, the Qt/Embedded GUI application framework from Trolltech, the Opera Web browser from Opera, and the Jeode JVM from Insignia.
• You can download the available Source Codes for Linux Commands for Zaurus development.
• This article describes how to build ipkg files.
• This how-to article shows you the way to set up the Linux cross-compiler.
• “PalmOS-hosted programming languages” (developerWorks, August 2001) by David Mertz and Andrew Blais, looks at development environments that can work directly on the handheld, bypassing the need to develop on the desktop, then cross-compile.
• “Xmingwin for cross-generating apps” (developerWorks, January 2003) by Cameron Laird provides a practical example of cross compilation by generating Windows programs from a Linux server.
• “Looking through wxWindows” (developerWorks, February 2001) by Markus Neifer introduces wxWindows, the portable C++ and Python GUI toolkit, and discusses how to deal with multiplatform file handling.
• This Redbook tip details how to configure gcc on Linux to act as a cross-compiler.
• The Zaurus developer site is a roundup of resources for the developer.
• The FIGlet site offers the code for the text-conversion software mentioned as an example in this article.
• Here you'll find the ipkg-build script.
• Two Java-specific development tools for Zaurus include a PDF guide on Java programming for the Zaurus and ZaurusBuilder, a JBuilder IDE plug-in wizard that manages the packaging of Java applications into an IPK distribution file for installation.
• The Zaurus Java FAQ answers questions on using and developing for Zaurus in Java.
• The Qt products for Zaurus programming include an open source SDK for Qtopia, a PDF programming guide for setting up and using Qt/E and Qtopia, and the free version of Qt/E.
• Learn more about the open source development project (its past and current specifications) for the Zaurus at the OpenZaurus project Web site.
• For Zaurus tools and compilers and SDKs, take a look at this site.
• Use the Zaurus themes section if you want to change the look of your Zaurus background, icons, and environment.
• The ZUG (Zaurus User Group) provides developers with volumes of experienced input.
• This unofficial Zaurus development FAQ provides much useful information.

About the author: Peter Seebach is a freelance writer. He collects interesting gizmos, and the Zaurus seemed a natural addition to the family. He's been playing with compiler toolchains and porting programs for longer than he's comfortable talking about. You can reach him at
dwwireless()seebs!plethora!net.

First published by IBM developerWorks. Reproduced by LinuxDevices.com with permission.

Related Links:

• Device preview: Sharp Zaurus SL-C700 VGA resolution PDA
• Device Profile: Sharp's Zaurus SL-5500 Linux PDA
• ELJonline: Applications for the Sharp Zaurus
• OpenZaurus Project

 
This article was originally published on LinuxDevices.com and has been donated to the open source community by QuinStreet Inc. Please visit LinuxToday.com for up-to-date news and articles about Linux and open source.