plucky (3) critcl_howto_install.3tcl.gz

Provided by: critcl_3.3.1+dfsg-1_amd64 bug

NAME

       critcl_howto_install - How To Install CriTcl

DESCRIPTION

       Be  welcome  to the C Runtime In Tcl (short: CriTcl), a system for embedding and using C code from within
       Tcl [http://core.tcl-lang.org/tcl] scripts.

       CriTcl is installed in four major steps:

       [1]    Install The Requisites

       [2]    Follow the instructions on How To Get The CriTcl Sources

       [3]    Install The CriTcl Packages

       [4]    Test The Installation

       It is now possible to follow the instructions on How To Use CriTcl.

INSTALL THE REQUISITES

       This major step breaks down into three minor steps:

       [1]    Install A Working C Compiler and development environment.

       [2]    Install A Working Tcl Shell

       [3]    Install Supporting Tcl Packages

   INSTALL A WORKING C COMPILER
       While CriTcl requires a working C compiler to both install itself, and to process  CriTcl-based  packages
       installing such is very much out of scope for this document.

       Please follow the instructions for the platform and system CriTcl is to be installed on.

       The important pieces of information are this:

       [1]    The  path  to  the  directory containing the C compiler binary has to be listed in the environment
              variable PATH, for CriTcl to find it.

       [2]    On Windows(tm) the environment variable LIB has to  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

   INSTALL A WORKING TCL SHELL
       That a working installation of CriTcl will  require  a  working  installation  of  Tcl  [http://core.tcl-
       lang.org/tcl] should be obvious.

       Installing Tcl however is out of scope here, same as for installing a working C compiler.

       There  are  too  many  options,  starting  from  building it from scratch [http://core.tcl-lang.org/tcl],
       installing     what     is     provided     by     the     platform's     package     manager     (zypper
       [https://en.opensuse.org/Portal:Zypper],    yum    [https://access.redhat.com/solutions/9934],    apt-get
       [https://help.ubuntu.com/community/AptGet/Howto],  and  more),  to  using  some   vendor's   distribution
       [https://core.tcl-lang.org/dist.html].

       A single piece of advice however.

       While CriTcl currently supports running on Tcl 8.4 and higher, and the creation of packages for the same,
       the last release for this version was in 2013 (9 years ago at the time of writing). Similarly,  the  last
       release for Tcl 8.5 was in 2016 (6 years ago). Both are official end of life.

       Given this I recommend to install and use Tcl 8.6.

   INSTALL SUPPORTING TCL PACKAGES
       The implementation of CriTcl uses and depends on

       [1]    cmdline

       Depending  on how Tcl was installed this package may be available already without action, or not.  Invoke
       the command

                  echo 'puts [package require cmdline]' | tclsh

       to check if the package is present or not. If it is present then its version number will be printed, else
       the error message can't find package cmdline or similar.

       If it is not present install the package as per the instructions for the chosen Tcl installation.

       Note,  the  package  cmdline  may  not  exist as its own installable package. In such a case check if the
       chosen Tcl installation provides a tcllib package and install that. This should install all the  packages
       in the Tcllib bundle, including cmdline.

       As  a last fallback, go to Tclib [http://core.tcl-lang.org/tcllib] and follow the instructions to install
       the bundle from scratch.

INSTALL THE CRITCL PACKAGES

       Note that this step has different instructions dependent on the platform CriTcl is to be installed on. In
       other words, only one of the sub sections applies, the other can be ignored.

   INSTALL ON UNIX
       This section offers instructions for installing CriTcl on various kinds of Unix and Unix-related systems,
       i.e. Linux, the various BSDs, etc. It especially covers Mac OS X as well.

       Use the instructions in section Install On Windows when installing on a Windows platform and not using  a
       unix-like   environment   as   provided   by   tools   like   MinGW  [https://www.mingw-w64.org],  CygWin
       [https://www.cygwin.com/],       Git       For       Windows       [https://gitforwindows.org],       WSL
       [https://docs.microsoft.com/en-us/windows/wsl/faq], etc.

       [1]    Change  the  working  directory  to  the  top  level  directory of the CriTcl checkout obtained by
              following the instructions of How To Get The CriTcl Sources.

       [2]    Verify that the file "build.tcl" is marked executable. Make it executable if it is not.

       [3]    Invoke

               ./build.tcl install

       to

              Attention This command uses default locations for the placement of  the  critcl  application,  the
              various packages, and header files.

       [4]    Invoke

               ./build.tcl dirs

       to     performing the installation.

       [5]    Use  the  options  listed  below to change the paths used for installation as desired. This is the
              same method as with configure based packages.

              --prefix path
                     Base path for non-package files.

              --include-dir path
                     Destination path for header files.

              --exec-prefix path
                     Base path for applications and packages.

              --bin-dir path
                     Destination path for applications.

              --lib-dir path
                     Destination path for packages.

              These options are especially necessary in all environments  not  using  the  semi-standard  "bin",
              "lib", "include" locations from configure.

              As  an  example  of  such  environments,  Ubuntu  (and  possibly Debian) expect Tcl packages to be
              installed into the "/usr/share/tcltk" directory, therefore requiring the use of

              --lib-dir /usr/share/tcltk

       for

       Note that this guide neither covers the details of the install method, nor does it cover any of the other
       methods  available through the build.tcl tool of CriTcl.  These can be found in the CriTcl build.tcl Tool
       Reference.

   INSTALL ON WINDOWS
       This section offers instructions for installing CriTcl on a Windows (tm) host.  Note that environments as
       provided  by  tools  like  MinGW  [https://www.mingw-w64.org],  CygWin [https://www.cygwin.com/], Git For
       Windows [https://gitforwindows.org],  WSL  [https://docs.microsoft.com/en-us/windows/wsl/faq],  etc.  are
       classed as Unix-like, and the instructions in section Install On Unix apply.

       [1]    In  a  DOS  box,  change  the  working directory to the top level directory of the CriTcl checkout
              obtained by following the instructions of How To Get The CriTcl Sources.

       [2]    In the same DOS box, invoke

               tclsh.exe ./build.tcl install

       to     the installation.

              Attention This command uses default locations for the placement of  the  critcl  application,  the
              various packages, and header files.

       [3]    Invoke

               tclsh.exe ./build.tcl dirs

       to     actually performing the installation.

       [4]    Use  the  options  listed  below to change the paths used for installation as desired. This is the
              same method as with configure based packages.

              --prefix path
                     Base path for non-package files.

              --include-dir path
                     Destination path for header files.

              --exec-prefix path
                     Base path for applications and packages.

              --bin-dir path
                     Destination path for applications.

              --lib-dir path
                     Destination path for packages.

       Attention! The current installer does not put an extension on the critcl application. This  forces  users
       to  either  explicitly  choose the tclsh to run the application, or manually rename the installed file to
       "critcl.tcl". The latter assumes that an association for ".tcl" is available, to either tclsh, or wish.

       Note that this guide neither covers the details of the install method, nor does it cover any of the other
       methods  available through the build.tcl tool of CriTcl.  These can be found in the CriTcl build.tcl Tool
       Reference.

TEST THE INSTALLATION

       Installing CriTcl contains an implicit test of its functionality.

       One of its operation modes uses the MD5 hash internally to generate unique ids for sources, as a means of
       detecting  changes. To make generation of such hashes fast a CriTcl-based package for MD5 is installed as
       part of the main installation process.

       In other words, after installing the core packages of CriTcl this partial installation is used  to  build
       the rest.

       This  is  possible  because  building a package from CriTcl-based sources is the operation mode not using
       MD5, therefore there is no circular dependency.

       For our purposes this however is also a self-test of the system, verifying that the core of CriTcl works,
       as well as the C compiler.

       For additional testing simply move on to section The First Package of the guide on How To Use CriTcl.

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, calling C code from Tcl, 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 (c) Jean-Claude Wippler
       Copyright (c) Steve Landers
       Copyright (c) 2011-2024 Andreas Kupries