CocoR/Readme.txt

This directory and its subdirectories contain the sources of Coco/R itself,
and also source code for various implementations of the compiler-specific
module FileIO used by Coco/R itself for I/O, and also, in many cases, by
the applications it produces.

Coco/R can be recompiled and bootstrapped from these sources - but PLEASE
BE CAREFUL!

Recompiling Coco/R
==================

To do so you are advised to create a working directory, copy all of the
files from this directory to it, and then copy all the files from the
subdirectory specific to your compiler.  For example, assuming you have the
XDS compiler (used here for illustration only):

     MD C:\WORK
     CD C:\WORK
     COPY C:\COCO\SOURCES\*.*
     COPY C:\COCO\SOURCES\XDSISO\*.*
     SET CRFRAMES=C:\COCO\FRAMES

(The "traditional" FileIO-based frame files must be used).

followed by

     XC =m CR

which will produce a new executable CR.EXE that you might rename to
COCOR.EXE when you are satisfied.

Note that some compilers will require you to choose between various memory
models, and may provide various optimization options that we cannot discuss
here.  For example, the StonyBrook 16 bit DOS compiler require you to use a
large data model.

Some compilers _require_ FORWARD declarations to be generated before they
will accept the code generated by Coco/R, others require that no such
directives be present.  The $M pragma (or -m command line option) will
suppress the generation of the FORWARD declarations (or, more honestly,
will comment them out).  The XDS and JPI compilers require that they be
present.

Coco/R itself makes use of 32-bit integers.  This should be handled
automagically by the appropriate definition of the INT32 type in
FileIO.DEF.

Modifying and bootstrapping Coco/R
==================================

Executing

      COCOR CR.ATG

will cause Coco to regenerate the parser (CRP), scanner (CRS) and main module
(CR) from the attribute grammar CR.ATG.

Thus, if you wish, you can modify CR.ATG and/or CR.FRM and subtly modify
the behaviour od Coco/R, or he form of the grammars that it will accept.
For example, you might want to add to the possible command line
options/pragmas, or modify Coco/R so that it suppresses the generation of
FORWARD declarations in the parser, or produce error messages in a
different format.

It is recommended that if you want to experiment with this, that you work
in a very different directory from the one in which you have filed the
original sources, lest you erase valuable original files.

Table size limitations
======================

The symbol tables used internally by Coco/R make use of fixed length arrays
- always a rather dangerous thing to do.  The dimensions of these arrays
have been chosen to ensure that the data segments for the modules will
remain within the limits imposed by MS-DOS system compilers that typically
impose a 64K limit on structures.  The limits can be extended for compilers
that allow this (such as 32 bit compilers) by editing CRT.DEF and CRT.MOD
appropriately, and recompiling Coco/R.  This may have to be done if a user
wishes to handle large grammars with many productions, for example.

Alternative versions of Coco/R
==============================

CRQ.FRM and CR.FRM are alternative compiler frame files.  They produce the
main driver routines CR.MOD and CRQ.MOD.  The first of these is the
"classic" Coco/R driver program; CRQ is an alternative that produces error
messages in a format that can be used to interface easily to various
editors that provide for constructing IDE environments.  By simply renaming
CRQ.FRM as CR.FRM and recompiling Coco/R you can easily generate this
"editor oriented" version.

=END=