critcl_install_guide(3tcl)

📦 version 3.1.18.1, in debian bookworm, ubuntu jammy, ubuntu noble

💖 critcl_install_guide — Critcl, the Installer's Guide 💖

okay bestie, welcome to critcl_install_guide(3tcl), aka the page where we get CriTcl (that's C Runtime In Tcl, the manual name, iykyk) onto your machine and actually working. grab a snack, this is a long one, but we're doing it together 🫶

✨ DESCRIPTION ✨

So, C Runtime In Tcl, or CriTcl, is a whole system for compiling C code that's embedded inside Tcl, like, on the fly. Then it either loads the resulting objects straight into Tcl so you can use them immediately, or it packages them up for distribution. The whole point? Speed. You rewrite the routines that are being performance bottlenecks in C, and suddenly everything slaps. 🔥

The audience for this doc is literally anyone who wants to build the packages — for themselves, or for other people. No gatekeeping here.

If you're a developer who wants to extend or modify the packages, we also have, additionally:

  1. Critcl - License.
  2. Critcl - The Developer's Guide.

Please go read Critcl - How To Get The Sources first if you haven't already, bestie. From here on out we're assuming the sources are already sitting in a directory of your choice. 💅

🎀 REQUISITES 🎀

Before Critcl can be built and used, a few requisites have to 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 the machine where Critcl is to be installed is essentially clean. But of course, if parts of the dependencies listed below are already installed, the associated steps can be skipped. Still recommended to read their sections though, so you can validate that the dependencies they talk about are actually installed. Vibe check your system, basically. ✅

🐚 TCL

We're building a Tcl package, so like, it's pretty obvious a working Tcl installation is needed, and I will not belabor the point. (iconic restraint of me honestly)

Out of the many available, use whatever you're comfortable with, as long as it provides Tcl 8.5, or higher, and Tk 8.5 or higher.

This may be a Tcl installation provided by your operating system distribution, from a distribution-independent vendor, or built by yourself. All valid.

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. keeping it transparent bestie 💖)

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 most important set of packages. This ensures that the dependencies for Critcl are all present, and more. Maximum coverage, no missing pieces. ✨

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

📚 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 recommended 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. so like, it still works, but it's giving dial-up energy without them 😭

  1. 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. Time-travel privileges, lowkey. ⭐

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. Like, respectfully, wrong inbox bestie 🙈

🔧 C COMPILER

To actually build packages based on critcl we need a working C compiler. no cap, you cannot skip this one.

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. (an open invitation, fr fr 💜)

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.
⚠️ heads up bestie: those two env vars are not optional vibes. PATH needs the compiler, and on Windows LIB needs Microsoft's library directories, or the standard critcl config can't fine-tune itself. 👑

Links of interest:

http://www.tldp.org/HOWTO/HOWTO-INDEX/programming.html

…and that's where part 1 wraps, but we are NOT done, more parts follow so don't go anywhere 💅✨

🛠️ BUILD & INSTALLATION INSTRUCTIONS 🛠️

💻 BUILD & INSTALLATION (UNIX) 💻

okay bestie so this bit is literally just "how do I get CriTcl onto a Unix machine" — like Linux, BSD, and the whole related crew, OS X included. If you're on a Windows box instead, skip down to the Build & Installation (Windows) section, mwah. 💖

To install Critcl you literally just 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" is the location of the Critcl sources on your system. No cap. ✨

This builds all the packages and then places them in a directory where the tclsh will find them. Iconic behaviour honestly.

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. Periodt. 💅

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. Bestie-friendly UI, we love to see it. 🫶

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. Vibe check time, bestie. ✨

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. Main character energy fr fr. 👑

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. iykyk 💅
> 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. We're nice, we promise. 🫶

🔑 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 (c) Jean-Claude Wippler

Copyright (c) Steve Landers

Copyright (c) 2011-2018 Andreas Kupries

okay bestie that's literally the whole install guide, you're so ready to compile and run. this was doc version 3.1.18.1 of critcl_install_guide(3tcl), and it's serving source-file realness. go forth and slay your C-in-Tcl adventures 💅✨🦋

📦 where this page comes from