Compiler - a Parser Generator Program (CPG)
Version 2.1
Open Source Distribution Notes
01/08/2007
Chuck Fayle

CPG is an application for specifying formal language grammars and computing,
generating, and simulating the corresponding automatons.  It has features
which significantly extend those of the lex/yacc and flex/bison tools
available on UNIX and Linux operating systems.  The software is distributed
under the terms of the GNU General Public License as specified in the file
gpl.txt included with the source code distribution.

The version 2.1 release is an update of the software to support new versions
of the Trolltech Qt library and GNU C++ compiler.  There is also a new
distribution for Windows XP.  The update relies on the Qt3Support Module for
the GUI program.  The programs have been developed and tested using Qt 4.x.x
and GNU C++ 4.x.x versions of libraries and tools.

There are a number of GUI restrictions and differences that remain until a
full conversion to the Qt4 interface can be completed:

* Only one grammar file can be open at a time.
* GUI Framework mode is set for multiple child document windows.
* Minor differences in window and control attribute rendering and inheritance.

The command line program is functionally unchanged.

New features have been added to the parser drivers to support C preprocessor
style conditional compilation and file inclusion mechanisms directly in the
lexical stage.  The 'calculate' example included demonstrates the features and
can be used generically for new applications.

**** Documentation ****

A user guide in .pdf format is included with the distribution.  Also included
is a document which lists the configurable features of the application
framework.  Read the supplementary notes at the end of this file.

**** Building the Application for Linux ****

The source code distribution file is cpg_linux_2_1.tar.gz.  The source files
are extracted into directories named 'cpg', 'calculate', and 'misc'.

The application is built using a gmake file that requires two environment
variables for locating the X11 distribution and the Qt object library.
The environment variables which must be set and exported are 

1) X11DIR = X11R6 distribution root directory ( example: /usr/X11R6 )
2) QTDIR  = Qt object library root directory  ( example: /usr/lib/qt4 )

Note that the gmake file is setup to use a shared Qt object library that has
been built to support threading and the Standard Template Library using the
-thread and -stl configure options respectively.  The application uses the
STL.

All other include files, libraries, compiler, and linker required are
standard components of most current Linux operating systems, and the
default search paths for the compiler and linker should locate the items.
The build should work with Qt library versions 4.x.x and GNU C++
versions 4.x.x.

Type 'make' in the 'cpg' source code directory to build the
application.  Two binary executables are built by the gmake file.

1) compiler - the Qt based GUI application
2) cpgcmd   - command line executable

The binary executables are located in the 'obj' subdirectory of the 'cpg'
source code directory after the build is complete.  The command line
executable 'cpgcmd' accepts the same input files as 'compiler' and can be
used in automated build systems.  The 'cpgcmd' executable is not dependent
on the Qt object library.

**** Building the Application for Windows XP ****

The source code distribution files are cpg_windowsxp_2_1.tar.gz and
cpg_windowsxp_2_1.zip.  Each file has the same contents.  The source
files are extracted into directories named 'cpg', 'cmd', 'calculate',
and 'misc'.

The Windows XP version is build using the MinGW package installed during the
installation of the Qt library for Windows XP.  Use the console window
configured during the Qt installation for the correct build paths.

In the 'cpg' source code directory perform the following build steps:

1) qmake -project
2) At the top of the 'cpg.pro' file add to the macro definitions the macro:

   QT += qt3support

3) qmake -makefile
4) make

In the 'cmd' source code directory perform the following build steps:

1) qmake -project
2) qmake -makefile
3) make

After these steps the executables are located in the 'release' subdirectory
of 'cpg' and 'cmd'.

**** Testing the Application ****

The 'calculate' directory contains an example which illustrates features in
the parser drivers for implementation of conditional compilation and
file inclusion directives directly in the lexical stage.  To build the
'calculate' application perform the following steps:

1) Execute 'compiler',  open the 'calculate.grammar' file.
2) Select menu item 'Parser' -> 'Calculate', click 'Calculate', 'Close'.
3) Select menu item 'Parser' -> 'Error Entries', click 'Calculate', 'Close'.
4) Select menu item 'Parser' -> 'Unit Rules', click 'Calculate', 'Close'.
5) Select menu item 'Parser' -> 'Generate Code'.
6) Set the 'Code Directory' to the 'parser' subdirectory of 'calculate'.
7) Click 'Generate', 'Close'.
8) Copy the *.h and *.cpp files in 'calculate' to the 'parser' subdirectory.
9) Change directory to 'parser'.
10) For Linux execute make.
11) For Windows execute qmake -project; qmake -makefile; make.

The 'grammar' subdirectory of the 'cpg' source code directory contains
files with the extension '.grammar'.  The '.grammar' files contain grammar
and code generation specifications for a number of parsers that are built
into the application itself.  Make a copy of the 'grammar' directory and
open the '.grammar' files with the 'compiler' GUI application for testing
and demonstration.

For the 'option.grammar' parser use an '.option' file located in the 'misc'
subdirectory for input to the simulator.  The '.option' files contain
application framework configuration options that control the GUI layout
and attributes.

For the 'regexp.grammar' parser use any regular expression text
that conforms to the user guide regular expression specifications for input
to the simulator.  The 'misc' subdirectory contains the 'regexp.input' file
which specifies a regular expression for a floating point operand.

In the 'misc' subdirectory the 'precedence.grammar' example illustrates
precedence specifications and error token synchronization processing.
Also in 'misc' the 'context.grammar' example illustrates regular expression
start contexts.

**** Supplementary Notes ****

Some addendum notes for the user guide.

Essential Error Entry Calculations:
These calculations are compute intensive in both time and memory, the exact
calculation typically much more so than the approximate.  When performing
these calculations for grammars with over 100 rules it may be useful to run
a monitor application.

Code Generation:
The code generation dialog has changed as follows:
1) 'Lexical Base Name' edit field has been changed to 'Lexical Prefix Name'
2) 'Parser Base Name' edit field has been changed to 'Parser Prefix Name'
3) 'Base Class Prefix Name' edit field has been added
4) 'Generate Base And Stack Classes' check box has been added

The 'Lexical Prefix Name' edit field specifies the identifier prefix string
for the derived lexical driver class.  The 'Parser Base Name' edit field
specifies the identifier prefix string for the derived parser driver class.
If the 'Generate Base And Stack Classes' check box is checked then driver
base classes and a stack structure are generated.  If not then the default
versions in the CPG source code directory are used.  When the box is checked
the 'Base Class Prefix Name' edit field specifies the identifier prefix
string for the lexical driver base classes, the parser driver base class,
and the stack structure.  These code generation parameters can be used to
generate multiple parsers with separate class namespaces that utilize either
a common or separate parsing stack structure definitions.  This simplifies
integrating multiple parsers into a single compiled application.

Also, the generated files include files from the CPG source code so you must
add the root CPG source code directory to the include file search path for
builds that incorporate the generated code.

For tty test application generation the Makefile created uses an environment
variable 'CPG_DIR' to specify the root CPG source code directory and must be
set before invoking gmake.
