PalmOS Pascal Compiler Version 2.00 (full version including native 68k and ARM code generation) Version 1.09 (Standard VFSDos version for 68k code generation only) 2003/05/02 by Philippe GUILLOT ph.guillot@wanadoo.fr INTRODUCTION: ------------- PP is a freeware standard Pascal compiler for PalmOS. PP generates true native 68000 or ARM executable code (.PRC) from standard Pascal source code. You can use your favorite Palm DOC editor to write your code, and either run PP from the VFSdos console or PPShell to compile and run your program. VFSDos applications created by PP have all the same Palm unique registered ID 'pDOS', which is the standard ID for all VFSdos applications. This means that your compiled applications can be executed from either the PP shell interface, or the VFSdos console, and you do not need to register a unique ID for them. For more information about VFSdos, please visit the VFSdos web page. PP is also able compile Palm graphical UI applications, hack extensions, shared libraries and multi segment applications (see further and provided samples). PP has been tested on the following handhelds: Palm III, m500, m505, m515, Sony Clie T625, TRGpro and Tungsten T. Although PP has been tested extensively, like any other Palm application, it may have bugs. Please contact me for any suggestions or bug reports. REQUIREMENTS: ------------- - PalmOS 3.5 or greater. PalmOS >=5.0 is required to execute armlet. - 140 k of free dynamic heap memory. - Mathlib library (only if the program uses one the mathematical functions: arctan, cos, sin, log, exp or sqrt). - VFSDos (*) console interface. (*) NOTE : If you wish you may use PP within the VFSdos console, instead of PP Shell. VFSdos is a DOS-alike console interface for PalmOS. You can find the latest version of VFSdos from the following site: http://pages.total.net/~hkonstas/vfsdos.html DOWNLOAD: --------- You can download the current version of PP from the following link: http://pages.total.net/~hkonstas/pp.html INSTALLATION: ------------- Distribution files: PP_EXE.PRC: The Standard Pascal compiler for VFSdos, version 1.09. ppLight/PP_EXE.PRC A version of the compiler for low memory device such as m100. ppARM/PP_EXE.PRC The full version 2.00 for also compiling armlet on OS5 devices. STDIOLIB.PRC: The latest STDIO library (required). PPSHELL.PRC: The compiler gui shell application (if you do not use VFSdos on your handheld). *.PAS: Pascal source code samples in DOC format. PgmPP.zip Laurent Duveau's demo files Optional files (NOT included in the distribution ZIP): VFSDOS.PRC: The Harry Konstas VFSdos console. MATHLIB.PRC: The mathlib library required for optional math operations. QED.PRC: The doc editor (shareware) available at http://www.qland.de/qed/ Install one of the "pp_exe.prc" and the latest version of the STDIO library, StdioLib.prc. If you are already using an older version of StdioLib, please install the version included in this distribution zip file. You may also install PPshell.prc if you do not have VFSdos installed on your handheld. You may find useful to also install the pascal sample files included in the zip to get you started. Please note that source code files are databases in uncompressed DOC format, readable by any DOC reader. If a message "unable to initialize" appears, you may try to install the file included in the folder ppLight. This version has a lower memory requirement. In counter part, some huge source may not compile and the executable sise is limited to 24 ko. The version 2.00 included in the ppArm forlder has the same features as the standard PP and in addition, it may compile native armlet (using the directive {$armlet xxxx,yyyy,zzzz,nnn} similar to the {$code...} directive described in the sequel). It support most Pascal features except standard io and real transcendental functions (sin, cos, etc.) which are not yet implemented. The compiler runs on 68k devices, but arm code runs only on OS>=5. ************ WARNING : ARM CODE DOES NOT RUN ON POSE ************************** USAGE: ------ Launch the PP Shell application and you will see the list of the sample source code files (all in DOC format, having the .pas extension). Simply select the file you want to compile, and press the GO button. Once the source has been successfully compiled, select the EXECUTE button. Now you will see the list of all the compiled PP applications. You can enter optional arguments in the text field under the list, and press the GO button to execute your application. Use the DEL button to delete a selected application from the list. In compile mode, the EDIT button launch QED doc editor (if present) on the selected file. If you have VFSdos installed on your handheld and will be using PP from within the VFSdos console, you simply launch pp with the source filename as a parameter directly from the VFSdos prompt: c:>pp sourcename where 'sourcename' is the name of your application source database. This example compiles the doc database named 'sourcename.pas'. If the program header in your source code is: program exename; ... then a PRC database named 'exename.exe' is created. Finally, to execute your compiled application, just type it in the VFSdos command prompt: c:>exename where are the optional application parameters (if any). When run is over, any key hit returns to VFSDos or PPShell. PP supports cooperation with doc editor QED ( http://www.qland.de/qed/ ). Version >= 2.73 is required. If an error occurs when compiling, a prompt "goto error ?[y]" proposes you to launch Qed at error position. PP LANGUAGE FEATURES: ---------------------- The langage syntax is compliant to the ISO 7185:1990 level 0. In particular,it supports - nonlocal goto, - procedure and function as parameter, - standard syntax for new and dispose for pointer to record with variant. The conformant array parameters are NOT supported. There is no runtime range control. See http://www.morecad.com/standardpascal/home.html for a complete description and the demo sources for examples. In addition, the language supports some of the Turbo Pascal extensions such as strings, @ operator, bitwize operators, etc. Files: ------ Files are stored as uncompressed doc database in binary format. Files of char and text are readable by any doc reader. The read functions supports compressed doc. Files other than input and output which are declared in the program parameter list are assigned to the actual parameters of the command line. The function reset(f) opens a file for reading which is specified in the program parameter list. To open a file while is not in the program parameter list, the syntax is reset(f,name), where name is a string. The same convention applies to open a file for writing using the procedure rewrite. The (non standard) function close(f) must be called for all open files. The standard input supports interactive mode (lazy I/O) for get procedure and when reading characters on the VFSDos console. Runtime error codes: -------------------- 102: Program parameter missing. 103: VFSDOSdata database not found. 105: File not open for inspection. 106: Unexpected end of file (EOF) while reading. 110: File not open for generation. 120: Invalid integer or real format. 158: Incorrect width parameter on text write. 201: mathlib library not found. 206: Unable to open file. 301: log or sqrt has negative parameter. 1000: Internal error (unexpected NULL handle). Misc: ----- - Real are 32 bit float IEEE 754 compatible; - Integer are 32 bit int; - Enumerated type is 8 bit; - Array and record size is limited to 32k; - Global data storage is limited to 32k - String constants storage is limited to 32k - Integer sets are limited to the range 0..255 - Packed structured type are implemented as unpacked types. Adresses are aligned to the even memory location for data greater than one byte. - Functions pack and unpack are not currently supported. - Subrange types are packed: a variable declared of type 0..65535 uses 2 bytes in memory. - Function odd and sqr are implemented inline and may not be invoqued as function parameter. - Boolean expressions are evaluated from left to right and the evaluation is aborted as soon as the result is known: in the expression a or b, the expression b is not evaluated if the value of a is true. - Other expressions and assignement statements are evaluated from right to left. In the statement t[i]:=a+b, the expression b is evaluated first, then a and then i (it may be important in the case of function with side effect). - Program paramater may be of type file, text or string. Additional functions and procedures: ------------------------------------ - gotoxy(x,y), procedure, positions the cursor at the desired screen position. - textmode(mode), procedure, selects video mode: 1=32 cols 0=40 cols. - clrscr, procedure, clears the screen. - delay(n) waits for n milliseconds. - random(n) returns a pseudo-random integer in the range 0..n-1. Non standard features: ---------------------- 1. Most constant expression computable at compilation time are allowed anywhere a constant value is expected. examples : const n = 5; nn = 2*n; type table = array[0..nn-1] of n..3*n; Mathematical functions sin, exp, arctan, sqrt, log are not allowed in constant declaration. 2. The packed array [1..?] of char type not supported for reading and writing. It is replaced in version >= 1.01a by the usual string type. - string[n] denotes a zero terminated string of at most n characters; - the default size is 63 characters not including the terminal zero. Therefore, string is equivalent to string[63]; - the first character of a string s is accessed by s[1]; - The null string '' is allowed, it is equivalent to chr(0); The following operators are supported for string types: - comparison with lexicographic order <, <=, >, >=, =, <> - concatenation + The string type is compatible with the char type and with any other string type, A string type var parameter is comptatible with any other string type variable. The inline function "length" returns the actual string length The string type is allowed as return type of a function. 3. The directive "inline" allows to insert 68000 or THUMB native code such as PalmOS API systrap's. When calling an inline procedure or function, the specified sequence of 16 bit constant in inserted. The constant in an inline sequence may be - any 16 bit integer constant; - any string constant (completed by zero for word alignement); - @VariableIdentifier, to define the 16 bit offset of the variable relative to A5 for global variables and to A6 for locals (mode 68k only, not in ARM mode). - @ProcedureOrFunctionIdentifier to define the offset of the defined procedure or function relative to the current program counter pc (mode 68k only, not in ARM mode). 4. Character '$' starts hexadecimal representation integers. 5. Underscore '_'is allowed inside identifiers. 6. Hard button page up stops the program while writing on the console. 7. The read procedure applied to a character is bufferised (batch mode). To use the interactive mode, use c:=input^; get(input). The variable input must be declared in the program parameters : program name(input); ... 8. The C++ style comment is supported : character following // are ignored until the end of line. 9. A predefined type "pointer" is assignement compatible with all other pointer types. The domain type of the "pointer" type is "pointer". 10.Typeless Var parameter are supported. In this case, any variable is compatible in the actual parameter list. 11.Additionnal keywords "shl" and "shr" are the usual shift operators. They have the same precedence as *. 12.Additionnal keyword "xor" performs the exclusive or with the same precedence as "or" 13.Boolean operators "or", "and" and "xor" perform bitwise operations when they apply on integer. 14.Function "sizeof" applied to a variable defines a constant equal to the number of byte of the variable. 15.Procedural type are allowed, e.g. type ProcType=procedure(var i:integer); 16.Adress operator '@' applied to a variable, a function or a procedure returns a pointer type, e.g. p:=@f; 17.Set are allowed in constant declaration. e.g. const op = ['+','-','*','/']; 18.In the armlet mode, the directive "systrap" defines a procedure or function as a call to a OS function. e.g. Procedure WinDrawChars(const chrs:string;len:Int16;x,y:Coord); systrap $220; The systrap number is anded with $00000fff. Only the three last hexadecimal digits are taken into account in the systrap number. The compiler automatically generates endian swapping call for parameter conversion. Compilation directives ---------------------- {$i filename} include the file at the position specified {$r resourcefilename} specifies a resource file to include to the PRC file {$appl creator} specifies to build a 'appl' type PRC with the specified creator. The creator must be a sequence of 4 characters in the range '!'..'~' (33..127). In this case the following standard features are not allowed - all file and text type; - file and text standard function (get, put, read(ln), write(ln), eof, eoln); - mathematical functions (sin, arctan, exp, log, sqrt, cos); - additionnal console function (gotoxy, clrscr); Launch parameters cmd (16 bit integer), cmdPBP (pointer), launchFlags (16 bit integer) must be declared in the program header and declared in global variable section if used. The scope of these variables is the main program section and they cannot be invoqued in other functions or procedure. If a program is lauched with a nonzero cmd value, the global variables segment is not initialised. The non local goto's in destination of the main program section, constant strings and precomuted sets invoque global memory and must not be used in a program section executed with nonzero cmd parameter. See demo ppShell.pas (source code of PPShell rewriten in Pascal) for further details. {$code xxxx,yyyy,zzzz,nnn} creates a resource of type zzzz identifier and nnn (a sequence of digits). xxxx is the type and yyyy is the creator of the PRC. The name is specified in the program header. This directive allows to use PP as a code resource editor useful for programming hackmaster extensions, multi segment application and shared libraries (see sample CaseHack.pas, Multi.pas and GaussLib.pas). The code segment contains in this order - the main program section if it is not empty - the procedures and functions in the order they are declared. You may declare global variables in a code resource, but the corresponding data resource is not created. These declarations should only be used in case of multi-segment application where the same declaration occurs in the main program file. They are used do define the variable access to the data segment in the compiled code. By default, the constant strings and precompiled set are stored in the data segment. To avoid problems in code ressource, you may use the directive {$c+} (see further) to force constant storage in the current code segment. Program parameter must be declared as global variable. The scope of the program parameters is the main program section. They cannot be invoqued in other procedure or functions. {$armlet xxxx,yyyy,zzzz,nnn} creates a resource of type zzzz identifier and nnn (a sequence of digits). xxxx is the type and yyyy is the creator of the PRC. The generated code is native ARM and the created resource may be called throught the pceNativeCall function. The global variable section of an armlet corresponds to the data passed to pceNativeCall function. The result is an error code it is nonzero in case of integer division by zero. {$define xxxx} sets symbol xxx as defined. 16 symbols are allowed with no interaction with other identifier nor keyword {$undef xxxx} set symbol xxx as undefined, but do not erase it. {$ifdef xxxx} {$ifndef xxxx} {$else} {$endif} are usual conditionnal compilation directives. {$c+} force constant litteral strings and precomuted sets to be stored in the code segment. In "code" mode, local constants are automatically stored in the code. If no global constant occurs, the use of this directive is unnecessary. {$c-} force constant litteral strings and precomuted sets to be stored in the data segment. Disclaimer: ----------- The PP compiler is distributed as freeware, and like any software application, although well tested, it may contain bugs. The author cannot be held responsible for any data loss. The user takes full responsibility for using the program. Acknowledgement: ---------------- Thanks to - Harry Konstas - Laurent Duveau - Peter Obukhov - John Newell for their contribution and help in the development of PP. HISTORY: -------- 2.00 may 2nd. 2003 : Real computation and systrap directive in ARM mode, minor fixes. 1.08 apr 8th. 2003 : bug fixes, string type allowed as program parameter, set allowed in constant declaration. Sets in ARM mode. 1.07 feb 14th. 2003 : minor changes, bug fixes (with statement, real and string comparison, strings in armlets) 1.06 feb 5th. 2003 : large code bug fix, conditionnal directives, {$c+/-} directive, change in the {$code ...} directive syntax, inline extensions. 1.05d jan 17th. 2003 : bug fix in "in" operator. 1.05c jan. 1st. 2003 : bug fixes : infinite loop when execute readln; StdioLib update (accepts bookmark in source doc file); bug in reset(f,'filename'); 1.05b Dec. 25th. 2002 : bug fixes : with statement and pointers, char to string conversion. 1.05a Dec 10th. 2002 : procedural type, address operator. 1.04d Nov 20th. 2002 : sizeof function and code directive. 1.03g Nov 15th. 2002 : Bugs fixes. 1.03f Nov. 11th. 2002 : additionnal support for Palm applications. 32 bit integers, pointer type, xor and shift operator, bitwise operations and the usual bug fixes. 1.01a: Oct. 1st,2002: Bug Fixes on reals, Constant set precomputation, additionnal features (strings, inline functions and procedures, include directive). 1.00d: Sept. 13th,2002: Bug Fixes, code optimization, samples. 1.00c: Sept. 7th,2002: Bug fixes, speed and code optimizations. 1.00b: Sept. 2nd, 2002: Minor update (bug fixes, PPshell updated). 1.00a: August 31st, 2002: Initial Release. * The PP compiler has been developped by Philippe Guillot on a Tungsten T using OnBoardC, QED and RsrcEdit. * PP Shell was written by Harry Konstas on a m505 using OnBoardC, QED and RsrcEdit, translated into Pascal by Philippe Guillot. Philippe GUILLOT ph.guillot@wanadoo.fr