critcl_install_guide(3tcl) | C Runtime In Tcl (CriTcl) | critcl_install_guide(3tcl) |
critcl_install_guide - Critcl - The Installer's Guide
Welcome to the C Runtime In Tcl, CriTcl for short, a system to build C extension packages for Tcl on the fly, from C code embedded within Tcl scripts, for all who wish to make their code go faster.
The audience of this document is anyone wishing to build the packages, for either themselves, or others.
For a developer intending to extend or modify the packages we additionally provide
Please read Critcl - 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.
Before Critcl can be build and used a number of requisites must be installed. These are:
This list assumes that the machine where Critcl 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.
As we are building a Tcl package that 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, and Tk 8.5 or higher.
This may a Tcl installation provided by your operating system distribution, from a distribution-independent vendor, or built by yurself.
Myself, I used ActiveState's [http://www.activestate.com] ActiveTcl 8.5 distribution during development of the binding, as I am most familiar with it.
(Disclosure: I, Andreas Kupries, work for ActiveState, maintaining 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
If that is not to your liking you have to read the sections for Critcl 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
For those wishing to build Tcl/Tk on their own, their sources can be found at
To use Critcl a few packages found in the Tcllib bundle are required. These packages are:
And to accelerate this package, it is recommend to get and install one of
Assuming that ActiveTcl is installed, or some other Tcl installation with teacup available, most (not md5c) of 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
Now, for those wishing to install the packages from source, the fossil repository for the two bundles can be found at https://core.tcl.tk/tcllib and https://core.tcl.tk/tklib.
Releases of Tcllib and Tklib can be found there as well, or fossil can be used to check out specific revisions.
Tcl- and Tklib come with their own installation instructions. These will not be repeated here. If there are problems with their directions please file a bug against the Tcllib project at the above url, and not CriTcl.
To actually build packages based on critcl we need a working C compiler.
How to install such and all the associated header files, libraries, etc. is heavily platform- and system-dependent, and thus outside of the scope of this document. Note that I am willing to extend this section with links of interest to tutorials, howtos and references for the various platforms.
The important pieces of information are this:
Links of interest:
This section describes the actions required to install CriTcl on Unix systems (Linux, BSD, and related, including OS X). If you have to install CriTcl on a Windows machine see section Build & Installation (Windows) instead. To install Critcl simply run
/path/to/tclsh /path/to/critcl/build.tcl install
This builds all packages and then places them in a directory where the tclsh will find them.
It further creates a "critcl" application script and places it into the directory tclsh resides in, making it a sibling of that executable. Note that the installed critcl application is modified to use the chosen tclsh instead of searching for one on the PATH.
On Windows you can invoke the file "build.tcl" with a double-click. This will pop up a small graphical interface for entering the destination and performing the installation. This handling of a double-click is restricted to Windows only however.
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 argument help, i.e., like
/path/to/tclsh /path/to/critcl/build.tcl help
This section describes the actions required to install CriTcl on Windows(tm) systems. If you have to install CriTcl on a Unix machine (Linux, BSD, and related, including OS X) see section Build & Installation (Unix) instead. To install Critcl simply run
/path/to/tclsh /path/to/critcl/build.tcl install
This builds all packages and then places them in a directory where the tclsh will find them.
It further creates a "critcl" application script and places it into the directory tclsh resides in, making it a sibling of that executable.
Attention! Note that while the installed critcl application is modified to use the chosen tclsh instead of searching for one on the PATH this is useless for Windows, which associates executables with files through their extension.
Attention! The current installer does not put an extension on the critcl application, forcing users to either explicitly choose the tclsh to run the application, or manually rename the installed file to "critcl.tcl", if an association for ".tcl" is available, to either tclsh, or wish.
On Windows you can invoke the file "build.tcl" with a double-click. This will pop up a small graphical interface for entering the destination and performing the installation. This handling of a double-click is restricted to Windows only however.
This GUI is also 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 argument help, i.e., like
/path/to/tclsh /path/to/critcl/build.tcl help
With critcl installed it is now the time to try at least one of the examples distributed with it. This will also test if the installation was successful.
Below I show the steps to generate and then use the low- and high-level stack example packages. I am intentionally bypassing the "build.tcl" file the example is coming with, to show the use of critcl itself.
Some more explanations before running the example:
Also, on Windows(tm) this part of the example must be replaced with
/path/to/tclsh /path/to/critcl
Only if the installed application was manually renamed to "critcl.tcl" and the machine has an association for ".tcl" to either tclsh or wish then the "/path/to/tclsh" can be left out.
If any command throws an error, i.e. has a problem, then all following commands will run into some other error as well, as a consequence of the first problem.
> cd examples/stack
> /path/to/critcl -keep -cache B -pkg cstack.tcl
> /path/to/critcl -keep -cache B -pkg stackc.tcl
> tclsh
% lappend auto_path [pwd]/lib
% package require stackc
% join [info loaded] \n
% stackc S
% S push FOO
% S size
% S destroy
% exit
>
Jean Claude Wippler, Steve Landers, Andreas Kupries
This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report them at https://github.com/andreas-kupries/critcl/issues. Ideas for enhancements you may have for either package, application, and/or the documentation are also very welcome and should be reported at https://github.com/andreas-kupries/critcl/issues as well.
C code, Embedded C Code, code generator, compile & run, compiler, dynamic code generation, dynamic compilation, generate package, linker, on demand compilation, on-the-fly compilation
Glueing/Embedded C code
Copyright (c) Jean-Claude Wippler Copyright (c) Steve Landers Copyright (c) 2011-2015 Andreas Kupries
3.1.17 | doc |