     palmdev-prep [ -d SDK | --default SDK ]
                  [ -r | --remove ]
                  [ -q | --quiet | --silent ] [ -v | --verbose ]
                  [ --dump-specs TARGET ]
                  [ DIRECTORY... ]

Most Palm OS programs use functions from the Palm OS API, so need to #include various Palm OS header files and perhaps also to link with static libraries such as Palm OS Glue. The preprocessor and the linker need to be told, one directory at a time, where to search for these files, via options such as -I, -isystem, and -L (see Options for Directory Search (Using and Porting GCC)).

Early versions of prc-tools contained a hard-coded list of directories to be searched.  Unfortunately, more recently there has been a tendency for each new Palm OS SDK to introduce new directories unpredictably and sometimes even to rearrange the old ones.  Hence the hard-coded list approach is no longer practical; instead, you can use palmdev-prep to generate a list of directories tailored to the SDKs and other Palm OS development material you actually have installed.

The palmdev-prep utility scans the standard PalmDev directory and any extra directories listed on its command line, and generates the options required to make GCC search as appropriate each of the subdirectories found under each of the root directories given. The ``standard PalmDev location'' is determined when prc-tools is configured; typically on Unix it is /opt/palmdev and on Cygwin it is typically /PalmDev, which typically corresponds to the Windows directory C:\PalmDev.

In detail:  first palmdev-prep looks in each root directory given for (immediate) subdirectories whose names start with sdk-, which it calls ``SDK directories''.

It then examines each SDK directory in turn.  If an SDK directory contains a directory named include or Incs, GCC's preprocessor will be instructed to search for header files within all subdirectories nested thereunder. Similarly, if an SDK directory contains a directory named lib or GCC Libraries, the linker will be instructed to search for libraries in the directories thereunder corresponding to the particular target architecture and multilib options in use.

If an SDK directory contains a file named base, then that file should contain a single line (e.g. sdk-3.5 or simply 4) specifying another SDK upon which this SDK is based.  The preprocessor and linker will then be instructed to search also the directories given by the base SDK, and to do so after searching those from this SDK.  This can be used to have replacement files from an ``SDK Update'' override files from the SDK that is being updated, while also allowing the use of the pristine original SDK.

It also detects include, Incs, lib, and GCC Libraries directories immediately within each root directory specified, causing them to be searched after all those corresponding to the particular SDK in use.

-d SDK
--default SDK
     When GCC is invoked without any -palmosN options, the SDK chosen to be the default SDK during the last invocation of palmdev-prep will be used (see New options). This option specifies that SDK should be the default; if you don't choose a default this way yourself, palmdev-prep will choose the highest SDK detected as the default.

-r
--remove
     Remove all files installed by palmdev-prep.

-q
--quiet
--silent
     Suppress the normal listing showing the SDKs found and their validity.

-v
--verbose
     Display details of files modified and actions taken by palmdev-prep.

--dump-specs TARGET
     Write a specs file describing the PalmDev headers and libraries for TARGET to standard output, instead performing of the normal installation actions.  This is for use while prc-tools itself is being built.

The directory structure and default SDK captured by palmdev-prep will be used by GCC until the next invocation of palmdev-prep.  You should rerun palmdev-prep whenever you

  * upgrade prc-tools;

  * install or remove a Palm OS SDK or other development material (specifically, when the collection of subdirectories changes);

  * want to change which SDK is to be used by default.

For the curious: palmdev-prep creates a GCC specs file that converts -palmosN options into the corresponding set of -isystem and -L options (see Specifying subprocesses and the switches to pass to them (Using and Porting GCC)).  This is how it is able to affect later unrelated invocations of GCC.  This file is inside one of GCC's internal directories, so on a typical Unix installation you need to be a privileged user to write to it.