PALMDEV-PREP(1)

NAME
palmdev-prep - Prepare PalmDev trees for use with prc-tools

SYNOPSIS
palmdev-prep [ -d sdk | --default sdk ]
             [ -r | --remove ]
             [ -q | --quiet | --silent ] [ -v | --verbose ]
             [ --dump-specs target ]
             [ directory... ]

DESCRIPTION
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".

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.

OPTIONS

"-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. 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.

NOTES
For the curious: "palmdev-prep" creates a GCC specs file that converts "-palmosN" options into the corresponding set of "-isystem" and "-L" options. 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.

SEE ALSO
gcc(1), build-prc(1), and the Info entries for prc-tools et al.