.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "PALMDEV-PREP 1"
.TH PALMDEV-PREP 1 "September 2003" "prc-tools 2.3" "User Commands"
.SH "NAME"
palmdev\-prep \- Prepare PalmDev trees for use with prc\-tools
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
palmdev-prep [ \-d \fIsdk\fR | \-\-default \fIsdk\fR ]
             [ \-r | \-\-remove ]
             [ \-q | \-\-quiet | \-\-silent ] [ \-v | \-\-verbose ]
             [ \-\-dump\-specs \fItarget\fR ]
             [ \fIdirectory\fR... ]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Most Palm \s-1OS\s0 programs use functions from the Palm \s-1OS\s0 \s-1API\s0, so need to
\&\f(CW\*(C`#include\*(C'\fR various Palm \s-1OS\s0 header files and perhaps also to link
with static libraries such as Palm \s-1OS\s0 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 \f(CW\*(C`\-I\*(C'\fR,
\&\f(CW\*(C`\-isystem\*(C'\fR, and \f(CW\*(C`\-L\*(C'\fR.
.PP
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 \s-1OS\s0 \s-1SDK\s0 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 \f(CW\*(C`palmdev\-prep\*(C'\fR
to generate a list of directories tailored to the SDKs and other Palm \s-1OS\s0
development material you actually have installed.
.PP
The \f(CW\*(C`palmdev\-prep\*(C'\fR utility scans the standard PalmDev directory and
any extra directories listed on its command line, and generates the options
required to make \s-1GCC\s0 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 \fI/opt/palmdev\fR and on Cygwin it is typically
\&\fI/PalmDev\fR, which typically corresponds to the Windows directory
\&\fIC:\ePalmDev\fR.
.PP
In detail:  first \f(CW\*(C`palmdev\-prep\*(C'\fR looks in each root directory given
for (immediate) subdirectories whose names start with \fIsdk\-\fR, which it
calls ``\s-1SDK\s0 directories''.
.PP
It then examines each \s-1SDK\s0 directory in turn.  If an \s-1SDK\s0 directory contains a
directory named \fIinclude\fR or \fIIncs\fR, \s-1GCC\s0's preprocessor will be
instructed to search for header files within \fIall\fR subdirectories nested
thereunder.
Similarly, if an \s-1SDK\s0 directory contains a directory named \fIlib\fR or
\&\fI\s-1GCC\s0 Libraries\fR, the linker will be instructed to search for libraries in
the directories thereunder corresponding to the particular target architecture
and multilib options in use.
.PP
If an \s-1SDK\s0 directory contains a file named \fIbase\fR, then that file should
contain a single line (e.g. \fBsdk\-3.5\fR or simply \fB4\fR) specifying
another \s-1SDK\s0 upon which this \s-1SDK\s0 is based.  The preprocessor and linker will
then be instructed to search also the directories given by the base \s-1SDK\s0, and
to do so \fIafter\fR searching those from \fIthis\fR \s-1SDK\s0.  This can be used
to have replacement files from an ``\s-1SDK\s0 Update'' override files from the \s-1SDK\s0
that is being updated, while also allowing the use of the pristine original
\&\s-1SDK\s0.
.PP
It also detects \fIinclude\fR, \fIIncs\fR, \fIlib\fR, and
\&\fI\s-1GCC\s0 Libraries\fR directories immediately within each root directory
specified, causing them to be searched \fIafter\fR all those corresponding
to the particular \s-1SDK\s0 in use.
.SH "OPTIONS"
.IX Header "OPTIONS"
.ie n .IP """\-d \f(CIsdk\f(CW""" 4
.el .IP "\f(CW\-d \f(CIsdk\f(CW\fR" 4
.IX Item "-d sdk"
.PD 0
.ie n .IP """\-\-default \f(CIsdk\f(CW""" 4
.el .IP "\f(CW\-\-default \f(CIsdk\f(CW\fR" 4
.IX Item "--default sdk"
.PD
When \s-1GCC\s0 is invoked without any \f(CW\*(C`\-palmos\f(CIN\f(CW\*(C'\fR options, the \s-1SDK\s0 chosen
to be the default \s-1SDK\s0 during the last invocation of palmdev-prep will be used.
This option specifies that \fIsdk\fR should be the default; if you don't
choose a default this way yourself, palmdev-prep will choose the highest \s-1SDK\s0
detected as the default.
.ie n .IP """\-r""" 4
.el .IP "\f(CW\-r\fR" 4
.IX Item "-r"
.PD 0
.ie n .IP """\-\-remove""" 4
.el .IP "\f(CW\-\-remove\fR" 4
.IX Item "--remove"
.PD
Remove all files installed by palmdev\-prep.
.ie n .IP """\-q""" 4
.el .IP "\f(CW\-q\fR" 4
.IX Item "-q"
.PD 0
.ie n .IP """\-\-quiet""" 4
.el .IP "\f(CW\-\-quiet\fR" 4
.IX Item "--quiet"
.ie n .IP """\-\-silent""" 4
.el .IP "\f(CW\-\-silent\fR" 4
.IX Item "--silent"
.PD
Suppress the normal listing showing the SDKs found and their validity.
.ie n .IP """\-v""" 4
.el .IP "\f(CW\-v\fR" 4
.IX Item "-v"
.PD 0
.ie n .IP """\-\-verbose""" 4
.el .IP "\f(CW\-\-verbose\fR" 4
.IX Item "--verbose"
.PD
Display details of files modified and actions taken by palmdev\-prep.
.ie n .IP """\-\-dump\-specs \f(CItarget\f(CW""" 4
.el .IP "\f(CW\-\-dump\-specs \f(CItarget\f(CW\fR" 4
.IX Item "--dump-specs target"
Write a specs file describing the PalmDev headers and libraries for
\&\fItarget\fR to standard output, instead performing of the normal installation
actions.  This is for use while prc-tools itself is being built.
.PP
The directory structure and default \s-1SDK\s0 captured by palmdev-prep will be
used by \s-1GCC\s0 until the next invocation of palmdev\-prep.  You should rerun
\&\f(CW\*(C`palmdev\-prep\*(C'\fR whenever you
.IP "\(bu" 4
upgrade prc\-tools;
.IP "\(bu" 4
install or remove a Palm \s-1OS\s0 \s-1SDK\s0 or other development material
(specifically, when the collection of subdirectories changes);
.IP "\(bu" 4
want to change which \s-1SDK\s0 is to be used by default.
.SH "NOTES"
.IX Header "NOTES"
For the curious: \f(CW\*(C`palmdev\-prep\*(C'\fR creates a \s-1GCC\s0 specs file that converts
\&\f(CW\*(C`\-palmos\f(CIN\f(CW\*(C'\fR options into the corresponding set of \f(CW\*(C`\-isystem\*(C'\fR
and \f(CW\*(C`\-L\*(C'\fR options.  This is how
it is able to affect later unrelated invocations of \s-1GCC\s0.  This file is
inside one of \s-1GCC\s0's internal directories, so on a typical Unix installation
you need to be a privileged user to write to it.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIgcc\fR\|(1), \fIbuild\-prc\fR\|(1), and the Info entries for \fIprc-tools\fR et al.