Building prc-tools

Prc-tools builds easily on Linux, should build without too much trouble on other Unixes (any problems encountered are bugs and I would appreciate hearing about them), builds with some effort on Windows NT with Cygwin, and doesn't have a hope on Windows 95. (The build process simply creates too many processes too fast for Windows 95 -- though a recent bug fix to Cygwin's fork() may have resolved this.)

Before you start

You need to have at least one Palm OS SDK installed. Prc-tools contains both host tools which run on your development computer and run-time support code which is linked into your application. To build this support code, you will need a set of Palm OS header files. (Indeed, you may wish to install several versions of the SDK, and switch between them for different projects.) By convention, prc-tools looks for SDKs in /usr/local/palmdev on Unix, or C:\PalmDev on Windows. (You will get to configure where GCC looks for SDKs later. These are the values which the prebuilt binaries use on the various platforms, and it seems like a useful convention to follow.)

You should install the SDK(s) you have selected into the directory you have chosen. You may also wish to create a symlink for a `default SDK'. For example, for a base directory of /usr/local/palmdev, the tree structure should look something like

/usr/local/palmdev/sdk-2/include/Core/...
/usr/local/palmdev/sdk-3.5/include/Core/...
/usr/local/palmdev/sdk-3.5/lib/...
/usr/local/palmdev/sdk -> sdk-2

You'll also need various software development packages:

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.9.1, gdb-4.18, and gcc-2.95.2. You will need to download source for each of these packages separately. Prc-tools also includes patches to generate HTML documentation for make; if you want to generate this, you will also need make-3.77 source code.

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

~$ tar xfz prc-tools-2.0.tar.gz
~$ tar xfz binutils-2.9.1.tar.gz
~$ tar xfz gdb-4.18.tar.gz
~$ tar xfz gcc-2.95.2.tar.gz
~$ tar xfz make-3.77.tar.gz
~$ cat prc-tools-2.0/*.palmos.diff | patch -p0
(Omit make-3.77.tar.gz and make-docs-3.77.palmos.diff if you don't want to generate make documentation.)

On Windows, you should also apply the Cygwin-specific patches:

~$ cat prc-tools-2.0/*.cygwin.diff | patch -p0

If you don't have autoconf installed, you need to fix the datestamp on cstamp-h.in to prevent autoconf from being invoked to regenerate it:

~$ touch gcc-2.95.2/gcc/cstamp-h.in

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-2.0
~/prc-tools-2.0$ ln -s ../binutils-2.9.1 binutils
~/prc-tools-2.0$ ln -s ../gdb-4.18 gdb
~/prc-tools-2.0$ ln -s ../gcc-2.95.2 gcc
~/prc-tools-2.0$ ln -s ../make-3.77 make
~/prc-tools-2.0$ cd ..
(On Windows, if you use any non-Cygwin programs in your build (such as the texi2html perl script), you should use mv instead of ln -s since non-Cygwin programs can't see through Cygwin's symlinks.)

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-2.0/configure --target=m68k-palmos \
         --enable-languages=c,c++ \
	 --with-headers=`pwd`/empty \
	 --sharedstatedir=/usr/local/palmdev
These parameters specify the following:
--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-language=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-build-sdk=2
Select which Palm OS SDK is to be used in building the target run-time support code. Current choices are 1, 2, 3.0, 3.1, 3.5; by default, version 2.0 is used.
--sharedstatedir=/usr/local/palmdev
(There's a bit of a hack here :-)) 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 /usr/local/palmdev on Unix and /PalmDev on Windows.
--prefix=/usr/local
--exec-prefix=prefix
Use these configure parameters to install the package somewhere other than the default /usr/local. On Windows, the prebuilt binary is configured with --prefix=/prc-tools --exec-prefix=/prc-tools/H-i586-cygwin32 and then Cygwin mounts are used to map the files from anywhere. Alternatively, if you want to install these files into the same directories that Cygwin uses, follow Mumit Khan's instructions and use --prefix=/cygnus/cygwin-b20 --exec-prefix=/cygnus/cygwin-b20/H-i586-cygwin32.

Building and installing

If you're using an unprotected file system like Windows, or if you are willing to do all your building as a user who can write to your install directory (i.e., root), you can build and install in one fell swoop:
~/build# make all-install

Otherwise, you'll need to make each of the dependencies of all-install explicitly, since the various builds and installs are interleaved:

~/build$ make all-host
~/build$ su
~/build# make install-host
~/build# ^D
~/build$ make all-gcc
~/build$ su
~/build# make install-gcc
~/build# make install-palmdev
~/build# ^D
~/build$ make all-target
~/build$ su
~/build# make install-target
(This is less ridiculous if you happen to be building only part of the tool chain!)

The multistage process is needed because GCC requires binutils to be installed before it can be built (or we could use the unified binutils/gcc tree trick, but that would cause other problems for us); and in turn prc-tools-2.0/crt needs GCC to be installed before it can be built.

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

Generating and installing the HTML documentation

The HTML documentation is not currently integrated with the rest of the build (since it really wants to be a configure option: --enable-html-docs or some such). If you want to generate these, you need to do it separately:
~/build$ cd doc
~/build/doc$ make html
~/build/doc$ su
~/build/doc# make install-html