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.