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 additionally
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.
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.
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 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
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 accessible
to
teacup. This is automatically ensured for the ActiveTcl
distribution. Others may have to run
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 accessible
to
teacup. This is automatically ensured for the ActiveTcl
distribution. Others may have to run
to make this happen.
Now, for those wishing to install the packages from source, the CVS repository
for the two bundles can be found at
https://sourceforge.net/projects/tcllib.
Releases of Tcllib can be found in the associated Files section, or CVS can be
used to check out the sub-project tcllib.
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 Critcl.
BUILD & INSTALLATION¶
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. The critcl application is written to use that executable as well,
and not search for it in 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.
On unix the same GUI is acessible 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
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.
> 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
>
Some explanations:
- •
- The example shows only the commands entered on the shell (and tclsh)
command line. Their responses are left out.
- •
- 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.
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
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.
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-2013 Andreas Kupries