Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 di-
       rectory of your choice.

REQUISITES
       Before  Critcl can be build and used a number of	requisites must	be in-
       stalled.	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 Ac-
       tiveTcl 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  in-
	      stall 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 in-
       stalled 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  li-
	      braries.	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  in-
       stall  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 ex-
       amples 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:

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

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

       o      Use  of  option  -keep  causes  critcl to	leave the generated .c
	      files behind, for	edification. Normally  this  happens  only  in
	      case of trouble.

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

       o      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/an-
       dreas-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-ku-
       pries/critcl/issues as well.

KEYWORDS
       C  code,	 Embedded C Code, code generator, compile & run, compiler, dy-
       namic 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)

NAME | DESCRIPTION | REQUISITES | BUILD & INSTALLATION INSTRUCTIONS | AUTHORS | BUGS, IDEAS, FEEDBACK | KEYWORDS | CATEGORY | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=critcl_installer&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help