On sourceforge there are a variety of Quex packages supporting the major operating systems and distributions at the time of this writing as they are: Microsoft Windows (tm), Mac OS (tm), and Linux (.deb and .rpm based distributions).
This section discusses the major ‘pillars’ of an installation. It is explains how to install quex from one of the source packages on an arbitrary platform. At the same time, it may provide first hints for troubleshooting. The pillars of a Quex installation are the following:
Before beginning the installation of quex, make sure that Python (http://www.python.org) is installed. Most linux distributions provide handy .rpm or .deb packages.
Do not install a Python version >= 3.0! Python 3.x is a language different from Python < 3.0. Quex is programmed towards version 2.6.
In order to verify that Python is installed you may open a console (cmd.exe, xterm or a shel/terminal under Unix). Then type python and the output should be similar to:
> python Python 2.6.4 (r264:75706, Jan 30 2010, 22:50:05) ... >>>
Type quit() to leave the shell. If you do not get this interactive python shell, then most likely the PATH variable does not contain the path where Python is installed. On the console review the setting of the PATH by:
C:\> echo %PATH%
on Windows, or:
> echo $PATH
on Unix. If Python’s path is not in the list, then add it. Consult your the documentation of your operating system for further instructions about how to do this.
Get a source distribution from quex.org or quex.sourceforge.net. That is, select a file with the ending ‘.tgz’, ‘.zip’, or ‘.7z’ from the download directory. Extract the files to a directory of your choice.
Quex knows about where it is installed through the environment variable QUEX_PATH. If you are using a Unix system and the bash-shell, add the following line to your .bashrc-file:
To do the same thing on Windows, go to Control Panel, System, Advanced, Environment Variables. Then add the variable QUEX_PATH with the value C:\Programs\Quex, provided that quex is installed there.
For clarity, the path must point to the place wher quex-exe.py is located.
The safest way to do this is to add the content of the QUEX_PATH variable to the PATH variable. Thus the systems will search for executables in quex’s installation directory. Or, on operating systems that can provide links, make a link:
> ln -s $QUEX_PATH/quex-exe.py $EXECUTABLE_PATH/quex
where $EXECUTABLE_PATH is a path where executables can be found by your system. On a Unix system an appropriate directory is:
To access this directory, you should be either root or use sudo. You can ensure executable rights with:
> chmod a+rx $QUEX_PATH/quex-exe.py > chmod a+rx /usr/local/bin/quex
On Windows, the file quex.bat should be copied into C:\WINDOWS\SYSTEM where most probably executable files can be found.
This is all for the installation of Quex. Your should now be able to type on the command line:
> quex --version
and get a result similar to:
Quex - Fast Universal Lexical Analyzer Generator Version 0.57.1 (C) 2006-2011 Frank-Rene Schaefer ABSOLUTELY NO WARRANTY
Note, that with the operating system installers there might be problems occuring with previous installations. Thus, when updating better better move any older installation to a place where the system can find them (e.g. in the trash can).
When compiling Quex-generated code the QUEX_PATH must be provided as an include path, i.e. you must add an -I option -I$QUEX_PATH on the command line or -I$(QUEX_PATH) in a Makefile.
In the sub directories of $QUEX_PATH/demo there are many examples of how to do that.
If you want to use character set conversion, you need to install one of the supported libraries–currently IBM’s ICU <http://icu-project.org/userguide/intro.html> or GNU IConv <http://www.gnu.org/software/libiconv/>[#f1]_.
That is all. Now, you should either copy the directories ./demo/* to a place where you want to work on it, or simply change directory to there. These directories contain sample applications 000, 001, $ldots$. Change to the directory of the sample applications and type make. If everything is setup properly, you will get your first quex-made lexical analyser executable in a matter of seconds.
It was reported that a certain development environment called ‘VisualStudio’ from a company called ‘Microsoft’ requires the path to python to be set explicitly. Development environments may have their own set of variables that need to be adapted.
The example applications depict easy ways to specify traditional lexical analysers, they show some special features of quex such as mode transitions, and more. Each demo-application deals with a particular feature of quex:
shows how to setup a lexical analyzer very quickly.
demonstrates basics on modes and mode transitions.
contains a sample application for an indentation based language.
implements a lexical analyzer handling UTF8 encoding. Quex creates an engine that relies on converters ICU and IConv. The converters are used to convert the incoming data stream to unicode. The internal engine still runs on plain unicode code points.
In contrast, directory demo/011 an example is shown how quex creates analyzer engines that do not need converters. The engine itself understands the codec and triggers on its code elements.
contains a setup to generate a lexical analyser for the ‘C’ language. Users are encouraged to submit other exciting examples of their language.
explains how to do lexical analysis with files that include other files.
contains an example that treats pseudo ambiguous post contexts (or, ‘dangerous trailing contexts) which are difficult to deal with by means of traditional lexical analyser generators.
examples showing pattern priorization between base and derived modes as well as applications of PRIORITY-MARK and DELETION.
shows how a quex generated lexer is linked to a bison generated parser.
shows how analyzers can be implemented for char and wchar_t string streams.
shows how to access the analyzer’s memory buffer directly. It also contains an example, stdinlexer.cpp, that shows how to parse the standard input (i.e. the cin or stdin stream).
provides an example of how to adapt the character encoding of the lexical analyzer engine without using converters. Example codecs are iso8859-7 and utf8.
gives an example of how to use multiple lexical analyzers in one single application.
contains a benchmark suite to measure the performance of the lexical analyzer. As an example a benchmark for a C-lexer is implemented. The suite can build lexical analyzers based on quex, but also as a comparison the same analyzers generated by flex and re2c.
The author of this document suggests that the user looks at these sample applications first before continuing with the remainder of this text. With the background of easy-to-use examples to serve as starting point for their own efforts, it should be natural to get a feeling for the ease of quex.
|||If you are glad to work on a Linux system, the probability that your distribution provides pre-configured installation packages for those libraries is very high. Nevertheless, there are also wellness packages for other operating systems.|