Ubuntu Manpage: critcl_install_guide - Critcl

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

COPYRIGHT

       Copyright (c) Jean-Claude Wippler
       Copyright (c) Steve Landers
       Copyright (c) 2011-2013 Andreas Kupries