4. Definition files

A project may optionally contain a definition file, which is read by build-prc and also by several other utilities. This file is used to specify various miscellaneous properties of the project, such as database header flags, names of multiple sections, and exported library functions.

4.1 General syntax

A definition file should have the extension `.def', and is a freely formatted file consisting of numbers, strings, comments, keywords, and various punctuation.

• Numbers may be in decimal (`37'), octal (`045'), or hexadecimal (`0x25').

• Strings are enclosed in either single (`'Hello'') or double (`"world"') quotes, and may contain the usual C escape sequences (`\t', `\n', `\'', `\"', `\\', `\177', `\x7F', ...). If a string contains only alphanumeric characters and does not conflict with a keyword, the quotes may be omitted.

• Both C style (`/* comment */') and C++ style (`// until end of line') comments may appear anywhere white space could occur, and are ignored.

A definition file consists of several clauses, which generally have syntax like the following:

clause-kind { specific-data... }

For example, here is a complete definition file for a (hypothetical) fairly large non-beamable application:

application { "Dr McCoy" DAFp copy-prevention } /* This app has three code resources: code #1 with all unannotated functions, #2 with functions placed in the "editfns" section, and #3 with "viewfns" functions. */ multiple code { editfns viewfns }

4.2 Specifying the kind of project

You can specify the database header attributes which appeared in an old-style build-prc command line along with the kind of project being built in this clause:

project-kind [ type ] { dbname crid miscellaneous... }

This clause must appear exactly once, and must be first in the file, before any other clauses. dbname, crid, and type specify the database's name, creator id, and type. Except when project-kind is database, type can be omitted and a type suitable for the project kind will be used. project-kind controls the processing of the bfd executable, and should be one of the following:

app

application

Build a Palm OS application, with a default type of appl. Code and data sections in the bfd executable are converted into Palm OS code, data, and rloc resources, and code #0 and pref #0 resources are synthesised.

glib

Build a GLib shared library, with a default type of GLib. Code and data sections in the bfd executable are converted into GLib code, data, and rloc resources.

syslib

Build a system shared library, with a default type of libr. Code sections in the bfd executable are converted into libr code resources. Since system libraries typically don't have their own global data, data sections in the bfd executable will produce a warning rather than being converted, unless you also use the data miscellaneous flag.

hack

Build a HackMaster hack, with a default type of HACK. All bfd executables given should be marked as stand-alone code sections, and any data sections or extra code sections present will elicit warnings from build-prc (see section 3.4 Stand-alone code resources).

database

This implies no special handling of the bfd executable, and so builds a generic database. In this case, type must not be omitted.

The database name and creator id must come first within the braces, and may be followed by any number of the following, in any order:

read-only

appinfo-dirty

backup

ok-to-install-newer

reset-after-install

copy-prevention

stream

hidden

launchable-data

recyclable

bundle

Set the corresponding database header attribute, adding to any attributes specified as options to build-prc. These may also be spelt with the hyphens replaced by underscores or omitted altogether (`readonly', `appinfo_dirty', etc).

modification=num

modnum=num

modno=num

Set the modification number in the database header to num.

version=num

Set the database header version number to num.

stack=size

For an application, make the pref #0 resource request size bytes of stack space. By default, 4K is requested.

data

For a system shared library, convert any data sections in input bfd executables into Palm OS data resources. Without this flag, when build-prc is building a system shared library, any data sections will cause warnings instead of being converted.

4.3 Declaring multiple code sections

Each section name that you use in a function section attribute in your project needs to be listed in your definition file in a multiple code clause:

multiple code { sectionname... }

This is used by multigen to produce an assembly language list of the section names which needs to be linked into your executable, and also by build-prc to map named code sections to numbered code resources in the .prc file.

Build-prc will emit warnings if there are sections in your executable which are omitted from this clause, or vice versa.

4.4 Listing exported library entry point functions

Both system shared libraries and GLibs require a dispatch table and a small amount of other assembler support code. You can write this by hand, or you can use stubgen to generate the needed code from an export clause:

export { function-name... }

Dispatch table entries are generated in the order in which function names are listed in the export clause. Thus, for the sake of binary compatibility between releases of your library, it is important to avoid changing the ordinal positions of function names. For example, new functions being added to an existing library should be added at the end of the export clause, after the existing functions names.