critcl_install_guide(n) C Runtime In Tcl (CriTcl) critcl_install_guide(n)______________________________________________________________________________NAME
critcl_install_guide - Critcl - The Installer's Guide
DESCRIPTION
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 addition‐
ally provide
[1] Critcl - License.
[2] Critcl - The Developer's Guide.
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.
REQUISITES
Before Critcl can be build and used a number of requisites must be
installed. These are:
[1] The scripting language Tcl. For details see Tcl.
[2] Various packages from the Tcllib bundle for Tcl. For details
see Tcllib.
[3] A working C compiler and development environment.
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 depen‐
dencies they talk about are indeed installed.
TCL
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 distribu‐
tion, 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
to install all packages ActiveState provides, and the kitchensink, as
the distribution itself usually contains only the ost important set of
packages. This ensures that the dependencies for Critcl are all
present, and more.
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 acces‐
sible to teacup. This is automatically ensured for the ActiveTcl dis‐
tribution. Others may have to run
teacup archive add http://teapot.activestate.com
to make this happen.
For those wishing to build Tcl/Tk on their own, their sources can be
found at
Tcl http://core.tcl.tk/tcl/
Tk http://core.tcl.tk/tk/
TCLLIB
To use Critcl a few packages found in the Tcllib bundle are required.
These packages are:
[1] cmdline
[2] md5.
And to accelerate this package, it is recommend to get and
install one of
[1] tcllibc
[2] md5c
[3] Trf
The system will work without them, but can become quite slow,
especially when handling large code blocks.
[3] snit
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 acces‐
sible to teacup. This is automatically ensured for the ActiveTcl dis‐
tribution. 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 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.
C COMPILER
To actually build packages based on critcl we need a working C com‐
piler.
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 var‐
ious platforms.
The important pieces of information are this:
[1] The path to the C compiler binary must be found in the environ‐
ment variable PATH, for critcl to find it.
[2] On Windows(tm) the environment variable LIB must be present and
contain the paths of the directories holding Microsoft's
libraries. The standard critcl configuration for this platform
searches these paths to fine-tune its settings based on avail‐
able libraries and compiler version.
Links of interest:
http://www.tldp.org/HOWTO/HOWTO-INDEX/programming.html
BUILD & INSTALLATION INSTRUCTIONS
BUILD & INSTALLATION (UNIX)
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
where "/path/to/tclsh" is the tclsh of your Tcl installation, and
"/path/to/critcl" the location of the Critcl sources on your system.
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 cho‐
sen 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 destina‐
tion 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" with‐
out any arguments.
To get help about the methods of "build.tcl", and their complete syn‐
tax, invoke "build.tcl" with argument help, i.e., like
/path/to/tclsh /path/to/critcl/build.tcl help
BUILD & INSTALLATION (WINDOWS)
This section describes the actions required to install CriTcl on Win‐
dows(tm) systems. If you have to install CriTcl on a Unix machine
(Linux, BSD, and related, including OS X) see section Build & Installa‐
tion (Unix) instead. To install Critcl simply run
/path/to/tclsh /path/to/critcl/build.tcl install
where "/path/to/tclsh" is the tclsh of your Tcl installation, and
"/path/to/critcl" the location of the Critcl sources on your system.
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 destina‐
tion 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 argu‐
ments.
To get help about the methods of "build.tcl", and their complete syn‐
tax, invoke "build.tcl" with argument help, i.e., like
/path/to/tclsh /path/to/critcl/build.tcl help
FIRST USE, TESTING THE INSTALLATION
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:
· Here "path/to/critcl" is the path to the installed critcl appli‐
cation, not the critcl source directory.
Also, on Windows(tm) this part of the example must be replaced
with
/path/to/tclsh /path/to/critcl
as the installed application has no extension and thus Windows
will not know how to execute the script.
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.
· The example shows only the commands entered on the shell (and
tclsh) command line. Their responses are 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.
· Use of option -keep causes critcl to leave the generated .c
files behind, for edification. Normally this happens only in
case of trouble.
· Use of option -cache redirects the location of the directory to
hold generated and build files to a local directory with a known
name, for an easy look after.
· Both cstack and stackc have to use the same -cache so that
stackc will find the stub table headers exported by cstack.
> 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
>
AUTHORS
Jean Claude Wippler, Steve Landers, Andreas Kupries
BUGS, IDEAS, FEEDBACK
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 enhance‐
ments you may have for either package, application, and/or the documen‐
tation are also very welcome and should be reported at
https://github.com/andreas-kupries/critcl/issues as well.
KEYWORDS
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
CATEGORY
Glueing/Embedded C code
COPYRIGHT
Copyright (c) Jean-Claude Wippler
Copyright (c) Steve Landers
Copyright (c) 2011-2015 Andreas Kupries
doc 3.1.15 critcl_install_guide(n)