Quartus Forth Manual

Table of Contents - Quartus Forth Home Page - How to Register

Creating Stand-Alone Executables

This section of the manual applies to the registered version of Quartus Forth only.

MakePRC: Stand-alone Executable Creation

Quartus Forth provides facilities for turning your applications into stand-alone executables that can be downloaded and distributed royalty-free. As it builds an executable, it includes only those parts of the kernel that are required for your application.

Executables generated by Quartus Forth can be HotSync'd into your Palm device and started from the application launcher, just as with any other Palm executable. No run-time module is required!

The basic command for creating a stand-alone executable (PRC) is MakePRC.

MakePRC ( xt creatorID. <name> -- )

MakePRC reads code from the specified xt, and recursively extracts all required supporting code into a new PRC with the name provided. Each PRC that is destined for release to the general public must have a unique creator ID, allocated from the Creator ID database that 3Com maintains for all developers.

Use the library file ids to make the use of creator IDs in Quartus Forth simple.

There's a simple usage example in the Quick Start --

' go 12345. MakePRC Hello

In this example, go is the top-level word, 12345. is the creator ID, and the resulting PRC name is Hello.

A more typical example comes from the sample application year:

needs resources
needs ids
...
(ID) p4ap (ID) Year use-resources
...
' go (ID) Year MakePRC Year
\ Note that Year is a creator-ID
\ registered with
\ http://palm.3com.com/devzone
\ Each released app must have a
\ unique, registered creator ID.

When you next HotSync your PalmPilot, the generated PRC is automatically downloaded to your PC or Mac, and can be distributed and uploaded to any Palm device. It's completely stand-alone, and requires no run-time module.

Using External Resources

CopyRsrc ( resource# resourceID. -- )
DelRsrc ( resource# resourceID. -- success )

You can create external PalmOS GUI resources using standard tools such as PilRC, or the on-board resource compiler, RsrcEdit. These resources can be used by your Quartus Forth applications, and compiled directly into stand-alone executables you create.

After MakePRC, you can use CopyRsrc and DelRsrc to copy resources into or delete resources from the generated target PRC file.

CopyRsrc will search for a specified resource by number and ID, and create a copy of that resource in the target PRC.

From the sample application Year:

3000 constant AboutBox
3001 constant HelpString
...
1001 constant YearForm
...
\ Add required resources:
2000 (ID) MBAR CopyRsrc \ menu
YearForm (ID) tFRM CopyRsrc
AboutBox (ID) Talt CopyRsrc
HelpString (ID) tSTR CopyRsrc

\ Copy icons:
1000 (ID) tAIB CopyRsrc \ normal
1001 (ID) tAIB CopyRsrc \ small

DelRsrc will delete a specified resource from the target PRC.

From Year:

\ Delete unneeded forms:
MainFormID (ID) tFRM DelRsrc drop
TitledFormID (ID) tFRM DelRsrc drop

See the Sample Applications for more details and examples of the use of these words.

Caveats for Stand-Alone Applications

Bear in mind that generated stand-alone executables contain only the code required by your application. In a generated executable, there is no dictionary; dictionary headers on words are removed, and the interpreter is not present.

Also, take care not to rely on the value returned by ' (tick) in a stand-alone executable. An xt returned by ' during compilation will not match the xt of a word in a generated executable. Should you need to initialize a vector with an xt, use ['] from within a word to do so; xt's returned by ['] are position-independent.

For example:

This technique would not produce working code in a stand-alone executable:

: myword ." Hello" cr ;

variable vector
' myword vector !

: go vector @ execute ;

This is the correct method:

: myword ." Hello" cr ;

variable vector

: go
['] myword vector !
vector @ execute ;


Table of Contents - Quartus Forth Home Page
© 1998, 1999 Neal Bridges. All rights reserved.