--- name: "critcl_application" section: "1" platform: "linux" package: "critcl" version: "3.3.1+dfsg-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/critcl_application" --- # critcl\_application(1) CriTcl Application Reference ``` ``` ## NAME critcl - CriTcl Application Reference ## SYNOPSIS **critcl** ?*option*...? ?*file*...? ``` ``` ## 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. This document is the reference manpage for the **critcl** command. Its intended audience are people having to build packages using **critcl** for deployment. Writers of packages with embedded C code can ignore this document. If you are in need of an overview of the whole system instead, please go and read the *Introduction To CriTcl*. This application resides in the Application Layer of CriTcl. ``` *================* |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. - **-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/\*", or "*~/.critcl/\.\*" 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). ## PACKAGE STRUCTURE Packages generated by critcl have the following basic structure: ``` +- pkgIndex.tcl +- critcl-rt.tcl +- license.terms (optional) | +- tcl (optional) | +- | +- +- ``` *Notes* - \[1\] The file "*pkgIndex.tcl*" is the standard package index file expected by Tcl's package management. It is sourced during a search for packages, and declares the package to Tcl with its files, and how to handle them. - \[2\] The file "*critcl-rt.tcl*" is a helper file containing the common code used by "*pkgIndex.tcl*" to perform its tasks. - \[3\] The file "*license.terms*" is optional and appears only if the "*.critcl*" file the package is generated from used the command **critcl::license** to declare package author and license. - \[4\] All files declared with the command **critcl::tsources** are put into the sub-directory "*tcl*". - \[5\] The shared library generated by critcl is put into a platform-specific sub-directory. The whole structure, and especially the last point, enable us to later merge the results (for the same package, and version) for multiple target platforms into a single directory structure without conflict, by simply copying the top directories over each other. The only files which can conflict are in the \ and "*tcl*" directories, and for these we know that they are identical across targets. The result of such a merge would look like: ``` +- pkgIndex.tcl +- critcl-rt.tcl +- license.terms (optional) | +- tcl (optional) | +- | +- | +- +- | +- ... +- +- ``` ## 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 ``` Copyright (c) Jean-Claude Wippler Copyright (c) Steve Landers Copyright (c) 2011-2024 Andreas Kupries ```