[ Table Of Contents | Keyword Index ]
critcl_introduction(n) 2 doc "C Runtime In Tcl (CriTcl)"
Name
critcl_introduction - Introduction To CriTcl
Description
Welcome to the C Runtime In Tcl, CriTcl for short, a system to build C extension packages for Tcl on the fly, from C code embedded within Tcl scripts, for all who wish to make their code go faster.
CriTcl started life as an experiment by Jean-Claude Wippler and was a self-contained Tcl package to build C code into a Tcl/Tk extension on the fly. It was somewhat inspired by Brian Ingerson's Inline for Perl, but is considerably more lightweight.
It is for the last 5% to 10% when pure Tcl, which does go a long way, is not sufficient anymore. I.e. for
when the last bits of performance are needed,
access to 3rd party libraries,
hiding critical pieces of your library or application, and
simply needing features provided only by C.
Modes Of Operation/Use
CriTcl can be used in three different modes of operation, called
Compile & Run, and
Generate TEA Package
Of these three Compile & Run came first and is the default when using the package directly. In that case the package collects the C fragments, builds them as needed, and caches the results for quick reuse when the same code is used in the future again.
The second mode, Generate Package, was introduced to enable the creation of (prebuilt) deliverable packages which do not depend on the existence of a build system, i.e. C compiler, on the target machine. This was originally done through the experimental Critbind tool, and is now handled by the CriTcl Application, also named critcl.
Newly introduced with Critcl version 3 is Generate TEA Package. This mode constructs a directory hierarchy from the package which can later be built like a regular TEA package, i.e. using
.../configure --prefix ... make all isntall
System Architecture
The whole system consist of two pieces, as seen in the figure below
At the top we have an application built on top of the core package, providing higher-level features than just compiling embedded C on the fly.
Below is the core package providing the essential functionality of the system.
Changes for version 2.1
Fixed bug where critcl::tsources interpreted relative paths as relative to the current working directory instead of relative to the ".critcl" file using the command, as all other commands of this type do.
Fixed internals, preventing information collected for multiple ".critcl" files to leak between them. Notably, critcl::tk is not a global configuration option anymore.
Fixed the command critcl::license to be a null-operation in mode "compile & run", instead of throwing an error.
Fixed the critcl application's interference with the "compile & run" result cache in -pkg mode by having it use a wholly separate (and by default transient) directory for that mode.
Fixed bug where changes to a ".critcl" file did not result in a rebuild for mode "compile & run". All relevant API commands now ensure UUID changes.
Fixed bug in the backend handling of critcl::debug where the companion c-sources of a ".critcl" file were not compiled with debug options, although the ".critcl" file was.
Fixed bug in critcl::debug which prevented recognition of mode "all" when it was not the first argument to the command.
Fixed bug in "preload.c" preventing its compilation on non-windows platforms.
Fixed long-standing bug in the handling of namespace qualifiers in the command name argument of critcl::cproc and critcl::ccommand. It is now possible to specify a fully qualified command name without issues.
Extended/reworked critcl::tsources to be the canonical way of declaring ".tcl" companion files even for mode "compile & run".
Extended/reworked critcl::tsources to allow the use of a ".critcl" file as its own Tcl companion file.
Extended critcl::framework to internally check for OS X build target, and to ignore the declaration if its not.
Extended critcl::failed to be callable more than once in a ".critcl" file. The first call forces the build, if it was not done already, to get the result. Further calls return the cached result of the first call.
Extended the handling of environment variable CC in the code determining the compiler to use to deal with (i.e. remove) paths to the compiler, compiler file extensions, and compiler options specified after the compiler itself, leaving only the bare name of the compiler.
Extended the code handling the search for preloaded libraries to print the paths it searched, making debugging of a search failure easier.
A new command critcl::tcl can be used to declare the version of Tcl minimally needed to build and run the ".critcl" file and package. Defaults to 8.4 if not declared. Extended critcl to have the stubs and headers for all of Tcl 8.4, 8.5, and 8.6.
A new command critcl::load forces the build and load of a ".critcl" file. This is the official way for overriding critcl's default lazy-build-&-load-on-demand scheme for mode "compile & run".
Note that after using critcl::load / critcl::failed in a ".critcl" file it is not possible to use critcl commands in that file anymore. Doing so will throw an error.
Extended the generation of '#line' pragmas to use info frame (if available) to provide the C compiler with exact line numbers into the ".critcl" file for the reporting of warnings and errors.
Extended critcl::check with logging to help with debugging build-time checks of the environment, plus an additional optional argument to provide labeling.
Added a new command critcl::checklink which not only tries to check the environment via compiling the code, but also its linkability.
Added a new command critcl::msg for messaging, like command critcl::error is for error reporting. Likewise this is a hook a user of the package is allowed to override. The default implementation, used by mode compile & run does nothing. The implementation for mode generate package prints the message to stdout.
Envisioned use is for the reporting of results determined by critcl::check and critcl::checklink during building, to help with debugging when something goes wrong with a check.
Exposed the argument processing internals of critcl::proc for use by advanced users. The new commands are
critcl::argnames
critcl::argcnames
critcl::argcsignature
critcl::argvardecls
critcl::argconversion
Please see section Advanced Embedded C Code of the critcl package documentation for details.
Extended the critclk package to intercept package provide and record the file -> package name mapping. Plus other internal changes now allow the use of namespaced package names while still using proper path names and init function.
Dropped the unused commands critcl::optimize and critcl::include.
Dropped -lib mode from the critcl application.
Dropped remnants of support for Tcl 8.3 and before.
Changes for version 3
The command critcl::platform was deprecated in version 2.1, superceded by critcl::targetplatform, yet kept for compatibility. Now it has been removed.
The command critcl::compiled was kept with in version 2.1 with semantics in contradiction to its, for compatibility. This contradiction has been removed, changing the visible semantics of the command to be in line with its name.
The change to version 3 became necessary because of the two incompatible visible changes above.
Extended the application package with code handling a new option -tea. Specifying this option invokes a special mode where critcl generates a TEA package, i.e. wraps the input into a directory hierarchy and support files which provide it TEA-lookalike buildsystem.
This new option, and -pkg, exclude each other. If both are specified the last used option takes precedence.
The generated package directory hierarchy is mostly self-contained, but not fully. It requires not only a working installation of Tcl, but also working installations of the packages md5 and cmdline. Both of these are provided by the Tcllib bundle. Not required, but recommended to have installed are any of the packages which can accelerate md5's operation, i.e. cryptkit, tcllibc, or Trf.
Extended the critcl package with a new command critcl::scan taking the path to a ".critcl" file, statically scanning it, and returning license, version, a list of its companion files, list of imported APIs, and list of developer-specified custom configuration options. This data is the foundation for the TEA wrapping described above.
Note that this is a static scan. While the other build modes can (must) execute the ".critcl" file and make platform-specific decisions regarding the assembled C code, companion files, etc. the TEA wrap mode is not in a position to make platform-specific decisions. It has to wrap everything which might conceivably be needed when actually building. Hence the static scan. This has however its own set of problems, namely the inability to figure out any dynamic construction of companion file paths, at least on its own. Thus:
Extended the API used by critcl-based packages with the command critcl::owns. While this command is ignored by the regular build modes the static scanner described above takes its arguments as the names of companion files which have to be wrapped into the TEA package and could not be figured by the scanner otherwise, like because of dynamic paths to critcl::tsources, critcl::csources, getting sourced directly, or simply being adjunct datafiles.
Extended the API used by critcl-based packages with the command critcl::api for the management of stubs tables, be it their use, and/or declaration and export.
Please see section Stubs Table Management of the critcl package documentation for details.
Extended the API used by critcl-based packages with the command critcl::userconfig for the management of developer-specified custom configuration options, be it their use and/or declaration.
Please see section Custom Build Configuration of the critcl package documentation for details.
Extended the API used by critcl-based packages with the commands critcl::description, critcl::summary, critcl::subject, critcl::meta, and critcl::buildrequirement for the declaration of TEApot meta data for/about the package.
Please see section Package Meta Data of the critcl package documentation for details.
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 such at https://chiselapp.com/user/andreas_kupries/repository/CriTcl/reportlist. Please also report any ideas for enhancements you may have for either package and/or documentation.
Note that this is not critcl's official bug tracker, but the repository where inofficial and experimental development of critcl is taking place. It is the best which can be done because an official bug tracker does not exist.
Category
Embedded C code
Copyright
Copyright © ???????????????????