home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 2 / RISC_DISC_2.iso / pd_share / program / language / oberon / pot / ReadMe1st < prev   
Encoding:
Text File  |  1995-05-08  |  5.6 KB  |  155 lines
  1. !pOt for the Archimedes
  2.  
  3.   This is a port ot pOt (portable Oberon translator) for the Archimedes.
  4.   pOt translates an Oberon (not Oberon2) file to a C file, that should
  5.   be compiled with a C compiler. 
  6.  
  7.   This archive contains all the files you will need to compile Oberon
  8.   programs with pOt. The pOtSrc archive has all the source code
  9.   needen to rebuild pOt and its runtime libraries yourself.
  10.  
  11.   pOt is written by David Tolpin, and runs under different flavors of
  12.   Unix and MS-Dos. I have changed the filename handling to be compatible
  13.   with the Arc way (extension directories), added Throwback support and
  14.   embedded the error messages in pOt.
  15.   The version of pOt for this port is 1.33, the original pOt can be found
  16.   at:
  17.  
  18.     hades.ethz.ch in /pub/Oberon/NonETHSystems/pOt
  19.  
  20. Note.
  21.  
  22.   I have only tried this with Desktop C v4, your experiences with other
  23.   C compilers (GNU CC, Easy C/C++, Desktop C v5 etc) are gratefully
  24.   received.
  25.  
  26.   Having Sed makes some things easier. Sed is not included in this
  27.   distribution, because it is readily available at different Acorn-
  28.   specific FTP sites. My copy comes from the !Virtual distribution.
  29.  
  30.   pOt is not a full blown Oberon system, far from it. The supporting
  31.   runtime libraries are just enough to make it to compile itself.
  32.   As far as I am concerned, it is capable as a cross-compiler for
  33.   bootstrapping a native Oberon-2 compiler (Don't hold your breath
  34.   waiting for this).
  35.   
  36.   It should be easy to make the In and Out modules as featured
  37.   in the book 'Programming in Oberon, steps beyond Pascal and 
  38.   Modula' by M. Reiser and N.Wirth' ISBN 0-201-56543-9, ACM Press
  39.   and Addison-Wesley Publishing Company.
  40.  
  41.  
  42. Package
  43.  
  44.   !pOtLand    : Resource directory. Contains the pOt runtime library
  45.                 and some Oberon modules and their symbol, .h and .hi
  46.                 files.
  47.   bin.mkmain  : Creates the entry point for the Oberon program
  48.   bin.pOt     : The main executable
  49.   DDE.!mkmain : DDE frontend for mkmain
  50.   DDE.!pOt    : DDE frontend for pOt
  51.   test        : A small example
  52.  
  53. Installation
  54.  
  55.   Put pOt, mkmain and sed in your Library directory, or at least in a
  56.   directory contained in your Run$Path.
  57.   Put !pOtLand somewhere easily accessible, for example in your root
  58.   directory, or along your !DeskLib application.
  59.   If you don't have the DDE, you can go to "How to use pOt"
  60.  
  61.   Put DDE.!pot and DDE.!mkmain in your DDE-directory.
  62.  
  63.   If you like to experiment with !Make-generated makefiles using pOt,
  64.   put this in !Make.choices.tools  
  65.  
  66.   ----------Cut here------------
  67.     pOt
  68.     mod
  69.     -L
  70.     pOt $(potflags) $<; cc $(ccflags) -o $@ $*.c
  71.     DDE:!pot.desc
  72.     DDE:!pot.!setup
  73.   ----------Cut here------------
  74.  
  75.  
  76. How to use pOt
  77.  
  78.   You must create a work directory. This directory structure should
  79.   have the following subdirectories.
  80.   
  81.     c    : C files                  generated by pOt
  82.     Cym  : Symbol files             generated by pOt
  83.     h    : header files             generated by pOt
  84.     hi   : constant-strings files   generated by pOt
  85.     mod  : Oberon files
  86.     o    : Object files             generated by the C compiler
  87.     TMP  : temporary files          for use by pOt
  88.  
  89.   pOt also uses a temporary file in <Wimp$ScrapDir>.
  90.  
  91.   If you don't have the DDE, the wordirectory must be your current
  92.   directory. pOt uses DDEUtils to set <Prefix$Dir>, except when the
  93.   first character of the Oberon file is '@'.
  94.  
  95.   First, pOt puts its parameters in the temporary file in <Wimp$Scrapdir>.
  96.   Then, it translates the Oberon source file. When it encounters the 
  97.   IMPORT-statement, it first looks for symbol files in workdir.Cym, and
  98.   then in pOtLand:Cym. pOtLand is set by the !pOtLand resource application.
  99.   When the Oberon module contains no errors, a c.- and a hi.-file is created,
  100.   and optionally a Cym.- and h.-file.
  101.   
  102.   Oberon programs are started by calling an exported PROCEDURE with NO
  103.   parameters. This clashes with nearly everybody else's way to start
  104.   programs. The solution used by pOt is to create a simple C file with
  105.   a main() function that calls the specified PROCEDURE. This file is
  106.   created by mkmain from a template file called pOtLand:main/tpl (this
  107.   file is in pOtland:Core).
  108.   If you don' have sed, you can do this by hand. Look at test.c.Say_Hello
  109.   how it is done.
  110.  
  111.   Compile the generated C files, including the one generated by mkmain.
  112.   Put pOtLand: and C: in the include path (-I)
  113.   Turn all warnings off (with -w  (one space)) or Suppress -> ' '.
  114.  
  115.   Link the resulting object files, and include the pOt runtime libraries
  116.   pOtLand:o.pOtLib and pOtLand:o.pOtCoreLib, *AND* a C runtime library
  117.   (I use the Shared C library stubs C:o.Stubs).
  118.  
  119.  
  120. Differences
  121.  
  122.   There are a few differences between Archimedes-pOt and the Unix version
  123.   (except for the obvious extension directory trick):
  124.  
  125.   - The generated C file includes hi.<name> instead of <name>.hi
  126.     The preprocessor of Desktop C v4 wants it this way.
  127.  
  128.   - Looking for Cym. files in the curent directory and in pOtLand:
  129.     is explicitely programmed, instead by adding POTLAND to PATH 
  130.     (Unix) -> adding pOtLand: to File: (Arc).
  131.  
  132.   - Errors are embedded in the scanner. This makes Throwback a lot more
  133.     usefull.
  134.  
  135.   - The indirection file is prefixed by ! instead of @. @ clashes with
  136.     the current directory indicator in RISC OS pathnames.
  137.  
  138. Bugs
  139.  
  140.   - The line number in errors is sometimes/often one too high.
  141.  
  142.   - Throwback cannot be turned off.
  143.  
  144.   - The runtime library is a bit tiny. It should be possible to put
  145.     MODULE's In and Out (see Programming in Oberon) on top of 
  146.     MODULE Files.
  147.  
  148. Contacting me
  149.  
  150.   email     : svdwal@xs4all.nl
  151.  
  152.   snail mail: Sander van der wal
  153.               Bevrijdingsplein 39
  154.               2321 BX Leiden
  155.               The Netherlands