------------------------------------------------------------------------
This is the 2.50 release of PRECCX  (README)               Jan     1999
Peter T. Breuer   <ptb@it.uc3m.es>
------------------------------------------------------------------------ 

INTRODUCTION:

  PRECCX is an infinite-lookahead compiler compiler for context
  dependent attributed grammars. Copyright P.T. Breuer, 1989-1994.

Compiler compilers aren't that easy to describe! You ought to have some
familiarity with the UNIX yacc utility, or GNU's bison under DOS, in
order to figure out what to do with PRECCX and why. This document will
genenerally assume that you know the basics, but still ... a compiler
compiler converts a high-level script into low level source code. The
script defines a language and the source code implements a parser for
that language. The parser may execute actions - in which case the
compiler compiler has compiled an interpreter - or it may build complex
structures such as further source code - in which case the compiler
compiler has compiled a compiler.

So a compiler compiler provides an easy path to the construction of a
complex utility. Just specify the language and some associated actions
and structures and let the compiler compiler build the source for you.

Why the new release of PRECCX?

This release consolidates development in the 2.4x line by merging in all
the changes, portability fixes and bugfixes made in 2.45[a-k] over several
months.  The biggest impactor is object-orientation. All internal buffers
and pointers are packed into a dynamic struct called "self".  And the
code will also compile and link under c++, as oft' requested.  See
history.txt and preccx.faq for more details of the changes.

          ================================

(README) CONTENTS:
          INTRODUCTION ........  What you just read.
          CONTENTS ............  Where you are.
          DIFFERENCES .........  For those who are upgrading -

          (Looking for a description? please read the manual page!)

          NEW .................  and those who are thinking of it.
          TESTING .............  A word on operating systems.
          INSTRUCTIONS ........  What to do next.

          ================================
            For those who are upgrading -
            -----------------------------

DIFFERENCES: 2.50 is primary source upward compatible with 2.4x but not
secondary source or binary compatible.  I.e.  you have to remake any
C codes that have been generated by an earlier version of preccx using
the new compiler compiler.

The 2.4x line was upwardly compatible with the popular 2.3x line
(pre-1994) except in the following respects.  The first three provisos
relate to the yacc-style $1, $2, $3, ...  numbered attribute references
required by 2.3x and which are now obsoleted in favour of $foo named
references:

1) use the -old switch while running precc over these old scripts;
2) don't use $0 or lower references;
3) don't use $$ (this is a _big_ change - see below);

4) you now should put { } tightly round actions. E.g.

   @ foo = bar {: gum :}

This is to avoid conflicts with C code ":"s in the gum part.

          ================================
Looking for a description?  Please read the manual page!  Use "nroff
-man" or install and use "man".  Check my home ftp site
ftp.comlab.ox.ac.uk for the many documents and examples in
pub/Programs/precc*.
 ---------------------------------------------------------

          ================================
       For those who are thinking of upgrading
       ---------------------------------------

NEW in 2.4x:
         1)  !{handler} foo bar
             ^^^^^^^^^^
                          ********* error handling

         2)  sum = term\x <'+'> term\y {: printf("%d",$x+$y); :}
                       ^^           ^^                ^^ ^^
                          ********* named attribute references

         3)  prod = term\x term\y {@ $x*$y @}
                                  ^^^^^^^^^^^
                          ********* inline attribute synthesis

1) The backtracking  error handler construct tells precc where to 
branch to in case of an  attempt to  backtrack  across  the !  mark.  
The handler parser  should  eat  tokens and branch to a standard  
parser when it thinks it has found something standard.

This is implemented extremely efficiently internally - no worries
about C stack buildup, so use with impunity.

2) The new attribute style has permitted the run-time attribute stack
to be dispensed with (see the manual). This saves RAM. The call_mode
parameter is now obsolete (it was anyway for users - the default was
never changed in practice). I think the style also looks better!

3) It is now generally impossible to make assignments to attributes
from within actions along yacc lines using {: $$=foo; :} because
attributes are now being built and used earlier: during the parse,
when they can be most useful, and this takes place before actions are
executed. So yacc-style writes to attributes from within actions have
no effect. You have to use the new {@ foo @} notation instead. 


The -old switch is an attempt to continue to support the yacc-style
$1, $2, $3, etc. attribute dereferences as far as possible. It
generates nasty code and it is preferable to convert scripts to the new
style of named attributes and dereferences instead! Note that there is
no longer support for the $$ yacc-style attribute target in actions.

          ================================
             A word on operating systems
             ---------------------------

TESTING: I have done much testing of 2.42/43 on HP-UX with c89, sunOS
UNIX and Linux UNIX with gcc and MSDOS with BorlandC/TurboC v2.0,
building multi-stage projects of various sizes.  See history.txt.
PRECCX is not certified for anything else but only because I do not have
direct access to anything else.  Reports say it seems to work on almost
any system with ANSI C, modulo the occasional renaming of include files.

          ================================
                  What to do next 
                  ---------------

INSTRUCTIONS: If you are using UNIX, then you have already unpacked the
source code, documentation, examples and makefiles (see the file
`filelist').  Now you should read INSTALL.  The instructions there will
tell you to configure by running the included `configure' script in the
src directory, then `make' and `make install'.  Then of course you have
to read the preccx.1 man pages.  That means, either `nroff -man preccx.1
|more' or `man preccx'.

If you don't read INSTALL but just go ahead and blindly type `make; make
install' in the top directory of the distribution (here) you might well
find that that works ;-), but I encourage you to take the reading route!

If you are using DOS then place all the distribution files in one
directory and run INSTALL.EXE.  Further instructions for DOS follow.

 -- Peter T. Breuer

------------------------------------------------------------------------
    This is the PRECCX distribution for DOS. Version 2.44.
------------------------------------------------------------------------

PRECCX is an infinite-lookahead compiler compiler for context dependent
grammars.

To install, either compile as for unix, but using a DOS version of MAKE
together with MAKEFILE.DOS and a DOS C compiler, or copy _all_ the files
in this directory or archive to a diskette or DOS directory and then run
INSTALL.EXE. The configuration data is held in the INSTALL.001/CFG file.

The choices you make during the INSTALL.EXE run cause various target
directories to be built and some of the .ZIP archives to be copied
across and `unzipped' to them.  If you don't believe me, use a virus
checker, or do the unpacking yourself.  PRECCX is packaged using
Info-ZIP's compression utility and the installation program uses UnZip
to read the archives.  Info-ZIP's software (Zip, UnZip and related
utilities) is free and can be obtained ubiquitously as source code or
executables at anonymous-ftp sites, including ftp.uu.net in directory
/pub/archiving/zip, and src.doc.ic.ac.uk in directory
/computing/systems/msdos/simtel/zip (for example).


The list of archived files is in PACKING.LST. This is the pattern:

README      = this file                 -> HOME    directory
INDEX       = this list                 -> HOME    directory
PACKING.LST = a more detailed list      -> HOME    directory

preccxx.zip = executables               -> BIN     directory
preccxl.zip = compiled libraries        -> LIB     directory
preccxd.zip = manuals                   -> MAN     directory
preccxi.zip = C header files            -> INCLUDE directory
preccxe.zip = examples                  -> EXAMPLE directory
preccxn.zip = life cycle documentation  -> DOC     directory
preccxs.zip = source code and makefiles -> SRC     directory

If automatic installation does not work, read INSTALL.  In fact, you
ought to read it anyway to see exactly what should have been installed.

After installation, you should run README.EXE in the manuals directory.
Then look at the example scripts & check that they compile.  See RUN in
the root directory for some very direct advice.

------------------------------------------------------------------------
Peter T. Breuer   <ptb@eng.cam.ac.uk,ptb@comlab.ox.ac.uk,ptb@dit.upm.es>

