Provided by: critcl_3.1.9-1build1_all bug

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

                  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 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/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

                  teacup archive add http://teapot.activestate.com

       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