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

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.

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.


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