Cocktail Toolbox

The Cocktail Toolbox is a set of programs for compiler construction. It contains the following tools:

Tool	Purpose
Rex	generator for lexical analyzers
Lark	LR(1) and LALR(2) parser generator with backtracking and predicates
Ell	LL(1) parser generator
Ast	generator for abstract syntax trees
Ag	generator for attribute evaluators
Puma	transformation of attributed trees using pattern matching

The development of the Cocktail Toolbox started around 1987 at the Forschungsstelle für Programmstrukturen an der Universität Karlsruhe, a subsidiary of GMD (Gesellschaft für Mathematik und Datenverarbeitung mbH). From 1994 until 2021 the Cocktail Toolbox was a commercial product of CoCoLab in Karlsruhe, Germany.

Compiler modules can be generated in the target languages C, C++, and Modula-2. The Cocktail Toolbox is implemented using Cocktail itself and in Modula-2. This version of Cocktail contains the original source code based on Modula-2.

If you want to modify the original source code of the Cocktail Toolbox, then this project is right for you. If you are just interested in a working copy, then the project cocktail is recommended.

Introduction

This document describes the source distribution of the Cocktail Toolbox for compiler construction and how to generate and install Cocktail from the sources. Most of the Cocktail tools are written in Cocktail itself and Modula-2. Therefore, a working copy of Cocktail and a Modula-2 to C translator called mtc2 are necessary to build Cocktail. Additionally, the support tools estra and mpp are used. Estra is a predecessor of the Cocktail tool puma for the transformation of trees and mpp is a preprocessor for Modula-2. Also, a C compiler and the following Unix utilities are needed: cat, sed, awk, unzip (or similar).

A build of Cocktail should be possible on every Unix operating system, on Windows and probably on other operating systems as well. The build process as described here has been executed successfully under the following operating systems:

SUSE Linux
SunOS 4.1.1
Debian Linux 8.9 (Jessie)
Arch Linux
Windows 10

Requirements

The following items are necessary for building and executing Cocktail:

• sources of the Cocktail tools (provided by this project)
• sources of the support tools: estra, mpp, mtc2 (provided by this project)
• executable copy of Cocktail (provided e. g. by the project cocktail)
• C compiler capable of generating 32 bit code
• utility programs: make/nmake, cat, sed, awk, unzip (or similar)

Note, the restriction to 32 bit code originates from the Modula-2 language and limitations in the Modula-2 to C translator mtc2. In some cases 64 bit code might work by chance. However, e. g. position independent code as generated by newer versions of gcc is known to fail.

Building Cocktail - Overview

Building of Cocktail is done from the command line. It consists of the following steps:

1. Clone or download and unpack the source code of Cocktail.

2. Compile and install the support tools estra, mpp, and mtc2.

3. Generate Modula-2 sources from the Cocktail sources (written in Cocktail and Modula-2) using the Cocktail tools and the support tools estra and mpp.

4. Convert the Modula-2 sources of Cocktail to C code using mtc2.

5. Compile the created C code.

6. Install the created binaries of the Cocktail tools.

Building Cocktail on Linux

Requirements

• C compiler capable of generating 32 bit code
• git
• executable copy of Cocktail (provided e. g. by the project cocktail)

Commands

The commands for building Cocktail on Linux are as follows:

1. Clone (or download and unpack) the source code of Cocktail:

   git clone https://github.com/cocolab8/cocktail-src.git
   cd cocktail-src
   

   Alternatively, you can download a zip archive from github and unpack:

   unzip cocktail-src-master.zip
   cd cocktail-src-master
   

2. Run config script:

   ./config CC="cc -m32"
   

3. Compile and install the support tools estra, mpp, and mtc2:

   The files in the directories */m2c contain obfuscated C source code.
   The files in the directories */src contain Modula-2 source code.

   make support
   make install_support DIR=$PWD
   PATH=$PWD/bin:$PATH
   

   The parameter DIR specifies the location where the support tools are installed. This should be a location where we have write access. Also, its subfolder bin should be added to the environment variable PATH.

4. Generate Modula-2 sources from the Cocktail sources (written in Cocktail and Modula-2) using the Cocktail tools and the support tools estra and mpp:

   This step generates Modula-2 source code in the directories */src.

   make sources
   

5. Convert the Modula-2 sources of Cocktail to C code using mtc2:

   This step converts the Modula-2 source files in the directories */src to C source code in the directories */m2c.

   make m2c
   

   You can ignore any warnings reported my mtc2.

6. Compile the created C code using a C compiler (in 32 bit mode):

   This step compiles the C source code in the directories */m2c.

   make
   

7. Install the created binaries of the Cocktail tools:

   make install DIR=...
   

   The tools can be installed at any place. This might require root (admin) privileges. For example:

   make install DIR=/usr/local
   

   The subfolder bin should be included in the environment variable PATH.

8. Optionally, test the Cocktail tools.

   make test DIR=/usr/local
   

9. Optionally, clean the file tree.

   make clean
   

Building Cocktail on Windows

Requirements

The following software must be available:

1. The following (Unix) utilities are needed:

   cat, sed, awk and unzip or 7z

   If not already available, the utilities cat, sed, and awk can be downloaded from sourceforge -> Packages.

   The package names and the file names are as follows:

   Package	File
   FileUtils	coreutils-5.3.0.exe
   Gawk	gawk-3.1.6-1-setup.exe
   Sed	sed-4.2.1-setup.exe

   These utilities can be installed for example in the folder

   C:\Program Files (x86)\gnuwin32
   

   Unfortunately, the first package above installs lots of superfluous programs. Actually, only cat.exe is needed from this package. All the others could be removed. In particular, this package installs dir.exe, link.exe, sort.exe, and date.exe, which clash with Windows utilities. These 3 programs should be removed or renamed in any case.

2. The utility unzip from the above location did not work for me. As a workaround, the program 7z can be used. If not already available, it can be downloaded from 7-zip.

   The program 7z1900.exe can be installed for example in the folder

   C:\Program Files (x86)\7-Zip
   

3. The previously installed utilities must be made available for command line use by extending the environment variable PATH by the following folders:

   C:\Program Files (x86)\gnuwin32\bin
   C:\Program Files (x86)\7-Zip
   

   On Windows 10 the environment variables can be manipulated e. g. here:

   Settings -> System -> Info -> System Properties -> Advanced -> Environment Variables -> User Variables -> Path

   or here:

   Settings -> System -> About -> Advanced System Settings -> Environment Variables -> User Variables -> Path

4. If not already available, install a C/C++ compiler. For example "Microsoft Visual Studio Express 2012 (Version 11)" including the "Microsoft C/C++ compiler (Version 17)" for 32 bit or "Microsoft Visual Studio 2022". These two have been tested. Other versions might work as well.

5. Enable the C/C++ compilers and utilities such as nmake for command line use, e. g.:

   "C:\Program Files (x86)\Microsoft Visual Studio 11.0\VC\vcvarsall.bat" x86
   

   or

   "C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\VsDevCmd" -arch=x86
   

6. Provide an executable copy of Cocktail, e. g. by installing the project cocktail.

Commands

The commands for building Cocktail on Windows from the command line are as follows:

1. Download a zip archive with the source code of Cocktail from github.

2. Unpack the source code archive of Cocktail:

   7z x cocktail-src-master.zip
   cd cocktail-src-master
   

3. Compile and install the support tools estra, mpp, and mtc2:

   The files in the folders *\m2c contain obfuscated C source code.
   The files in the folders *\src contain Modula-2 source code.

   set CT_DIR=C:\Program Files (x86)\Cocktail
   set PATH=%CT_DIR%\bin;%PATH%
   nmake /c /f Makefile.mvc support
   nmake /c /f Makefile.mvc install_support
   

   The support tools will be installed in the folder %CT_DIR%. This should be a folder where we have write access. The subfolder bin should be added temporarily to the environment variable PATH.

4. Generate Modula-2 sources from the Cocktail sources (written in Cocktail and Modula-2) using the Cocktail tools and the support tools estra and mpp:

   This step generates Modula-2 source code in the folders *\src.

   nmake /c /f Makefile.mvc sources
   

5. Convert the Modula-2 sources of Cocktail to C code using mtc2:

   This step converts the Modula-2 source files in the folders *\src to C source code in the folders *\m2c.

   nmake /c /f Makefile.mvc m2c
   

   You can ignore any warnings reported my mtc2.

6. Compile the created C code using a C compiler:

   This step compiles the C source code in the folders *\m2c.

   nmake /c /f Makefile.mvc compile
   

7. Install the created binaries of the Cocktail tools:

   The tools can be installed at any place. This might require admin privileges. For example:

   set CT_DIR=C:\Program Files (x86)\Cocktail
   nmake /c /f Makefile.mvc install
   

8. Define environment variables:

   set CT_DIR=C:\Program Files (x86)\Cocktail
   set PATH=%CT_DIR%\bin;%PATH%
   

   The definition of the environment variable CT_DIR is needed everytime Cocktail is used. Also, the subfolder bin of the installation location should be added to the environment variable PATH. These settings could be added permanently to the list of environment variables, for example.

9. Optionally, test the Cocktail tools:

   nmake /c /f Makefile.mvc test
   

10. Optionally, clean the file tree:

    nmake /c /f Makefile.mvc clean
    

Documentation

User manuals and other documentation in the formats PDF and plain text can be found in the directories doc.pdf and doc.txt.

The documentation of Cocktail is written for the Unix wordprocessor groff with me macros along with the support tools pic, tbl, and eqn. Therefore, the production of PDFs works probably under Linux, only. The input files for groff are in the directory doc.me. From these files formats such as Postscript, plain text, or PDF can be produced. The commands for word processing depend on the operating system. Under Linux the commands are:

    groff -P-g -U -pte -me file.me > file.ps             # Postscript in A4 format
    groff -P-g -U -pte -me -rletter=1 file.me > file.ps  # Postscript in letter format

    sed '/^\.PS$/,/^\.PE/d' < file.me | tbl | eqn -Tascii | groff -Tascii -U -me | \
       sed -e 's/.^H//g' -e 's/^[7|//g' -e 's/^[[6-9]//g' -e 's/^[//g' | \
       recode l1..l1/CR-LF > file.txt                    # plain text format

    ps2pdf file.ps file.pdf                              # PDF format