| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
On most platforms, you compile and link your programs, and the resulting executable is the program you run. (The GNU linker produces an executable using a library named "bfd"---hence the term "bfd executable"). On Palm OS, however, this bfd executable is not, in fact, executable: its format must be changed from bfd COFF to a .prc database file, and, for all but the most trivial programs, UI resources must be bound in.
The post-linker tools are build-prc, which reads a definition
file and various resource sources to generate a Palm OS .prc file,
and obj-res, which converts a bfd executable into resources.
(Build-prc can now read bfd executables directly, so there is no
need to use obj-res anymore, but it is still supported for backwards
compatibility.) There are also multigen and stubgen,
which generate various support files;
and trapfilt, which decodes Palm OS trap vectors.
Other miscellaneous tools include palmdev-prep, which informs GCC of
the locations of Palm OS SDKs and the like. You should run it whenever you
upgrade prc-tools or install new SDKs or modify existing ones.
6.1 build-prc 6.2 multigen 6.3 stubgen 6.4 obj-res 6.5 palmdev-prep 6.6 trapfilt
build-prc [ -l ] [ -L ] [ -t type ] prcfile app-name crid file...
build-prc [ -o file | --output file ]
[ -a file | --appinfo file ]
[ -s file | --sortinfo file ]
[ -l ] [ -L ] [ -H | --hack ]
[ -t type | --type type ]
[ -c crid | --creator crid ]
[ -n name | --name name ]
[ -m num | --modification-number num ]
[ -v num | --version-number num ]
[ --read-only ] [ --appinfo-dirty ] [ --backup ]
[ --ok-to-install-newer ] [ --reset-after-install ]
[ --copy-prevention ] [ --stream ] [ --hidden ]
[ --launchable-data ] [ --recyclable ] [ --bundle ]
[ -z n | --compress-data n ]
[ --no-check-header ] [ --no-check-resources ]
[ --no-check ]
file...
|
build-prc reads resources from the input files given and
combines them into one output Palm OS .prc resource data file. There are
two styles of build-prc command line: in the old style, the first three
non-option arguments describe the output file, and input files don't start
until the fourth argument. In the new style, all non-option arguments
are input files. An invocation is new-style if the first file argument
does not have a .prc extension or if the -o option is used.
Input files are identified by their extension:
fname.def
typennnn.bin
typennnn.progname.grc
type #nnnn resource, where nnnn is in hexadecimal.
fname.prc
fname.ro
.prc format. The contents of all the
resources in a resource database are copied to the output database.
(The information in the input database's header--name, creator, flags,
etc--is entirely ignored.)
progname
.disposn or a .trap section,
its .text section is converted to a stand-alone code resource
accordingly (see section 3.4 Stand-alone code resources). Otherwise, its code and data
sections are converted to resources according to a definition
file, or, if there is no definition file, as if the application
project kind was specified.
By default, build-prc uses its first non-option argument as
the filename for its output .prc file. In an old-style command line,
prcfile is used as is. In a new-style command line, the output
filename is formed by removing the extension, if any, from the first
file argument and appending `.prc'.
-o file
--output file
-a file
--appinfo file
-s file
--sortinfo file
-l
-L
-H
--hack
-t type
--type type
Note that this affects only the type recorded in the database header; in particular, it does not change build-prc's notion of the kind of project being generated (see section project kinds), nor does it influence resource checking. If you do not want the database to be checked as if it is an application, you must either tell build-prc what it really is, by using a definition file or one of the options listed above, or, as a last resort, suppress resource checking entirely.
-c crid
--creator crid
-n name
--name name
-m num
--modification-number num
-v num
--version-number num
--read-only
--appinfo-dirty
--backup
--ok-to-install-newer
--reset-after-install
--copy-prevention
--stream
--hidden
--launchable-data
--recyclable
--bundle
--readonly, etc).
-z N
--compress-data N
--no-check-header
--no-check-resources
By default, build-prc will check for these resources and emit diagnostics accordingly, which helps you detect mistakes such as the omission of a bfd executable from the build-prc invocation.
--no-check
--no-check-foo options listed above.
multigen [ -b base | --base base ] deffile.def |
The multigen utility generates an assembly language source file
and a linker script for use in projects with multiple code resources
(see section 3.2 Multiple code resources). The assembly stub file must be
compiled in with your application, and the linker script should be
added to your link command.
You can write the required assembly language definitions and linker
script yourself if you wish, but it is easier to have multigen
generate them for you from the relevant clause in your project's definition
file (see section 4. Definition files).
multigen reads from `deffile.def' and by
default writes the assembler stub file to `deffile-sections.s' and
the linker script to `deffile-sections.ld'.
-b base
--base base
stubgen [ -b base | --base base ] deffile.def |
The stubgen utility generates assembly language stub files for a
GLib or an assembly language dispatch table for a SysLib (see section 3.3 Shared libraries). You can write these stub files yourself, but, particularly
for a GLib, it is easier to have stubgen generate them for you from the
relevant clause in your library's definition file (see section 4. Definition files).
stubgen reads from deffile and by default writes its output to
`deffile-stubs.c' and `deffile-jumps.s', or to
`deffile-dispatch.s', depending on the project-kind
specified in deffile.
-b base
--base base
(This is inconsistent with the way multigen handles the `-b'
option. One or the other is likely to change.)
obj-res [ -l ] [ -L exportfile ] [ -z n ] bfdfile |
The obj-res utility reads a file in a BFD supported object file format
(most usually COFF) and generates the raw binary resource files necessary to
make up a Palm OS executable in the current directory. These files can be
bound together into a Palm OS resource data file using build-prc.
This utility is deprecated. It is provided only for use in existing
legacy build scripts and makefiles. In new projects it is more convenient to
present the same object file directly to build-prc, thus enabling
better error checking, avoiding a separate obj-res step, and avoiding
the clutter of separate `.grc' files.
In particular, if you are using multiple code resources or the stand-alone
code facilities then you must not use obj-res. Such projects
require information that is thrown away by obj-res, and your build
will fail or, worse, silently produce invalid results.
But if you nonetheless choose to use it: obj-res reads from
bfdfile and writes to a number of files with names of the form
`typennnn.bfdfile.grc'. By default it generates
resources for a Palm OS application.
-l
-L exportfile
Unlike previous versions of obj-res, this version cannot generate an
offset table in exportfile. You should use build-prc
directly with a definition file instead.
-z n
build-prc option.
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 section `Options for Directory Search' in 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
-palmosN options, the SDK chosen
to be the default SDK during the last invocation of palmdev-prep will be used
(see section 1.1 Palm OS-specific GCC 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
-q
--quiet
--silent
-v
--verbose
--dump-specs target
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
For the curious: palmdev-prep creates a GCC specs file that converts
-palmosN options into the corresponding set of -isystem
and -L options (see section `Specifying subprocesses and the switches to pass to them' in 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.
trapfilt [ -q | --quiet | --silent ] [ vector... ] |
On the 68000, calls to Palm OS system API functions are compiled into a
trap instruction followed by a trap vector, which is a 16-bit
number in a range starting at 0xA000. The mapping between particular system
functions and numeric trap vectors is given in the `CoreTraps.h' header
in a Palm OS SDK (or `SysTraps.h' in older SDKs).
A disassembly listing of a Palm OS program displays only the trap
instructions and the raw trap vectors. The trapfilt utility decodes
trap vectors using the mapping given by the header from the default SDK
selected with palmdev-prep. Typically you use it in conjunction
with a disassembly listing from objdump:
m68k-palmos-objdump -d myapp | m68k-palmos-trapfilt |
If any vector arguments are given, trapfilt decodes them and
outputs the results on standard output. Otherwise, when no such arguments
are given, it acts as a filter: copying from standard input to standard
output, annotating each line that matches the syntax of a trap vector
(i.e., the syntax as printed by objdump) with the name of the
corresponding system function, if any.
-q
--quiet
--silent
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |