[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

6. Post-linker and other tools

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  

6.1 build-prc

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 ]

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:

A project definition file, which controls the post-linking process. If your project uses a definition file, there can be only one and it must be first in the list of input files. (Hence definition files can only be used in a new-style invocation.)

A raw binary resource file (the .grc style filename is produced by obj-res). The contents of a raw file are added to the output as a type #nnnn resource, where nnnn is in hexadecimal.

A resource database in .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.)

Files with no extensions are treated as bfd executables. If a bfd executable contains either a .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
Write the .prc output to file. It is an error to use this option in an old-style command line, as it conflicts with the mandatory prcfile argument.

-a file
--appinfo file
Add an AppInfo block with the contents of file to the database.

-s file
--sortinfo file
Add a SortInfo block with the contents of file to the database.

Build a GLib shared library; this is equivalent to specifying a project kind of "glib" in a definition file. In particular, it changes the default database type and the disposition of code and data sections in the bfd executable, and influences resource checking.

Build a system shared library; this is equivalent to specifying a project kind of "syslib" in a definition file. In particular, it changes the default database type and the disposition of code (and data) sections in the bfd executable, and influences resource checking.

Build a HackMaster hack; this is equivalent to specifying a project kind of "hack" in a definition file. In particular, it changes the default database type, requires all bfd executables to be marked as stand-alone, and influences resource checking.

-t type
--type type
Set the database's type to type, overriding any type it may get from a definition file or elsewhere.

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
Set the database's creator ID to crid, overriding any ID it may get from a definition file. It is an error to use this option in an old-style command line, as it conflicts with the mandatory crid argument.

-n name
--name name
Set the database's name to name, overriding any name it may get from a definition file. It is an error to use this option in an old-style command line, as it conflicts with the mandatory app-name argument.

-m num
--modification-number num
Set the modification number in the database header to num.

-v num
--version-number num
Set the database header version number to num.

Set the corresponding database header attribute, adding to any attributes set in a definition file. These options may also be spelt without the internal hyphens (--readonly, etc).

-z N
--compress-data N
Compress the data resource, `data #0'. Compression ranges from 0, no compression, to 7, full (and somewhat experimental!) compression.

Suppress warnings related to invalid database header fields, such as a blank database name or creator ID. If the database being generated is only for use as a temporary file, for example, these warnings may not be of interest.

Suppress checking for the presence of vital resources. Databases corresponding to particular kinds of project are malformed if they do not contain certain resources: for example, an application without a `code #1' resource cannot be launched correctly, and a Hack requires `TRAP' resources to be numbered consecutively and to have corresponding `code' 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.

Suppress all checking of the generated database; this is equivalent to using all of the --no-check-foo options listed above.

6.2 multigen

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
Write the assembly language output to `base.s' and the linker script to `base.ld'.

6.3 stubgen

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
Write the GLib output to `base-stubs.c' and `base-jumps.s', or the SysLib output to `base-dispatch.s'.

(This is inconsistent with the way multigen handles the `-b' option. One or the other is likely to change.)

6.4 obj-res

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.

Generate resources for a GLib shared library.

-L exportfile
Generate resources for a Palm OS version 2 system shared library.

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
Compress the data resource, `data0000.bfdfile.grc', similarly to the corresponding build-prc option.

6.5 palmdev-prep

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

Remove all files installed by palmdev-prep.

Suppress the normal listing showing the SDKs found and their validity.

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

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.

6.6 trapfilt

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.

In non-filter mode, output only the system function name for each vector given. The default output format in non-filter mode is similar to that used in filter mode.

[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]