home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / p / potland / pot / Docu / pOtNotes < prev   
Encoding:
Text File  |  1995-05-06  |  7.5 KB  |  204 lines
  1. David Tolpin, dvd@Jet.Msk.SU.
  2.  
  3.                     Overview.
  4.  
  5. pOt is an Oberon to C translator. It is derived from one-pass Wirth's
  6. compiler described in "Project Oberon" and retains some of the
  7. implementation limitations specific to that compiler.
  8.  
  9. pOt itself is written in Oberon (excluding three small
  10. modules' implementation - Files.c, Reals.c and OS.c), and have
  11. been successfully compiled under SunOS 4.1, FreeBSD, Linux and 
  12. MSDOS (using Turbo C 2.0).
  13.  
  14. pOt  IS NOT Oberon-2 implementation. It is not that difficult to
  15. implement the dialect, but I hate adding eclectic features to
  16. Oberon. It implements a language that is very close to one
  17. described in "Oberon Report" by Niklaus Wirth. There are maybe
  18. some inconsistencies, as well as implementation limitations, but
  19. mainly the cause for them is the pOt's genesis, not my changes.
  20.  
  21. Recently I compiled (with minor changes) Coco/R with pOt - it
  22. works, however my Texts implementation  relates a Text object to
  23. a disk file, not to a memory buffer with direct access. By the
  24. way, I don't like the way Coco/R is written (I mean the source
  25. codes). 
  26.  
  27. Garbage collector works for me well enough, and although it is
  28. expensive, the overall result is satisfactory - I can translate 
  29. (on MSDOS machine with TC 2.0 compiled pOt) the whole pOt within 
  30. 400 Kb of RAM; it requires to set GC threshold to 16 Kb, that
  31. decreases the execution speed by 10%. With GC threshold set to
  32. 128 Kb and collecting between source files 460 Kb is more than
  33. sufficient memory. (by the way, the executable itself is about
  34. 300 Kb, but I suspect that TC 2.0 stores public symbols' names in
  35. it).
  36.  
  37.                   pOt's output.
  38.  
  39. pOt produces three files for each source module (*.Mod)
  40.  
  41.   *.Cym - symbol file,
  42.   *.c -  C language source file,
  43.   *.h - external objects and types declarations (this file is
  44.   NOT included by *.c),
  45.   *.hi - static array that contains all string constants is
  46.   defined in this file, and *.c includes it.
  47.  
  48. New *.h created only if *.Cym is changed, thus, it is possible
  49. to use c <- h file dependencies efficiently.
  50.  
  51. Main module for a program is created by shell script mkmain.sh,
  52. and the script takes two arguments - the names of the module and
  53. the exported procedure to call.
  54.  
  55.                Environment settings. 
  56.  
  57. When pOt (actually, any pOt compiled program using Files module to
  58. handle files) tries to open an old file, it first looks for the
  59. file in the current directory, then in directories listed in
  60. POTLAND environment variable with obligatory trailing slashes.
  61. Directory names' separator is slash (this work for MSDOS too),
  62. paths' separator is semicolon for DOS, colon for UNIX.
  63.  
  64. New files are always created in the current directory.
  65.  
  66.               Distribution.
  67.  
  68. pOt - the root directory
  69.   bin - compiled binaries
  70.   Docu - documentation files
  71.   lib - Oberon libraries
  72.     Core - core library and RTL
  73.   src - source code for pOt
  74.   Tests - if exists, may contain several simple Oberon programs
  75.   Scripts - some shell scripts
  76.               
  77.               Using pOt.
  78.  
  79. Call to pOt has the following format:
  80.   
  81.     "pOt" {("-"options|file|"@"parfile)" "}
  82.  
  83. where file is a source file name (with extension),
  84. parfile is a name of a file from that command line parameters
  85. are read (in which case all control characters (with 0 < code < 32)
  86. are treated as separators),
  87. options is a list of characters from the following set:
  88.     ILMNORSTUilmnorstu;
  89. each character in either case corresponds to a different flag,
  90. an upper-case character turns the corresponding flag on, a lower case
  91. off. The flags (and their corresponding characters) are
  92. following
  93.  
  94.     F - wraps lines of C code so they almost fit 
  95.             into 80 columns (default off),
  96.     H - allows generation of new C .h files (default off);
  97.   I - index check (default on),
  98.   L - if on, error messages are displayed inf format
  99.       <filename>(<line>,<col>) err|warning <errnum>
  100.       if off,
  101.       pos <posnum> err|warning <errnum> (default off);
  102.   M - include CR (CHR(13)) as the first character into 
  103.       the line separator (default off);
  104.   N - generate line numbers (default off);
  105.   O - nil pointer dereference check (default on);
  106.   R - range check (default on);
  107.   S - allow generation of new symbol file (default off);
  108.   T - type checks (default on);
  109.   U - append NL (CHR(10)) to the line separator, if not
  110.      already appended (default on).
  111.  
  112. If both 'm' and 'u' are set, 'U' is assumed; setting these
  113. flags to 'UM' forms the MSDOS line separator.
  114.  
  115. Errors and warnings are reported by number, the explanations are
  116. listed  in pOtErr.Txt, that is in Docu directory of the
  117. distribution.
  118.  
  119.         Compiling C text and linking.
  120.  
  121. pOt produces ANSI C text, but the text is tricky enough to make some
  122. compilers shout. Turn off warnings, they are completely
  123. useless. pOtRTL.h must be made accessible via include path.
  124. When linking a program containing Oberon modules, result of
  125. compilation of pOtRTL.c must be included into the link list - it
  126. is the pOt's runtime library. Usually, modules pOtRTL.c, OS.c,
  127. Reals.c, and OS.c (these modules are written manually) are
  128. composed into a pOtCore.(a|lib|so) library.
  129.  
  130. If a stand-alone Oberon program is created, a main module must
  131. be created (supposedly by mkmain.sh) and included into the link
  132. list.
  133.  
  134.         Important notes on implementation's limitations.
  135.  
  136. First, if a string is passed to an array value parameter that is
  137. longer by more than 2048 elements than the string, error 244 is
  138. reported. This maybe avoided by, e.g., copying the string (using
  139. COPY function) to a character array variable and then passing
  140. the variable. (COCD.Overhead sets the limit).
  141.  
  142. Second, a named string constant's value may not be set via
  143. referencing to an imported constant. This is much weaker
  144. limitation than Wirth's, according to which strings cannot be
  145. exported at all.
  146.  
  147. Most other limitations are caused by sizes of corresponding
  148. compiler's tables. 
  149.  
  150.               Minimum library.
  151.  
  152. The library (lib directory and subdirectories of the distribution) 
  153. contains several modules those may be useful. Since they are
  154. usually 'demand written' I do not document them here. 
  155.  
  156. Recent changes.
  157.  
  158.  
  159. > So called "code procedures" will be used for that. The syntax is retained
  160. > as it is implemented in Wirth's compiler, i.e. the name of the procedure
  161. > is prepended with "-", and after the declaration a number is specified.
  162. > 
  163. > e.g.,
  164. > 
  165. > PROCEDURE fopen(i: LONGINT; j:LONGINT):LONGINT 0;
  166. > 
  167. > But the number is meaningless in my implementation.
  168. > 
  169. > These procedures are translated into the calls to C procedures of the same
  170. > name. It should be common practice to use them in conjuction with SYSTEM.ADR:
  171. > 
  172. > 
  173. > MODULE Clib;
  174. >     PROCEDURE -fopen*(fn: LONGINT; mode: LONGINT): LONGINT 0;
  175. > END Clib.
  176. > 
  177. > MODULE Test;
  178. >     IMPORT SYSTEM, Clib;
  179. >     PROCEDURE foo*;
  180. >         VAR a:LONGINT; name,mode: ARRAY 100 OF CHAR;
  181. >     BEGIN name := "test"; mode := "r+";
  182. >         a := Clib.fopen(SYSTEM.ADR(name),SYSTEM.ADR(mode))
  183. >     END foo;
  184. > END Test.
  185.  
  186.  
  187. The possibility to insert untranslated calls to C-functions is added.
  188. Here is an exerpt from my letter on the subject:
  189.  
  190. This release is intended for testing, so don't expect too much 
  191. from it. If you have any bug reports/suggestions please e-mail
  192. them to any of the following addresses
  193.  
  194.     dvd@fe.msk.ru,
  195.     dvd@pizza.msk.su,
  196.   dave@dream.demos.su
  197.  
  198. letters in English, Russian/koi8 are OK. I understand German too,
  199. but the answer will be in English. My wife knows French.
  200.  
  201. Please do not offer language extensions.
  202.  
  203. DT 31-Oct-94. Moscow.
  204.