Installing prc-tools on MS Windows with Cygwin

On Microsoft Windows, prc-tools is built using the Cygwin Unix emulation layer. If you are already a Cygwin user, much of the following will be familiar.

The installation procedure is actually rather shorter and simpler than this Web page! Its length is because we've tried to explain the background behind the parts that may be unfamiliar.

Before you begin

You need to decide where to put your PalmDev tree, i.e., where you will install Palm OS SDKs and other Palm OS-related header files and libraries (collectively, development material). Palm OS programmers tend to spend more time than most studying system header files, so we suggest somewhere easily accessible such as C:\PalmDev. (Create this directory if it doesn't already exist.)

You also have some choices to make with respect to some of the components:

The advantage of a Cygwin package is that it is package-managed and you can update it easily and automatically at the same time as you update the other packages; the advantage of a standalone zip archive is that you can unpack it wherever you wish, but this is only really of interest for the manuals, not PilRC.

Installing Cygwin and prc-tools

(You may be tempted to use an ordinary Windows archive utility, such as WinZip, to install individual Cygwin packages such as prc-tools. This does not work: non-Cygwin utilities can handle neither mount points, potentially installing files in the wrong places, nor symbolic links, replacing them with spurious zero-length files. There is only one supported way to install prc-tools; namely, by using Cygwin's setup.exe. The easiest way to use it is described here.)

Run Cygwin's setup utility, setup.exe, which you can obtain by selecting one of the Install Cygwin now icons on the Cygwin homepage.

Note: If you are using setup.exe version 2.573.2.3 (released in August 2008) or later it will not let you download prc-tools by default because our setup.ini package information file is not signed. Make a shortcut where you specify the command to run as "setup.exe -X". The -X option will force setup to skip the verification of the cryptograhic signature of our setup.ini file.

The various options in setup.exe are mostly self-evident and depend solely on your personal preferences. The ones that do matter are:

You can always add new packages later or update the existing ones: just run setup.exe again. If you have any problems installing or using Cygwin, your first step should be to check the Cygwin documentation and FAQ.

Mounting your PalmDev tree

Prc-tools needs the PalmDev tree to be available at the POSIX path /PalmDev. The best way to arrange this is to create a mount point pointing to the location you have chosen: You only need to do this once, after you install Cygwin.

Installing SDKs

Some of the Palm OS SDKs are available as Windows installers, while others are zip archives that you'll have to unpack yourself. Usually the installer will guess where it should install itself correctly, but you should check that it has detected your choice of PalmDev tree location correctly. When you're unpacking an SDK manually, you should follow the instructions in its ReadMe file and aim for a directory structure as shown in the next section.

Post-installation setup

Neither prc-tools nor GCC has any built-in knowledge of what Palm OS SDKs and other development material you happen to have installed. You can use palmdev-prep to provide such knowledge: after running it, m68k-palmos-gcc will be able to find Palm OS-related headers and libraries automatically, i.e., without needing any extra -I and -L options, and will have a new -palmosN option for selecting which SDK to use.

You should rerun palmdev-prep whenever you upgrade prc-tools or install or remove a Palm OS SDK or other development material. You should also rerun it using its -d SDK option when you want to change which SDK is to be used by default, i.e., in the absence of any -palmosN options.

(For simplicity of presentation, in the remainder of this section we'll use C:\PalmDev as an abbreviation for the directory which you have chosen to contain your PalmDev tree, typically C:\PalmDev. If you've chosen a different location, you should make the appropriate substitution in what follows.)

Palmdev-prep will search C:\PalmDev for SDKs and other development material and report on what it finds. This report reflects the SDKs that will be accessible via a -palmosN option to GCC, so if it fails to list some SDK that you think you have installed, you'll have to figure out why prc-tools has not been able to detect it. In general, prc-tools prefers and expects the directory structure of a Palm OS SDK to look like

Header files, arranged in arbitrary directories under include
Static (link-time) libraries for m68k-palmos
For compatibility with some of the ways in which SDKs have been packaged, palmdev-prep will also correctly detect an SDK when header files are under Incs instead of include and/or libraries are under GCC Libraries instead of lib.

Using prc-tools from a Windows Command Prompt

The prc-tools user commands and various Cygwin DLLs are in the C:\cygwin\bin directory, which needs to be in your PATH. The appropriate directory is already in the Cygwin shell's path by default, so you don't need to do anything special to use prc-tools and the rest of Cygwin from the Cygwin shell.

To work from an ordinary Windows Command Prompt (DOS window), you need to add C:\cygwin\bin to your PATH environment variable there. (Replace C:\cygwin by wherever you chose to place Cygwin's root directory, of course.)

Depending on your version of Microsoft Windows, you do this in the System control panel (the Environment Variables section of the Advanced tab) or in C:\AUTOEXEC.BAT. You only need to do this once.

Part of the installation guide of the prc-tools web pages