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:

You can download the reference manuals either as a Cygwin package (described below) or as a standalone zip archive (available from the downloads page as prc-tools-htmldocs-version.zip) or not at all (and use the manuals available online);
You can install PilRC as a Cygwin package or you can use the (non-Cygwin-aware) standalone version from the PilRC homepage.

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:

When you are asked which Download Site you want to use, you should choose two: one for the ordinary Cygwin packages and the other for the Palm OS-related ones supplied via these Web pages. For the first, choose any appropriate geographically nearby site. For the second, add this User URL:
http://prc-tools.sourceforge.net/install
(The list of available download sites is a multiple selection list box, so you can <Ctrl>-click to select more than one site. The URL might be displayed in the list in an abbreviated form as just http://prc-tools.sourceforge.net even though the full URL has been accepted.
If you get the error message Unable to get setup.ini from http://prc-tools[...], check the URL you added and add it again if necessary. Most people who have encountered this message have eventually found that it was caused by a mere typo, such as the addition of a trailing space to the URL.)
When you are asked to select the packages you want, note that only the fundamental packages in the Base category and those in the Misc category will be installed by default; of course, you can choose to install many others too, depending on your needs.
In particular, you will want to consider the Palm OS-related packages, which are in the Devel category:
- prc-tools contains all the (m68k) Palm OS compiler tools
- prc-tools-arm, which requires the main prc-tools package to also be installed, contains the additional tools necessary for building ARM programs
- prc-tools-htmldocs provides local copies of the manuals available online; they are installed at Cygwin\usr\doc\prc-tools-version\index.html, where Cygwin is the root directory in which you installed Cygwin and version is the prc-tools-htmldocs version number
- pilrc provides a Cygwin-aware build of the PilRC UI resource compiler
- make, while not really Palm OS-specific, is often used to build Palm OS projects
Of these five packages, only prc-tools itself will be installed by default, so if you need the others you will need to go into the Devel category yourself and select them.

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:

Create C:\PalmDev, or whatever your chosen directory is, if you have not already done so;
Open a shell window from the Cygwin Shell start menu item or the icon installed by the Cygwin installation, and type
mount -tf "C:\PalmDev" /PalmDev
Replace C:\PalmDev by wherever you chose to install SDKs (but keep the quote marks to avoid misinterpretation of any backslashes).

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

C:\PalmDev\sdk-N\include
Header files, arranged in arbitrary directories under include
C:\PalmDev\sdk-N\lib\m68k-palmos-coff
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