Building prc-tools

Prc-tools is built regularly on Linux and Cygwin, and should build without too much trouble on other Unix-like systems. These regular builds are done either with the RPM spec file prc-tools.spec or with the prc-tools.build script. While we make every effort to keep these instructions up to date, those two files should be considered to represent the canonical tested build procedures.

Problems encountered while building prc-tools are likely to be bugs in the build scripts, makefiles, or procedures, and we would like to hear about them. The prc-tools-devel mailing list is the right place to report difficulties in building prc-tools itself. (But it is not the right place for difficulties encountered while using the tools.)

In this document, we use prc-tools-srcdir to refer to the top level source directory for prc-tools. If you are working from CVS, this directory's name will be simply prc-tools. If you have downloaded a source tarball, it will be something like prc-tools-2.1.

Prc-tools and Palm OS SDKs

Prc-tools contains both host tools which run on your development computer and run-time support code which is linked into your application. Header files of some kind describing how to call several Palm OS API functions are needed to compile this run-time support code.

For a Palm OS application, these header files are provided by a Palm OS SDK. However, the audience for prc-tools is different: It is often built by people, such as system administrators and OS distributors, who may not themselves be Palm OS programmers. It is unreasonable to require such people to first obtain a separate non-redistributable SDK that they may not subsequently wish to use, just so that they can compile a small part of this package.

Hence prc-tools contains header files (in the bootstrap subdirectory) which declare just enough Palm OS API functions and related machinery to compile the run-time support code. Thus prc-tools itself can be compiled by itself, without requiring any separate Palm OS SDK to be installed on the build system. (Of course people later using prc-tools will likely need to obtain an SDK themselves if they wish to write non-trivial applications.)

See Debian bug #78745 and bootstrap/Makefile for further details of this arrangement.

Build tools required

You will need to have a unidiff-capable implementation of patch, a C compiler, a C++ compiler, lex or flex, and yacc or bison installed. Some of the post-linker tools are written with C++ and STL, so if you are using GCC you will need at least egcs 1.1.1 or so, or any GCC 2.95. If your normal gcc or cc is earlier than this but you have a recent GCC installed as, e.g., gcc295, you can specify that the tools be built using the non-default compiler by defining variables for the configure command:

~/build$ CC=gcc295 CXX=g++295 ../prc-tools-srcdir/configure ...etc...

Particularly if you are a maintainer working on prc-tools, you may also need the following:

If you do much work on the configuration files or are working from CVS, you'll need autoconf. At present, prc-tools requires autoconf 2.13 or so rather than one of the more recent (and not entirely compatible) 2.5x versions.
If you are working on the run-time support code, you may need to update the bootstrap headers. A Palm OS SDK and some Palm OS device (such as Poser and a ROM) are needed to do this, because the headers are generated by running a Palm OS application, GenBootstrap.
If you want to generate the HTML documentation, you'll need texi2html (version 1.64 or later; previous versions do not understand the options with which prc-tools invokes it).

Unpacking and patching the sources

This prc-tools package contains source code for the post-linker tools and run-time support on the device, and patches against binutils-2.14, gdb-5.3, and gcc-2.95.3 and gcc-3.3.1. You will need to download source for each of these packages separately, either from a GNU mirror or from http://prc-tools.sourceforge.net/misc/.

At present only the C and C++ languages are supported, so you can download and unpack only the gcc-core and gcc-g++ packages instead of the entire gcc package if you wish.

(Note that the patches are in unified diff format and some patch implementations, notably on Solaris, do not handle this format correctly. If you are thus afflicted, we recommend using GNU patch instead.)

Once you have downloaded the packages, you need to unpack them and apply the patches:

~$ tar xfz prc-tools-2.1.tar.gz
~$ tar xfz binutils-2.14.tar.gz
~$ tar xfz gdb-5.3.tar.gz
~$ tar xfz gcc-2.95.3.tar.gz
~$ tar xfz gcc-3.3.1.tar.gz
~$ cat prc-tools-srcdir/*.palmos.diff | patch -p0

Finally, you need to make the GNU packages available to prc-tools's configure script and top-level Makefile so that building all the packages can be integrated into just one build:

~$ cd prc-tools-srcdir
~/prc-tools-srcdir$ ln -s ../binutils-2.14 binutils
~/prc-tools-srcdir$ ln -s ../gdb-5.3 gdb
~/prc-tools-srcdir$ ln -s ../gcc-2.95.3 gcc295
~/prc-tools-srcdir$ ln -s ../gcc-3.3.1 gcc
~/prc-tools-srcdir$ cd ..

At present, the m68k compiler will be built from gcc295 and the ARM compiler from gcc; if you are only building one of them, you can omit the other directory. (In the future, the m68k patches will be ported to GCC 3.x, and the gcc295 directory will disappear.)

(On Windows, if you use any non-Cygwin programs in your build, you should use mv instead of ln -s since non-Cygwin programs can't see through Cygwin's symlinks.)

You can optionally generate HTML versions of the documentation for prc-tools, binutils, GDB, GCC, and also for make. To generate the make documentation, you'll also need to make GNU Make source code available similarly, as prc-tools-srcdir/make. (Due to recent rearrangements in the make package, this requires at least version 3.80 of GNU Make.)

Configuring

It's recommended that you configure and build these packages in a directory separate from their source trees:

~$ mkdir build
~$ cd build
~/build$ mkdir empty
~/build$ ../prc-tools-srcdir/configure --target=m68k-palmos \
	 --enable-languages=c,c++ \
	 --with-headers=`pwd`/empty

(Source tarballs contain the configure script, but CVS does not. If you are building from CVS you'll have to use autoconf -- 2.13, not 2.5x -- to regenerate it from configure.in first.)

The parameters shown above must be given, with whatever values are appropriate, because their defaults will cause problems. In addition to the standard configure options, the following options can be used:

--enable-targets=m68k-palmos,arm-palmos: Sets multiple target platforms for the tool chain: binutils, GCC, etc will be built for each target, and the generic tools in tools will be configured for all of the given targets. You must use this or --target, but not both.
--target=m68k-palmos: Sets the target platform for the tool chain. The target used in prc-tools-0.5.0 was m68k-palmos-coff; dropping the -coff now will ease a potential future move to ELF, and just plain makes more sense. But at the moment m68k-palmos is merely an alias for m68k-palmos-coff, so you can use the full name for compatibility with prc-tools-0.5.0 for now if you like.
--enable-languages=c,c++: Only build C and C++ compilers. In particular, the Objective-C runtime hasn't been ported to Palm OS, so objc won't work here.
--with-headers=`pwd`/empty: GCC fixes system headers by filtering out non-ISO standard constructs. Pointing it at an empty directory like this effectively suppresses that behaviour -- which may or may not be the best idea, but it makes life easier for now. :-)
--with-palmdev-prefix=/opt/palmdev: This is where the tool chain will look for Palm OS SDK headers and libraries and so on. You can put this wherever you like; by convention, we use /opt/palmdev on Unix and /PalmDev on Windows. By default, the tool chain will look in /opt/palmdev.
--enable-html-docs[=/path]: Generate HTML-formatted documentation for prc-tools and also whichever of binutils, GDB, GCC, and make have been made available within the source tree. By default, generation of HTML documentation is disabled. If you enable it, you can specify where the resulting HTML files should be installed, or, if you omit the optional directory argument, palmdev-prefix/doc will be used by default.

Building and installing

You can build and install prc-tools just as you would any other package:

~/build$ make
~/build$ make install

You may need to change user (e.g. to root) if you are installing to directories to which your usual user doesn't have write access.

In the past, building prc-tools was a tedious multistage process of

building and installing binutils;
building and installing GCC;
building the Palm OS runtime code.

This multistage process was needed because GCC required an installed Palm OS binutils before it could be built, and in turn the run-time support code (such as that in the crt subdirectory) needed both binutils and GCC to be installed before it could be built.

The top-level prc-tools Makefile now tells the GCC build process to use an uninstalled binutils from ~/build/binutils, and tells the target run-time build process to use an uninstalled GCC from ~/build/gcc and the same uninstalled binutils. Thus later stages of the build use the tools you have just built from the places in which you have built them, instead of requiring the previous intertwined build/install process.

If you use one of the lower level makefiles directly, or if you have omitted the binutils or gcc directories from your source tree, the build processes will fall back to using the respective installed utilities from your PATH. The build will fail unless you have previously installed such utilities.

There are further details in the GCC distribution's install directory and also in the Cross-FAQ, if you run into problems.

To the prc-tools website