critcl_a..._package(3tcl)

📦
version 3.3.1 · 2 versions
, in ubuntu resolute, ubuntu stonking

💖 NAME 💖

critcl_application_package — the CriTcl Application Package Reference, bestie 🫶

(yes, this is the critcl_a..._package(3tcl) page, from the C Runtime In Tcl, aka CriTcl. buckle up.)

✨ SYNOPSIS ✨

package require Tcl 8.6

package require critcl::app ?3.3.1?

package require critcl ?3.3.1?

package require platform ?1.0.2?

package require cmdline

::critcl::app::main commandline

🦋 DESCRIPTION 🦋

Be welcome to the C Runtime In Tcl (short: CriTcl), a whole system for embedding and using C code from inside your Tcl [http://core.tcl-lang.org/tcl] scripts. no cap, it's giving "C but make it Tcl" and honestly? iconic. 💅

This doc right here is the reference manpage for the critcl::app package. The intended audience is developers working on critcl's internals — like, the people poking around inside the machine. You do not need these commands to just write a normal CriTcl script, fr fr. If you want the big-picture overview of the whole system instead, go read the Introduction To CriTcl. 🌸

This package lives in the Application Layer of CriTcl. Behold, the layers, in all their ASCII glory:

*================*
|Applications    |
| critcl         |
| critcl::app    |
*================*
+----------------+
|Core Packages   |
| critcl         |
| critcl::util   |
+----------------+
+----------------+
|Support Packages|
| stubs::*       |
| md5, platform  |
|  ...           |
+----------------+

…implementing the functionality of the CriTcl Application, and through that, the generate package mode. And here's the tea: the actual application is (only) a shim wrapping around this package 🫶. It itself is build on top of the core package critcl.

🌈 API 🌈

The package exports exactly one single command, and that's it. periodt. 💅

  • ::critcl::app::main commandline — The commandline is a list of zero or more options followed by zero or more CriTcl script files. By default, the CriTcl script files are build and the results cached. This cuts down on the time needed to load the package. The last occurrence of -pkg and -tea, if provided, selects the corresponding alternative mode of operations. For a larger set of examples please see section "Building CriTcl Packages" in the document about Using CriTcl. ✨

The options are:

🎀 OPTIONS 🎀

Here are all the options it understands, bestie — every single one, no skips, no summarizing. 👑

  • -v, --version — Print the version to stdout and exit. bye bestie, that's the whole job. 👋
  • -I path — Arranges for the compiler to search path for headers. Uses of this option are cumulative.

Ignored when generating a TEA package (see option -tea below).

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

Ignored when generating a TEA package (see option -tea below).

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

Ignored when generating a TEA package (see option -tea below).

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

Ignored when generating a package because this mode starts out with a unique and empty result cache. See option -pkg, below.

Ignored when generating a TEA package (see option -tea below).

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

Ignored when generating a TEA package (see option -tea below).

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

Ignored when generating a TEA package (see option -tea below). Uses of this option are cumulative.

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

Ignored when generating a TEA package (see option -tea below).

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

Ignored when generating a TEA package (see option -tea below).

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

Ignored when generating a package (see option -pkg, below), which starts out with a unique and empty result cache.

Ignored when generating a TEA package (see option -tea below).

  • -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. 🔍

Ignored when generating a TEA package (see option -tea below).

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

Ignored when generating a TEA package (see option -tea below).

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

Ignored when generating a TEA package (see option -tea below).

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

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:

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

Ignored when generating a TEA package (see option -tea below).

🌈 MODES OF OPERATION/USE 🌈

okay so bestie, CriTcl can be used in three different modes of operation, and they are literally:

  1. Compile & Run, and
  2. Generate Package
  3. Generate TEA Package

Compile & Run was the original mode and is the default for critcl_pkg. The way it works is it collects all the C fragments out of the CriTcl script, builds them whenever they're needed, and then caches the results so that later loads go faster. it's giving "build once, slay forever" 💅

The second mode, Generate Package, got introduced so you could make (prebuilt) deliverable packages that do not depend on there being a build system — like a C compiler — on the target machine. no compiler on the box? no problem, bestie 🫶 This was originally done through the experimental Critbind tool, and now it's handled by the CriTcl Application, which is also named critcl.

Newly introduced with CriTcl version 3 is Generate TEA Package. This mode constructs a directory hierarchy from the package, and that hierarchy can later be built like a regular TEA package, i.e. using:

.../configure --prefix ...
make all isntall
ngl the isntall up there is exactly what the original says, so we're keeping it fr fr 🙈

🎀 PACKAGE STRUCTURE 🎀

Packages generated by critcl have this basic structure, periodt:

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

✨ Notes ✨

  1. The file "pkgIndex.tcl" is the standard package index file that Tcl's package management expects. It gets sourced whenever Tcl is searching for packages, and it declares the package to Tcl along with its files, and how to handle them.
  2. The file "critcl-rt.tcl" is a helper file holding the common code which "pkgIndex.tcl" uses to do its little tasks. lowkey the unsung hero of the whole operation 💖
  3. The file "license.terms" is optional and only shows up if the .critcl file that the package is generated from used the command critcl::license to declare the package author and license.
  4. All files declared with the command critcl::tsources get put into the sub-directory "tcl".
  5. The shared library generated by critcl gets put into a platform-specific sub-directory.

The whole structure — and especially that last point — lets us later merge the results (for the same package and version) for multiple target platforms into a single directory structure, with zero conflicts, just by copying the top directories over each other. The only files that could conflict live in the <TOP> and "tcl" directories, and for those we already know they're identical across targets. so like, no drama 💅 The result of such a merge would look like:

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

👑 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. it's not a vibe, it's just reality 🙈 Please report them at https://github.com/andreas-kupries/critcl/issues. Ideas for enhancements you may have for either the package, the application, and/or the documentation are also very welcome and should be reported at https://github.com/andreas-kupries/critcl/issues as well. come through, bestie 🫶

⭐ 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

and that's the whole page, bestie 🎀 this was critcl_a..._package(3tcl) from the doc collection, version 3.3.1, dated as the footer says — mwah, go forth and embed your C code, you main character 💖✨👑

📦 where this page comes from