home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / pccts1.zip / README.106 < prev    next >
Text File  |  1993-03-23  |  10KB  |  251 lines
  1.  
  2.                             Welcome to PCCTS 1.06
  3.  
  4.                                December 1992
  5.  
  6.  
  7.                   Purdue University Electrical Engineering
  8.  
  9.                                 Terence Parr
  10.                                  Hank Dietz
  11.                                  Will Cohen
  12.  
  13.  
  14.                                 INSTALLATION
  15.  
  16. UNIX USERS
  17.  
  18.      If you received your PCCTS copy via email, please see the section
  19. below concerning EMAIL RECIPIENTS.
  20.  
  21.      PCCTS 1.06 includes a number of different programs and examples
  22. in the software release package -- most of which like to live in their
  23. own directories.  The install script will build a standard hierarchy.
  24.  
  25.      The PCCTS executables (antlr, dlg) may be placed anywhere the user
  26. wishes but the install script places them in the bin directory created
  27. during installation.
  28.  
  29.      To begin installation, the user should create a directory (usually
  30. called pccts) where the PCCTS source subtree is to be created.  Place
  31. the pccts.bag file and the install script into this directory and cd
  32. into it.  To install PCCTS, simply type
  33.  
  34.      sh install
  35.  
  36. which will build the standard PCCTS directory hierarchy (under the
  37. directory where you ran the install script), "unbag" all of the files
  38. and build executable versions of antlr and dlg.
  39.  
  40.      The examples associated with PCCTS have makefile variables called
  41. ANTLR, DLG etc... which must be set according to your personal
  42. directory structure before make'ing.  Some variables point to the
  43. PCCTS executables if the PATH environment variable does not include
  44. your bin directory.  Also, there are variables that point to PCCTS
  45. include directories and must be changed if you deviate from the
  46. standard PCCTS installation hierarchy.  antlr and dlg can be built
  47. without executable versions of themselves (antlr and dlg are written
  48. in themselves).  The grammar files for antlr and dlg are included with
  49. this release.
  50.  
  51. NON-UNIX USERS
  52.  
  53.      ANTLR was written using portable (we hope), vanilla K&R-style C
  54. and ANSI C.  It has been successfully ported to PC's (large model,
  55. Microsoft C 6.0-- 16-bit integers, 32-bit pointers) and 68020-based
  56. Macs.  We do not provide an installation script for non-Unix users.
  57. You must interpret the install script and perform the analogous
  58. operations on your machine.  Briefly,
  59.  
  60.      Create a directory for PCCTS.  Go inside.
  61.      Make the following sub-directories:
  62.           antlr dlg h support support/sym support/set support/rexpr
  63.           lang lang/C bin
  64.      Make the unbag executable with:
  65.           cc -o bin/unbag unbag.c
  66.      Run unbag on the main pccts.bag ('unbag pccts.bag').
  67.      Move all of the .bag files to the directories with their name.
  68.      Move genmk.c to the support directory
  69.      Run unbag on all .bag files from within their directories.
  70.      Rename all makefile.user files to makefile (in antlr, dlg, lang/C).
  71.      In antlr directory, create an empty parser.dlg
  72.          and make the scan.c date stamp new ("touch" it)
  73.      Make antlr
  74.      In dlg directory, create an empty parser.dlg
  75.          and make the scan.c date stamp new ("touch" it)
  76.      Make dlg
  77.      Compile genmk.c
  78.  
  79. IMPORTANT NOTE:  You must create the parser.dlg and "touch" scan.c in
  80.                  antlr and dlg directories or the makefiles will try to
  81.                  execute antlr and dlg, which don't exist yet.  The first
  82.                  time, you want only to compile the C files in order to
  83.                  obtain an executable for antlr and dlg.  From this point,
  84.                  a change in antlr.g or dlg_p.g will force antlr/dlg to
  85.                  regenerate themselves.
  86.  
  87. IMPORTANT NOTE:  See the notes about WORD SIZE below.  You MUST
  88.                  "#define PC" for the preprocessor so that the word size
  89.                  will be 16bits for int's IF you have a machine with
  90.                  this size; e.g. a IBM PC clone.
  91.  
  92.      For Mac programmers using MPW (Maciontosh Programmer's Workshop),
  93. an "#ifdef MPW" is included to print error messages that can be
  94. "executed" to highlight the error location.  In other words, the line
  95. in the file where the error occured will be highlighted by hitting
  96. "enter" over the error message.  Add "-d MPW" to your list of compile
  97. flags.  See generic.h in antlr directory.
  98.  
  99. EMAIL VERSION RECIPIENTS
  100.  
  101.      If you received PCCTS via email response from
  102. pccts@ecn.purdue.edu you have one additional installation step to
  103. perform over the ftp folks.  You will have received a number of
  104. bite-size chunks of pccts which are small enough to be emailed (~1500
  105. lines each).  You must reconstruct the PCCTS files before you can
  106. begin installation.  In order to rebuild an original file, you must
  107. have "one.c" which will take the chunks and pack them together.  If
  108. you are a non-UNIX type, you must have the "unbag.c" file which unbags
  109. the bags created by our mail archiver.  UNIX folks use the shell to
  110. unbag as they would for shar files (this will be done automatically by
  111. the install script).
  112.  
  113.      To install PCCTS, place all PCCTS mail messages into a pccts
  114. directory, remove the mail headers from one.c, and install.  Then
  115. compile one.c with:
  116.  
  117.      cc -o one one.c
  118.  
  119. and then type:
  120.  
  121.      ./one f1 f2 ... fn
  122.  
  123. where f1..fn are the parts of PCCTS source sent as chunks (i.e. these
  124. files will be all the files you received NOT including one.c, unbag.c,
  125. README, install and the request acknowledge banner).  There is no need
  126. to remove mail headers from the chunk files and they may appear in any
  127. order.  The subject line of the mail will identify it as a chunk and a
  128. chunk of what file.  The "one" program should be used to put pccts.bag
  129. back together.  You are now in a position to begin normal PCCTS
  130. installation.  All files you receive should go into a pccts directory.
  131.  
  132.      Note that all files which arrive in "chunks" must be put back
  133. together using "one".  Beware that you do not mix chunks from more
  134. than one original file.  For instance, do not specify all chunks that
  135. you collect from the PCCTS mailbot on the "one" command line unless
  136. you have requested only one original file that was split into multiple
  137. files.  Each chunk knows which original file it is a part of, where it
  138. goes in that file and how many total chunks are required to rebuild
  139. that original.
  140.  
  141. WORD SIZE
  142.  
  143.      PCCTS makefiles assume 32-bit integers.  If you have 16-bit
  144. integers (or heaven-forbid another size), you must change set.h in
  145. support/set and output.c in dlg.  Both files have an "#ifdef PC"
  146. preprocessor command to change wordsize definitions.  You can add
  147. another "#ifdef" for your machine or specific wordsize.  If you have
  148. 16-bit integers, you may simply define "PC" as a preprocessor flag (by
  149. changing the makefile variable "CFLAGS" to include "-DPC").
  150.  
  151.                                 TUTORIAL
  152.  
  153.      The advanced tutorial should be placed in a directorty at the
  154. same level as antlr, dlg, support etc...  Do a
  155.  
  156.      sh advtut.bag
  157.  
  158. to unbag (or use the unbag program) and then type
  159.  
  160.      make -s all
  161.  
  162. which will create executables called tut1-tut4.  These executables
  163. correspond to the examples in the tutorial.
  164.  
  165.                               NEW FEATURES
  166.  
  167. The following bullet points are the headers in the file UPDATE106.text:
  168.  
  169. o   Predicated Parsing -- EXTREMELY ALPHA
  170.  
  171. o   1.06 Is Written in 1.00
  172.  
  173. o   ANTLR Compiles Under ANSI C
  174.  
  175. o   Grammar Files, antlr.g and dlg_p.g, Distributed
  176.  
  177. o   Script Generates Makefiles for PCCTS Projects
  178.  
  179. o   DLG Supports Case Insensitive Scanners
  180.  
  181. o   Delayed Lookahead Fetches in Generated Parser
  182.  
  183. o   Tutorials Available
  184.  
  185. o   Error Messages for k>1 Improved
  186.  
  187. o   Trace Facility has Exit Macro
  188.  
  189. o   Resource Limitation
  190.  
  191. o   Rule Prefix Option
  192.  
  193. o   Standard PCCTS Header Generated
  194.  
  195. o   Doubly-Linked AST's
  196.  
  197. o   C++ Compatible Parsers
  198.  
  199.  
  200.                          MACHINE COMPATIBILITY
  201.  
  202. PCCTS Version 1.06 has been successfully tested on the following
  203. platforms:
  204.  
  205. o   Sun 3/60
  206. o   Sun SPARC I, II
  207. o   Encore Multimax running Umax 4.3
  208. o   Sun sparcstation IPX
  209. o   NeXTstation
  210. o   unknown VAX running Ultrix 4.2
  211. o   DEC 5000
  212. o   Linux on 386PC
  213. o   Microsoft C 6.0 on PC OS/2, DOS
  214. o   CSET/2 C compiler on PC OS/2
  215. o   IBM RS6000
  216. o   MIPS 4000
  217.  
  218.  
  219.                            INCOMPATIBILITIES
  220.  
  221.      Due to the bug fixes in 1.06, new ambiguities may appear in your
  222. grammar.  These were always there--ANTLR simply did not find them.
  223. The analysis is more correct.
  224.  
  225.     Calls to zzTRACE are no longer generated by the -gd option.  Now,
  226. zzTRACEIN, zzTRACEOUT are called at the beginning and end of
  227. functions, respectively.
  228.  
  229.      The way in which PCCTS translates actions has been changed; before
  230. they were parsed with a C function, now the #lexclass facility is
  231. being used.  Some differences in translation may be discovered; e.g. a
  232. character may need to be escaped with \ whereas before the simple
  233. character was sufficient.
  234.  
  235.      The user should no longer set the next token of lookahead or the
  236. text of the next token in the lexical analyzer using LA(1) and
  237. LATEXT(1).  This is incompatible with the -gk option; hence, NLA and
  238. NLATEXT should be used instead where the N means next.
  239.  
  240.      The -ga does not generate anything different as the code
  241. generator now dumps both K&R and ANSI with #ifdef's around the ANSI
  242. code.
  243.  
  244.      Previously, no prototype was given when -ga was off.  Now,
  245. prototypes are always generated (with the appropriated #ifdef's).
  246. These prototypes can conflict with the outside environment if the rule
  247. names are things like if and stat (which is a system call).  Use the
  248. -gp prefix option to prefix all functions corresponding to rules with
  249. a string of your choice.
  250.  
  251.