marpatcl_install_guide - Marpa/Tcl - The Installer's Guide
Welcome to Marpa/Tcl, a Tcl binding to the "libmarpa" parsing engine.
Please read the document Marpa/Tcl - Introduction to Marpa/Tcl, if you have not done so already. It provides an overview of the whole system.
This document is targeted at users of Marpa/Tcl with the goal of building its packages and applications for distribution, or their own use.
Please read Marpa/Tcl - How To Get The Sources first, if that was not done already. Here we assume that the sources are already available in a directory of your choice.
Developers building Marpa/Tcl with the intent of extending or modifying the packages and application should read Marpa/Tcl - The Developer's Guide as well.
A number of requisites must be installed before building and using Marpa/Tcl is possible. These are:
Jeffrey Kegler's libmarpa library. For details see Libmarpa.
The scripting language Tcl. For details see Tcl.
The critcl package (C embedding) for Tcl. For details see CriTcl.
Various packages from the Tcllib bundles for Tcl. For details see Tcllib.
The kettle application (Build tool) for Tcl. For details see Kettle.
This list assumes that the machine where Marpa/Tcl is to be installed is essentially clean. Of course, if parts of the dependencies listed below are already installed the associated steps can be skipped. It is still recommended to read their sections though, to validate that the dependencies they talk about are indeed installed.
This C library is the foundation of Marpa/Tcl, providing the parser engine we bind to.
The instructions for its installation, including the retrieval of its sources, can be found at http://jeffreykegler.github.io/Marpa-web-site/libmarpa.html.
As we are only interested in the library itself installation of the Marpa::R2 Perl binding is not necessary. Marpa/Tcl also comes with its own testsuite.
Regarding packages for the various Linux distributions which would make installation more convenient, I have currently only found/seen:
libmarpa-r2-perl is the Perl binding I mentioned above. Based on the set of installed files I believe that libmarpa is part of the shared library for the binding itself, and not installed as a separate binary.
As we are building a set of Tcl packages it should be pretty much obvious that a working Tcl installation is needed, and I will not belabor the point.
Out of the many use whatever you are comfortable with, as long as it provides Tcl 8.5, or higher.
This may be a Tcl installation provided by your operating system distribution, from a distribution-independent vendor, or built by yourself.
Myself, I used ActiveState's ActiveTcl 8.5 distribution during development of the binding, as I am most familiar with it.
(Disclosure: I, Andreas Kupries, worked for ActiveState, and maintained ActiveTcl and TclDevKit for them).
This distribution can be found at http://www.activestate.com/activetcl. Retrieve the archive of ActiveTcl 8.5 for your platform and install it as directed by ActiveState.
Assuming that ActiveTcl got installed I usually run the command
teacup update
to install all packages ActiveState provides, and the kitchensink, as the distribution itself usually contains only the most important set of packages. This ensures that the dependencies for CriTcl, and Marpa/Tcl are all present, and more.
If that is not your liking you have to read the sections for CriTcl, and Marpa/Tcl to determine the exact set of packages required, and install only these using
teacup install $packagename
Both teacup commands above assume that ActiveState's TEApot repository at http://teapot.activestate.com is in the list of repositories accessible to teacup. This is automatically ensured for the ActiveTcl distribution. Others may have to run
teacup archive add http://teapot.activestate.com
to make this happen.
For those wishing to build Tcl on their own, its sources can be found at
To use Marpa/Tcl a few packages found in the bundle Tcllib are required. These packages are:
debug
debug::caller
oo::util
lambda
try
fileutil
Assuming that ActiveTcl is installed, or some other Tcl installation with teacup available, these packages can be installed via
teacup install $packagename
The teacup command above assumes that ActiveState's TEApot repository at http://teapot.activestate.com is in the list of repositories accessible to teacup. This is automatically ensured for the ActiveTcl distribution. Others may have to run
teacup archive add http://teapot.activestate.com
to make this happen.
Now, for those wishing to install the packages from source, the fossil repository for the bundle can be found at https://core.tcl.tk/tcllib/.
Releases of Tcllib can be found there as well, or fossil can be used to check out specific revisions.
Tcllib comes with its own installation instructions. These will not be repeated here. If there are problems with its directions please file a bug against the Tcllib project at the above url, and not Marpa/Tcl.
To build Marpa/Tcl the tool critcl is required.
Marpa/Tcl's build system (based on Kettle) accepts it either as an application found in the PATH (be it script, starkit or starpack), or as a Tcl package available to the tclsh used to run their build & installation processes.
Marpa/Tcl requires version 3 or higher.
Releases of version 3 and higher, and the associated sources, can be found at http://andreas-kupries.github.com/critcl.
Any branch of the repository can be used (if not using the prebuild starkit or starpack), although the use of the stable branch master is recommended.
At the above url is also an explanation on how to build and install CriTcl, including a list of its dependencies.
Its instructions will not be repeated here. If there are problems with their directions please file a bug against the critcl project, and not Marpa/Tcl.
To build Marpa/Tcl the tool kettle is required.
Marpa/Tcl's build system requires it as an application found in the PATH.
Marpa/Tcl requires version 1 or higher.
Releases of this tool (and its associated package) can be found at http://core.tcl.tk/akupries/kettle. This is a fossil repository.
A mirror of the above repository can be found at https://chiselapp.com/user/andreas_kupries/repository/Kettle. Note that this mirror is also a conversion from Fossil to Git.
Use of either releases or of the head of the main branch is recommended. Usage of branches is strongly discouraged as these are used to work on experimental features and bugfixes of the tool. As such their stability is not guaranteed.
At the above url is also an explanation on how to build and install Kettle, including a list of its dependencies.
Its instructions will not be repeated here. If there are problems with their directions please file a bug against the Kettle project, and not Marpa/Tcl.
This section describes the actions required to install Marpa/Tcl on Unix systems (Linux, BSD, and related, including OS X). If you have to install Marpa/Tcl on a Windows machine see section Build & Installation (Windows) instead.
To install Marpa/Tcl simply run
/path/to/tclsh8.5 /path/to/marpatcl/build.tcl install
where "/path/to/tclsh8.5" is the tclsh of your Tcl installation, and "/path/to/marpatcl" the location of the Marpa/Tcl sources on your system.
This builds all packages and then places them in a directory where the tclsh8.5 will find them.
The build system provides a small GUI for those not comfortable with the command line. This GUI is accessible by invoking "build.tcl" without any arguments.
To get help about the methods of "build.tcl", and their complete syntax, invoke "build.tcl" with the argument help, i.e., like
/path/to/tclsh8.5 /path/to/marpa/tcl/build.tcl help
This section describes the actions required to install Marpa/Tcl on Windows(tm) systems. If you have to install Marpa/Tcl on a Unix machine (Linux, BSD, and related, including OS X) see section Build & Installation (Unix) instead.
To install Marpa/Tcl simply run
/path/to/tclsh8.5 /path/to/kettle -f /path/to/marpatcl/build.tcl install
where "/path/to/tclsh8.5" is the tclsh of your Tcl installation, "/path/to/kettle" is the installed kettle application, and "/path/to/marpatcl" the location of the Marpa/Tcl sources on your system.
This builds all packages and then places them in a directory where the tclsh8.5 will find them.
The above is written without assuming any associations from extensions (like ".tcl") to executables responsible for the files with that extension. Actually, given that "build.tcl" is technically a "kettle"-script, which in turn is a ".tcl"-script I am not sure if Windows is able to handle such a chain of interpreters. The command given above simply spells out the entire chain.
The build system provides a small GUI for those not comfortable with the command line. This GUI is accessible by invoking "build.tcl" without any arguments from the command line.
To get help about the methods of "build.tcl", and their complete syntax, invoke "build.tcl" with the argument help, i.e., like
/path/to/tclsh8.5 /path/to/kettle -f /path/to/marpatcl/build.tcl help
This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such at the Marpa/Tcl Tracker. Please report any ideas for enhancements you may have for either package and/or documentation as well.
aycock, character classes, context free grammar, document processing, earley, horspool, joop leo, lexing, libmarpa, nigel horspool, parsing, regex, table parsing
Copyright © 2015-present Andreas Kupries
Copyright © 2018-present Documentation, Andreas Kupries