Provided by: critcl_3.1.17+dfsg-1_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.

       [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 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 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 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:

       [1]    The path to the C compiler binary must be found in the environment  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 available
              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 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

   BUILD & INSTALLATION (WINDOWS)
       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

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

   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  application,  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  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-2015 Andreas Kupries