Provided by: critcl_3.3.1+dfsg-1_amd64 
NAME
critcl_application_package - CriTcl Application Package Reference
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 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::app package. Its intended audience are developers
working on critcl's internals. These commands are not needed to simply write a CriTcl script. If you
are in need of an overview of the whole system instead, please go and read the Introduction To CriTcl.
This package resides in the Application Layer of CriTcl.
*================*
|Applications |
| critcl |
| critcl::app |
*================*
+----------------+
|Core Packages |
| critcl |
| critcl::util |
+----------------+
+----------------+
|Support Packages|
| stubs::* |
| md5, platform |
| ... |
+----------------+
, implementing the functionality of the CriTcl Application, and through this, the mode generate package.
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 a single command
::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
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/<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
CriTcl can be used in three different modes of operation, called
[1] Compile & Run, and
[2] Generate Package
[3] Generate TEA Package
Compile & Run was the original mode and is the default for critcl_pkg. Collects the C fragments from the
CriTcl script, builds them as needed, and caches the results to improve load times later.
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
PACKAGE STRUCTURE
Packages generated by critcl have the following basic structure:
<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 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 <TOP>
and "tcl" directories, and for these we know that they are identical across targets. 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. 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
doc 3.3.1 critcl_application_package(3tcl)