PgmPP bundle v5
===============

  Version 5 - May 11, 2004

  PgmPP bundle is a set of 12 sample freeware programs for the
  on board Palm OS Pascal compiler

  PgmPP bundle also provides 5 general purpose units

  Made in 2002-2004 by Laurent Duveau (with a huge help from
  Philippe Guillot, the author of the Palm OS Pascal Compiler)
      Web Site = http://www.aldweb.com
      e-Mail   = info@aldweb.com




Palm OS Pascal compiler (PP)
----------------------------

The PgmPP sample programs were compiled with the great on board 
Palm OS Pascal compiler for Palm OS handheld devices
      Web Site = http://ppcompiler.free.fr
      e-Mail   = ph.guillot@wanadoo.fr

The Source code of the PgmPP programs are available in the PP 
distribution and can also be downloaded from my Web Site.

The PgmPP programs are either brand new programs made for PP or
a port of the sample freeware programs that I originally made
for HSPascal. As a matter of fact, porting these programs from 
HSPascal to PP was a very easy job to do.

Philippe Guillot is doing a tremendous job with the PP compiler
and he really deserves respect and consideration. Thanks Philippe
for providing us with the PP compiler for free! 




Sample programs
---------------

    v1 : not changed since v1 of PgmPP
    v2 : changed since v1 of PgmPP or new in v2
    v3 : changed since v2 or v1 of PgmPP or new in v3
    v4 : changed since v3, v2 or v1 of PgmPP or new in v4
    ... and so on...


ascii v4

  ascii is just a useful characters ASCII codes chart.

  Characteristics:
  - Console based program


Bench1 v4

  Michael Winikoff's simple benchmark routine in PP. 
  http://goanna.cs.rmit.edu.au/~winikoff/palm/dev.html#bench
  You will see that PP is one of the compilers available 
  on the Palm OS environment that generates the fastest 
  applications.

  Characteristics:
  - Console based program


Bench1GUI v4

  Bench1GUI is the same program as Bench1 but written to be
  a Palm graphical UI application. Comparing these two 
  programs' source codes is a good way for understanding the
  differences beween a console based program and a GUI one.

  Characteristics:
  - "Basic" Palm graphical UI application (no resource file)


Bench1ARM v4

  Bench1ARM is the same program as Bench1GUI but written to 
  run the Bench1 benchmark routine in ARMlet mode for Palm 
  OS 5.x devices. Comparing these two programs' source codes 
  is a good way for understanding the differences beween a 
  standard Palm OS 68k DragonBall (up to version 4.x of Palm
  OS) program and an ARMlet one (for Palm OS version 5.x).
  You will be amazed by the tremendous gain of speed (17
  times faster on my Palm Tungsten C!).

  Characteristics:
  - "Basic" Palm graphical UI application
  - one resource file being the ARMlet 
  - only runs on Palm OS 5 devices


Bench2 v4

  My own benchmark routine in PP which is highly documented
  here: http://www.aldweb.com/articles.php?lng=en&pg=24
  My benchmark analysis of development tools confirms that PP
  is one of the  Palm OS compilers which generate the fastest
  running software.

  Characteristics:
  - Console based program


Bench2GUI v4

  Bench2GUI is the same program as Bench2 but written to be
  a Palm graphical UI application. Comparing these two 
  programs' source codes is a good way for understanding the
  differences beween a console based program and a GUI one.

  Characteristics:
  - "Basic" Palm graphical UI application (no resource file)


Bench2ARM v4

  Bench2ARM is the same program as Bench2GUI but written to 
  run the Bench2 benchmark routine in ARMlet mode for Palm 
  OS 5.x devices. Comparing these two programs' source codes 
  is a good way for understanding the differences beween a 
  standard Palm OS 68k DragonBall (up to version 4.x of Palm
  OS) program and an ARMlet one (for Palm OS version 5.x).
  You will be amazed by the tremendous gain of speed (10
  times faster on my Palm Tungsten C!).

  Characteristics:
  - "Basic" Palm graphical UI application
  - one resource file being the ARMlet 
  - only runs on Palm OS 5 devices


CellsPP v5

  CellsPP is a port of the popular "Game of Life" invented 
  in 1970 by John Conway. In an automata universe, cells 
  follow very basic rules to survive, be born or die in 
  a turn based simulation.

  Characteristics:
  - Standard Palm graphical UI application
  - Minimum Palm OS requirement is version 2.0
  - Port of the Cells v1.6 source code for HSPascal
  - ARMlet switch if device runs with Palm OS 5.x (self 
    detection) for faster display of cells generations

  WARNING: for the ARMlet compilation, PP v2.08j or later is 
           required 


MatchesPP1 v4

  MatchesPP1 is a silly little game in which each of the two 
  players (computer and you) removes one after the other 
  from one to three matches. The player who remains with
  the last match looses the game.

  Characteristics:
  - Console based program. MatchesPP1 was developped to allow
    comparizon of its source code with the one of MatchesPP2
    which is a standard Palm graphical UI application.
  - Minimum Palm OS requirement is version 2.0
  - Adaptation of the Matches v2.0 source code for HSPascal


MatchesPP2 v4

  MatchesPP2 is the same game as MatchesPP1 but written to 
  be a Palm graphical UI application. Comparing these two 
  programs' source codes is a good way for understanding the
  differences beween a console based program and a GUI one.

  Characteristics:
  - Standard Palm graphical UI application
  - Minimum Palm OS requirement is version 2.0
  - Port of the Matches v2.0 source code for HSPascal


NekoPP v4

  Who is NekoPP you may ask? NekoCat is a little cat that
  sits on your Palm and chases the food (bird, mouse or 
  fish) that you tick on the screen until he catches it.
  This so cute little cat then goes through a series of 
  absolutely adorable activities, such as cleaning himself
  and taking a nap.

  Characteristics:
  - Standard Palm graphical UI application
  - Minimum Palm OS requirement is version 2.0
  - Port of the NekoCat v2.3 source code for HSPascal


NumerusPP v4

  NumerusPP is a basic standard 4 function calculator... 
  that operates in Roman numerals.
  NumerusPP accepts numbers in the range {0..99999}.

  Characteristics:
  - Standard Palm graphical UI application
  - Minimum Palm OS requirement is version 3.0
  - Port of the Numerus v1.7 source code for HSPascal




Units
-----

PPlib v4

  PPlib.pas is a set of common functions that can be used both in
  console based applications and graphical UI applications.


TPTypes v4

  TPTypes.pas may be included in your PP programs for HSPascal and
  Turbo Pascal integer types compatibility. It can be used both in
  console based applications and graphical UI applications.


PalmAPI v5

  PalmAPI.pas is a set of common Palm OS API calls and types 
  definitions for PP. In other words, it is a PP port of a subset
  of the Palm SDK. It is to be used for graphical UI applications.


PalmARM v5

  PalmARM.pas is a set of common Palm OS API calls and functions
  for PP to be used with with ARMlets.


PalmMS v5

  PalmMS.pas is a set of common Palm OS API calls and functions
  for PP to be used with with multi code segments.




How to install the PgmPP programs executables?
----------------------------------------------

All these sample programs are Palm OS v5 ready (tested with Palm 
Simulator version 5.1b and in my Palm Tungsten C).

The graphical UI applications are PRC file that are installed like
any other Palm OS file using HotSync. So, extract ProgramName.PRC from
the PgmPP.ZIP archive file. Double-click on it and the Palm install
tool will popup. ProgramName.PRC will be transferred to your Palm
device next time you synchronize your device with your PC with HotSync.

Both black & white and color versions of the graphical UI
applications are available. Whether your device is color enabled or
not, they will automatically detect it and adapt to display all
items in black & white or in color.

The console based applications need PP or vfsDOS to run. Please refer
to the PP official documentation for proceeding instructions.




How to install the PgmPP programs source code?
----------------------------------------------

You will find in the PgmPP.ZIP archive file some ProgramName.pas.pdb
and ProgramName.rsrc.prc files. You need to upload these files to your
Palm device, together with some or all of the Units files 
(PPlib.pas.pdb, PalmAPI.pas.pdb, TPTypes.pas.pdb, PalmARM.pas.pdb and
PalmMS.pdb) that are to be found in the Units folder inside the 
PgmPP.ZIP file.

All FileName.pas.pdb file can be read and modified with Piaf (the PP 
dedicated source code IED), QED or any other DOC reader. The 
ProgramName.rsrc.prc file can read and modified with the RsrcEdit 
program.

PP v2.02 or later is required for compiling these programs. Some of
them might work with v1.04C or later versions but I do not guarantee 
backward compatibility. 
Please note that CellsPP requires PP v2.08j or later.

To compile the program by yourself, you just have to go in PPShell or
Piaf and select the ProgramName.pas.pdb. Then click on the Compile or
Build button and that's it.




Donate...
---------

All these sample programs for PP are free to use. However, if you
like them, please consider making a donation to show your support.
Any amount will be greatly appreciated. To proceed, just connect to: 
  http://www.aldweb.com/give.html  (secured PayPal transaction)




Updates Description
-------------------

  v5 (05/11/04)
    - added ARMlet switch if device runs with Palm OS 5.x (self
      detection) for faster display of cells generations in CellsPP, 
      also made some minor CellsPP source code optimizations
    - updated the PalmAPI.pas unit
    - added the ARMrsrc constant in the PalmARM.pas unit
    - added a new PalmMS.pas unit to ease the management of multi code 
      segments management
    - upgraded this help file (Piaf and PalmARM.pas use in the How to 
      Install paragraph)

  v4 (08/26/03)
    - corrected a comment label for Bench2GUI program (creator ID was 
      said to be referenced for Bench1GUI instead of Bench2GUI)
    - updated the web site URL of PP in all programs headers since the
      official PP web site has been moved from 
      http://pages.total.net/~hkontas/pp.html to its dedicated web 
      site http://ppcompiler.free.fr
    - also updated this help file accordingly
    - various updates made by Philippe Guillot in the PalmAPI.pas 
      unit file
    - in this help file, changed compatibility notice from v1.04C to 
      v2.02 of PP as I no more check compatibility with earlier versions
      of PP
    - added new unit PalmARM.pas
    - added Bench1ARM and Bench2ARM programs

  v3 (06/03/03)
    - removed use of "TPTypes.pas" in the GUI programs (CellsPP, 
      Matches2PP, NekoPP and NumerusPP) as this unit is meant to be
      used with console based applications that do not call Palm OS API
    - added Bench1GUI and Bench2GUI programs

  v2 (05/21/03)
    - renamed the "SysTraps.pas" unit name by the more appropriate
      "PalmAPI.pas" name and updated programs source codes that
      require it accordingly (CellsPP, MatchesPP2, NekoPP, NumerusPP)
    - added Bench1.pas and Bench2.pas programs
    - upgraded this help file

  v1 (11/22/02)
    - initial release
