critcl(1)

📦 version 3.3.1, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 NAME 💖

critcl — CriTcl Application Reference 🌸

✨ SYNOPSIS ✨

critcl ?option...? ?file...?

🦋 DESCRIPTION 🦋

okay bestie, be welcome to the C Runtime In Tcl (short: CriTcl), the whole system for embedding and using C code from inside your Tcl scripts (peep http://core.tcl-lang.org/tcl). ✨

This document is the reference manpage for the critcl command, periodt. Who's it for? The people who have to build packages using critcl for deployment. 👑

And if you need an overview of the whole system instead, please go read the Introduction To CriTcl. 💜

This application resides in the Application Layer of CriTcl, iykyk:

*================*
|Applications    |
| critcl         |
| critcl::app    |
*================*

+----------------+
|Core Packages   |
| critcl         |
| critcl::util   |
+----------------+

+----------------+
|Support Packages|
| stubs::*       |
| md5, platform  |
|  ...           |
+----------------+

The application supports the following general command line:

critcl ?option...? ?file...?

The exact set of options supported, their meaning, and interaction is detailed in section Application Options below 👇. For a larger set of examples please see section "Building CriTcl Packages" in the document about Using CriTcl. 📚

💅 APPLICATION OPTIONS 💅

The following options are understood:

-v, --version — Print the version to stdout and exit. bye bestie 👋
-I path — Arranges for the compiler to search path for headers. Uses of this option are cumulative (stack 'em up 🥞).

-L path — Arranges for the linker to search path. Uses of this option are cumulative too.

-cache path — Sets path as the directory to use as the result cache. The default is "~/.critcl/<platform>", or "~/.critcl/<pid>.<epoch>" when generating a package. See option -pkg, below. 🗂️

-clean — Arranges for all files and directories in the result cache to be deleted before compilation begins. 🧼

-config path — Provides a custom configuration file. By default a configuration included in the system core is used. When specified multiple times the last value is used.

-debug mode — Activates one of the following debugging modes:
- memory — Track and report memory allocations made by the Tcl core.
- symbols — Compile all ".c" files with debugging symbols.
- all — Both memory and symbols.

-disable name — Sets the value of the custom build configuration option name to false. It is equivalent to "-with-name 0". 🙅

Validated only if one of the input files for the CriTcl script actually defines and uses a custom build configuration option with that name.

-enable name — Sets the value of the custom build configuration option name to true. It is equivalent to "-with-name 1". ✅

Validated only if one of the input files for the CriTcl script actually defines and uses a custom build configuration option with that name.

-force — Forces compilation even if a shared library for the file already exists. Unlike cleaning the cache, this is lazy in the destruction of files and only affects relevant files. 💪

-help — Prints a short description of command line syntax and options and then exits the application. 🆘
-keep — Causes the system to cache compiled ".c" files. Also prevents the deletion of the unique result cache used by the run when generating a package (see option -pkg below). Intended for debugging of critcl itself, where it may be necessary to inspect the generated C code. 🔍

-libdir directory — Adds directory to the list of directories the linker searches for libraries in (like -L). With -pkg, generated packages are saved in directory. When specified multiple times the last value is used. The default is "lib", resolved relative to the current working directory. 📁
-includedir directory — Adds directory to the list of directories the compiler searches for headers in. With -pkg, generated header files are saved in directory. Uses of this option are cumulative. The last value is used as the destination for generated header files. The default is the relative directory "include", resolved relative to the current working directory.

-pkg — Generates a package from the CriTcl script files. Input files are processed first as usual, but are then bundled into a single library, with additional generated files to form the library into a standard Tcl package. 📦

generation. If both options, i.e. -pkg and -tea are specified the last one specified wins.

Options -clean and -force are ignored. -libdir is relevant in both this and -tea mode.

The basename of the first file is the name of the package to generate. If its file extension indicates a shared library (".so", ".sl", ".dylib", and ".dll") it is also removed from the set of input files. Each CriTcl script file is kept as part of the input. A single file without a suffix is assumed to be a CriTcl script. A file without a suffix, but other input files following is treated like the name of a shared library proper, and removed from the set of input files. 🤓

Examples:

... -pkg ... foo

=> Package name is: foo
=> Input file is:   foo.tcl

... -pkg ... foo bar.tcl

=> Package name is: foo
=> Input file is:   bar.tcl

... -pkg ... foo.tcl

=> Package name is: foo
=> Input file is:   foo.tcl

... -pkg ... foo.so bar.tcl

=> Package name is: foo
=> Input file is:   bar.tcl

-show — Prints the configuration of the chosen target to stdout and then exits. Set -target, below. 👀
-showall — Prints the whole chosen configuration file to stdout and then exits. See -config, above. 📜
-target name — Overrides the default choice of build target. Only the last occurrence of this option is used. The named target must exist in the chosen configuration file. Use -targets (see below) to get a list of the acceptable targets. Use -config to select the configuration file. 🎯

-targets — Prints the list of all known targets from the chosen configuration file to stdout and then exits. Use -config to select the configuration file. 🗒️
-tea — Like -pkg, except no binaries are generated. Creates a directory hierarchy containing the CriTcl script, its companion files, and a TEA-conformant build system with most of the needed support code, including copies of the critcl packages. 🍵

If both -pkg and -tea are specified the last occurrence wins.

-I, -L, -clean, -force, -cache, -includedir, -enable, -disable, and -with-FOO are ignored. In contrast, the option -libdir is relevant in both this and -pkg mode.

Examples:

... -tea ... foo

=> Package name is: foo
=> Input file is:   foo.tcl

... -tea ... foo bar.tcl

=> Package name is: foo
=> Input file is:   bar.tcl

... -tea ... foo.tcl

=> Package name is: foo
=> Input file is:   foo.tcl

... -tea ... foo.so bar.tcl

=> Package name is: foo
=> Input file is:   bar.tcl

-with-name value — This option sets the value of the custom build configuration option name to value.

The information is validated only if one of the ".critcl" input files actually defines and uses a custom build configuration option with that name.

🎀 PACKAGE STRUCTURE 🎀

Okay bestie, so when critcl spits out a package, it doesn't just dump random files everywhere — it's got a whole little layout, and it's actually super organized. Here's the basic shape of what you get:

<TOP>
+- pkgIndex.tcl
+- critcl-rt.tcl
+- license.terms (optional)
|
+- tcl (optional)
|  +- <tsources files>
|
+- <platform>
   +- <shared library>

Notes — because obviously we're doing notes 💅

The file pkgIndex.tcl is the standard package index file that Tcl's package management expects. It gets sourced during a search for packages, and it declares the package to Tcl along with its files and how to handle them.
The file critcl-rt.tcl is a helper file. It's holding the common code that pkgIndex.tcl uses to actually do its tasks.
The file license.terms is optional — it only shows up if the .critcl file that the package was generated from used the command critcl::license to declare the package author and license.
Every file declared with the command critcl::tsources gets dropped into the sub-directory tcl.
The shared library that critcl generates goes into a platform-specific sub-directory.

The whole structure — and especially that last point — is what lets us later merge the results (for the same package, and version) across multiple target platforms into one single directory structure, with zero conflict, just by copying the top directories over each other. The only files that could ever conflict live in the <TOP> and tcl directories, and for those we know they're identical across targets. So it's fine. It's giving "trust the process" energy ✨

And the result of a merge like that? It looks like this:

<TOP>
+- pkgIndex.tcl
+- critcl-rt.tcl
+- license.terms (optional)
|
+- tcl (optional)
|  +- <tsources files>
|
+- <platform1>
|  +- <shared library1>
+- <platform2>
|  +- <shared library2>
...
+- <platformN>
   +- <shared libraryN>

Look at that. Multi-platform. No conflict. Iconic. 🔥

👑 AUTHORS 👑

The legends who made this happen:

Jean Claude Wippler
Steve Landers
Andreas Kupries

💀 BUGS, IDEAS, FEEDBACK 💀

ngl, this document — and the package it describes — will undoubtedly contain bugs and other problems. It's software, bestie, we're all just doing our best 😭

So please, if you find something, report it here:

https://github.com/andreas-kupries/critcl/issues

And if you've got ideas for enhancements for either the package, the application, and/or the documentation — those are super welcome too, and they should go to the exact same place:

https://github.com/andreas-kupries/critcl/issues

One link. All the vibes. Drop your thoughts there. 🫶

🌸 KEYWORDS 🌸

Just so you know what we're working with:

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 ⭐

And that's a wrap, bestie 🎀 This whole page is from the doc source, version 3.3.1, section critcl(1) — so if you're citing it or whatever, that's the receipts. Go compile something beautiful. Slay. 💅

📦 where this page comes from

debian trixie: critcl 3.3.1+dfsg-1 · BSD
ubuntu questing: critcl 3.3.1+dfsg-1
ubuntu resolute: critcl 3.3.1+dfsg-1build1 · BSD
ubuntu stonking: critcl 3.3.1+dfsg-1.1 · BSD
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms