Provided by: critcl_3.1.9-1_all bug

NAME

       critcl - CriTcl Application

SYNOPSIS

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

_________________________________________________________________

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.

       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
              These options cause critcl to print its version to stdout and then exit.

       -I path
              This option specifies an additional global include path to use  during  compilation
              of ".critcl" files. All values are used if this is specified multiple times.

              This option is irrelevant when generating a TEA package (see option -tea below).

       -L path
              This option specifies an additional global library searh path to use during linking
              of ".critcl" files. All values are used if this is specified multiple times.

              This option is irrelevant when generating a TEA package (see option -tea below).

       -cache path
              This option specifies the path to the directory to use as the result cache. If  not
              specified it defaults to "~/.critcl/<platform>", or, when generating a package (see
              option -pkg below), to "~/.critcl/<pid>.<epoch>", When specified multiple times the
              last value is used.

              This option is irrelevant when generating a TEA package (see option -tea below).

       -clean When  specified  the  result cache is emptied, i.e. all files and directories found
              inside are deleted) before compilation begins.

              This option is irrelevant when generating a package (see option -pkg below) because
              this mode starts out with a unique and empty result cache.

              This option is irrelevant when generating a TEA package (see option -tea below).

       -config path
              This option specifies the path to a custom configuration file, allowing the user to
              use  their  own  target  specifications.  If  not  specified  a  hardwired  default
              configuration embedded in the system core is used instead.  When specified multiple
              times the last value is used.

              This option is irrelevant when generating a TEA package (see option -tea below).

       -debug mode
              This option activates compilation with debugging. It accepts the modes below.  When
              specified multiple times the combination of all modes is used.

              This option is irrelevant when generating a TEA package (see option -tea below).

              memory This  mode  activates  memory  debugging of allocations made through the Tcl
                     core.

              symbols
                     This mode activates building of all ".c" files with debugging symbols.

              all    This mode activates both memory and symbols.

       -disable name
              This option sets the value of the custom build configuration option name to  false.
              It is equivalent to "-with-name 0".

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

              This option is irrelevant when generating a TEA package (see option -tea below).

       -enable name
              This option sets the value of the custom build configuration option name  to  true.
              It is equivalent to "-with-name 1".

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

              This option is irrelevant when generating a TEA package (see option -tea below).

       -force When specified compilation is always done, even if a shared library  for  the  file
              exists  already.  This  effect can be had through cleaning the cache (see above) as
              well, except that it is lazy in the destruction of files and will not destroy files
              unrelated to the ones we are building.

              This option is irrelevant when generating a package (see option -pkg below) because
              this mode starts out with a unique and empty result cache.

              This option is irrelevant when generating a TEA package (see option -tea below).

       -help  This option will cause the system to print a short help about command  line  syntax
              and options and then exit the application.

       -keep  This  option will cause the system to keep the ".c" files generated by a run in the
              result cache.  When generating a package (see option -pkg below) this also prevents
              the  deletion  of the unique result cache used by the run.  This option is intended
              for the debugging of critcl itself, where  it  may  be  necessary  to  inspect  the
              generated C code.

              This option is irrelevant when generating a TEA package (see option -tea below).

       -libdir path
              This  option  specifies the path under which the packages generated via option -pkg
              are saved. It also specifies a path to search libraries  in,  like  for  -L.   When
              specified  multiple  times  the  last value is used.  When not specified at all the
              default, "lib", is used. Note how this is a relative path, placing the result  into
              the current working directory.

       -includedir path
              This option specifies the path under which any generated package headers are saved.
              It also specifies a path to search include files in, like for -I.   When  specified
              multiple  times  the last value is used as destination, however all previous values
              are kept on the include search path.   When  not  specified  at  all  the  default,
              "include",  is  used. Note how this is a relative path, placing the result into the
              current working directory.

              This option is irrelevant when generating a TEA package (see option -tea below).

       -pkg   The default mode of the application is to build the ".critcl" files listed  on  the
              command  line and save the results in the result cache. Essentially pre-filling the
              cache with important packages, cutting  down  on  the  time  needed  to  use  these
              packages.

              This option activates one of the other modes, package generation.  In this mode the
              input files are processed first as usual, however after that they are bundled  into
              a  single library and additional files are generated to make this library usable as
              a regular Tcl package.

              The option -tea, see below, invokes the last mode, TEA generation. If both options,
              i.e. -pkg and -tea are specified the last one specified wins.

              In this mode the options -clean and -force are irrelevant and ignored. In contrast,
              the option -libdir is relevant in both this and -tea mode.

              When this option is specified the basename of the first  file  argument  after  the
              options  is  used  as the name of the package to generate. If the extension of that
              file indicates a shared library (".so", ".sl", ".dylib", and  ".dll")  it  is  also
              removed  from the set of input files. A ".tcl" file is kept as part of the input. A
              single file without extension is assumed to actually have  a  ".tcl"  extension.  A
              file without extension, but other input files following is treated like the name of
              a shared library proper, and removed from the set of input files.

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

       -show  This option, when specified, will cause the system to print  the  configuration  of
              the  chosen target to stdout and then exit.  The choice of target can be influenced
              through the option -target (see below).

       -showall
              This option, when specified, will cause  the  system  to  print  the  whole  chosen
              configuration  file  to stdout and then exit.  The choice of configuration file can
              be influenced through the option -config (see above).

       -target name
              This option overrides the default choice of build target with  the  user's  choice.
              When  specified multiple times the last value is used.  The named target must exist
              in the chosen configuration file.  Use option -targets (see below) to get a list of
              the acceptable targets.  The choice of configuration file can be influenced through
              the option -config (see above).

              This option is irrelevant when generating a TEA package (see option -tea below).

       -targets
              This option, when specified, will cause the system to print the list of  all  known
              targets  from the chosen configuration file to stdout and then exit.  The choice of
              configuration file can be influenced through the option -config (see above).

       -tea   Similar to option -pkg, except that the invoked mode does  not  generate  binaries,
              but a directory hierarchy containing the ".critcl" file, its companion files, and a
              TEA-lookalike build system with most of the needed support code  (incliding  copies
              of the critcl packages).

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

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

              When  this  option  is  specified the basename of the first file argument after the
              options is used as the name of the package to generate. If the  extension  of  that
              file  indicates  a  shared  library (".so", ".sl", ".dylib", and ".dll") it is also
              removed from the set of input files. A ".tcl" file is kept as part of the input.  A
              single  file  without  extension  is assumed to actually have a ".tcl" extension. A
              file without extension, but other input files following is treated like the name of
              a shared library proper, and removed from the set of input files.

              Examples:
              => Package name is: foo
              => Input file is:   foo.tcl
              => Package name is: foo
              => Input file is:   bar.tcl
              => Package name is: foo
              => Input file is:   foo.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.

              This option is irrelevant when generating a TEA package (see option -tea above).

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>

CHANGES FOR VERSION 2.1

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

       [2]    Fixed  internals,  preventing information collected for multiple ".critcl" files to
              leak between them.  Notably,  critcl::tk  is  not  a  global  configuration  option
              anymore.

       [3]    Fixed  the  command critcl::license to be a null-operation in mode "compile & run",
              instead of throwing an error.

       [4]    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.

       [5]    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.

       [6]    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.

       [7]    Fixed  bug  in  critcl::debug which prevented recognition of mode "all" when it was
              not the first argument to the command.

       [8]    Fixed bug in "preload.c" preventing its compilation on non-windows platforms.

       [9]    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.

       [10]   Extended/reworked critcl::tsources to be the  canonical  way  of  declaring  ".tcl"
              companion files even for mode "compile & run".

       [11]   Extended/reworked  critcl::tsources to allow the use of a ".critcl" file as its own
              Tcl companion file.

       [12]   Extended critcl::framework to internally check for OS X build target, and to ignore
              the declaration if its not.

       [13]   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.

       [14]   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.

       [15]   Extended the code handling the search for preloaded libraries to print the paths it
              searched, making debugging of a search failure easier.

       [16]   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.

       [17]   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.

       [18]   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.

       [19]   Extended critcl::check with logging to help with debugging build-time checks of the
              environment, plus an additional optional argument to provide labeling.

       [20]   Added a new command critcl::checklink which not only tries to check the environment
              via compiling the code, but also its linkability.

       [21]   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.

       [22]   Exposed the argument processing internals  of  critcl::proc  for  use  by  advanced
              users. The new commands are

              [1]    critcl::argnames

              [2]    critcl::argcnames

              [3]    critcl::argcsignature

              [4]    critcl::argvardecls

              [5]    critcl::argconversion

              Please see section Advanced Embedded C Code of the critcl package documentation for
              details.

       [23]   Extended the critcl 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.

       [24]   Dropped the unused commands critcl::optimize and critcl::include.

       [25]   Dropped -lib mode from the critcl application.

       [26]   Dropped remnants of support for Tcl 8.3 and before.

CHANGES FOR VERSION 3

       [1]    The  command  critcl::platform  was  deprecated  in  version  2.1,  superceded   by
              critcl::targetplatform, yet kept for compatibility. Now it has been removed.

       [2]    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.

       [3]    The  change  to  version 3 became necessary because of the two incompatible visible
              changes above.

       [4]    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.

       [5]    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:

       [6]    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.

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

       [8]    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.

       [9]    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.

CHANGES FOR VERSION 3.0.1

       [1]    Bugfixes all around. In detail:

       [2]    Fixed recording  of  Tcl  version  requirements.  Keep  package  name  and  version
              together, unbreaking generated meta data and generated package load command.

       [3]    Fixed the build scripts: When installing, or wrapping for TEA, generate any missing
              directories

       [4]    Modified the build scripts to properly exit the  application  when  the  window  of
              their GUI is closed through the (X) button.

       [5]    Removed an 8.5-ism (open wb) which had slipped into the main build script.

       [6]    Modified  the  example  build  scripts  to  separate  the  output for the different
              examples (and packages) by adding empty lines.

       [7]    stack::c example bugfix: Include API declarations for use in the companion files.

       [8]    Extended the documentation: Noted the need  for  a  working  installation  of  a  C
              compiler.

       [9]    Extended  the Windows target definitions and code to handle the manifest files used
              by  modern  MS  development  environments.  Note  that  this  code   handles   both
              possibilities, environment using manifests, and (old(er)) environments without.

       [10]   Extended  the Windows 64bit target definitions and code to auto-detect the need for
              the helper library "bufferoverflowU.lib"  and  reconfigure  the  compile  and  link
              commands  appropriately.  We  assume  that the library must be linked when present.
              This should be no harm if the library is present, yet not needed. Just superfluous.
              We search for the library in the paths specified by the environment variable LIB.

CHANGES FOR VERSION 3.0.2

       [1]    Fixed  issue in compile-and-run mode where commands put into the auto_index are not
              found by Tcl's [unknown] command.

       [2]    Fixed an array key mismatch breaking usage of client data and delete  function  for
              procedure. Reported by Jos DeCoster, with patch.

       [3]    Implemented  a command line option -L, an equivalent of option -I, just for library
              search paths.

       [4]    Fixed github issues 5 and 8. Working around  a  missing  variable  ::errorInfo.  It
              should  always  be  present, however there seem to be revisions of Tcl around which
              violate this assumption.

CHANGES FOR VERSION 3.0.3

       [1]    Fixed github issues 5 and 8, for the example build.tcl scripts.  Working  around  a
              missing variable ::errorInfo. It should always be present, however there seem to be
              revisions of Tcl around which violate this assumption.

CHANGES FOR VERSION 3.0.4

       [1]    Fixed generation of the package's initname when the  incoming  code  is  read  from
              stdin and has no proper path.

       [2]    Fixed  github  issue  11.  Now  using /LIBPATH instead of -L on Windows (libinclude
              configuration setting).

       [3]    Extended critcl to handle -l:path format of -l options.  GNU ld 2.22+ handles  this
              by searching for the path as is. Good when specifying static libraries, as plain -l
              looks for shared libraries in preference over static. critcl  handles  it  now,  as
              older GNU ld's do not understand it, nor the various vendor-specific linkers.

       [4]    Fixed  github  issue #12. Critcl now determines the version of MSVC in use and uses
              it to switch between  various  link  debug  options.  Simplified  the  handling  of
              bufferoverflowU.lib  also,  making use of the same mechanism and collapsing the two
              configurations sections we had back into one.

       [5]    Reworked the insertion of  #line  pragmas  into  the  generated  C  code  to  avoid
              limitations  on  the line number argument imposed by various compilers, and be more
              accurate.

       [6]    Modified argument processing. Option -libdir now also implies -L for its argument.

       [7]    Extended handling of option -show (critcl::showconfig) to  list  the  path  of  the
              configuration  file  the  data  is  coming  from.  Good for debugging configuration
              processing.

       [8]    Extended the build script with targets to regenerate  the  embedded  documentation,
              and diagrams, and to generate a release.

CHANGES FOR VERSION 3.0.5

       [1]    Fixed  bug  in  the  new  code  for  #line pragmas triggered when specifying C code
              without leading whitespace.

       [2]    Extended the documentation to have manpages  for  the  license,  source  retrieval,
              installer, and developer's guides.

CHANGES FOR VERSION 3.0.6

       [1]    Fixed  github  issue 10. The critcl application now delivers a proper exit code (1)
              on build failure, instead of always indicating success (status 0).

       [2]    Fixed github issue 13. Handling  of  bufferoverflowU.lib  for  release  builds  was
              inconsistent  with  handling  for  debug  builds.  It  is  now  identically handled
              (conditional) by both cases.

       [3]    Documentation cleanup, mainly in the installation guide, and the README.md shown by
              github

CHANGES FOR VERSION 3.0.7

       [1]    Fixed  the  code  generated  by critcl::c++command.  The emitted code handed a non-
              static string table to Tcl_GetIndexFromObj, in violation  of  the  contract,  which
              requires  the  table  to  have  a fixed address. This was a memory smash waiting to
              happen. Thanks to Brian Griffin for alrerting us to the general problem.

CHANGES FOR VERSION 3.1

       [1]    Added a new higher-level package critcl::iassoc.

              This package simplifies the creation of code associating data with  an  interpreter
              via Tcl's Tcl_(Get|Set)AssocData() APIs. The user can concentrate on his data while
              all the necessary boilerplate C code to support this is generated by the package.

              This package uses several of the new features which were added to the  core  critcl
              package, see below.

       [2]    Added the higher-level package critcl::class.

              This  package  simplifies  the  creation of C level objects with class and instance
              commands. The user can write a class definition with class- and  instance-variables
              and -methods similar to a TclOO class, with all the necessary boilerplate C code to
              support this generated by the package.

              This package uses several of the new features which were added to the  core  critcl
              package, see below.

       [3]    Extended  the  API for handling TEApot metadata. Added the command critcl::meta? to
              query the stored information. Main use currently envisioned  is  retrieval  of  the
              current  package's  name  by  utility  commands, for use in constructed names. This
              particular information is always available due to the static scan  of  the  package
              file on execution of the first critcl command.

              The  new  packages  critcl::iassoc  and critcl::class (see above) are users of this
              command.

       [4]    Extended the API with a command, critcl::name2c, exposing the process of converting
              a  Tcl  name  into base name, namespace, and C namespace. This enables higher-level
              code generators to generate the same type of C identifiers as critcl itself.

              The new package critcl::class (see above) is a user of this command.

       [5]    Extended the API with a command, critcl::source, executing critcl commands found in
              a  separate file in the context of the current file. This enables easier management
              of larger bodies of code as it allows the user to split  such  up  into  easier  to
              digest smaller chunks without causing the generation of multiple packages.

       [6]    Related  to  the previous item, extended the API with commands to divert collection
              of generated C code into memory. This makes it  easier  to  use  the  commands  for
              embedded C code in higher-level code generators.

              See the section Advanced: Diversions for details of the provided commands.

              The new package critcl::class (see above) is a user of these facilities.

       [7]    Extended  the  API with commands helping developers with the generation of proper C
              #line directives. This allows higher-level code generators to generate  and  insert
              their  own  directives,  ensuring  that  compile  errors in their code are properly
              attributed.

              See the section Advanced: Location management for details of the provided commands.

              The new packages critcl::iassoc and critcl::class (see above) are  users  of  these
              facilities.

       [8]    Extended  the  API with commands giving users the ability to define custom argument
              and result types for ::critcl::cproc.

              See the section Advanced: Extending cproc for details of the provided commands.

CHANGES FOR VERSION 3.1.1

       [1]    Bugfixes all around. In detail:

       [2]    Fixed the generation of  wrong#args  errors  for  critcl::cproc  and  derived  code
              (critcl::class  cproc-based  methods). Use NULL if there are no arguments, and take
              the offset into account.

       [3]    Fixed the handling of package names by critcl::class. Forgot that they may  contain
              namespace separators. Bumped to version 1.0.1.

       [4]    Extended  a critcl::class generated error message in instance creation for clarity.
              Bumped to version 1.0.2.

CHANGES FOR VERSION 3.1.2

       [1]    Enhancement. In detail:

       [2]    Extended critcl::cproc to be able to handle optional arguments, in a  limited  way.
              This is automatically available to critcl::class cproc-based methods as well.

       [3]    Bugfix  in  lassign  emulation  for  Tcl 8.4.  Properly set unused variables to the
              empty string.  Bumped version of emulation package lassign84 to 1.0.1.

CHANGES FOR VERSION 3.1.3

       [1]    Enhancement. In detail:

       [2]    Added new argument type "pstring", for "Pascal String", a counted  string,  i.e.  a
              combination of string pointer and string length.

       [3]    Added new methods critcl::argtypesupport and ::critcl::argsupport to define and use
              additional supporting code for an argument type, here used by  "pstring"  above  to
              define the necessary structure.

       [4]    Semi-bugfixes  in the packages critcl::class and critcl::iassoc. Pragmas for the AS
              meta data scanner to ensure that the template files are made part of  the  package.
              Versions bumped to 1.0.4 and 1.0.1 respectively.

CHANGES FOR VERSION 3.1.4

       [1]    Bugfix  in  package critcl::class. Generate a dummy field in the class structure if
              the class has no class variables. Without this change the structure would be empty,
              and a number of compilers are not able to handle such a type.

       [2]    Fixed a typo which broke the win64 configuration.

       [3]    Fixed issue #16, a typo in the documentation of command critcl::class.

CHANGES FOR VERSION 3.1.5

       [1]    Fixed  issue  #19.  Made  the regular expression extracting the MSVC version number
              more general to make it work on german  language  systems.  This  may  have  to  be
              revisited in the future, for other Windows locales.

       [2]    Fixed  issue  #20.  Made  option -tea work on windows, at least in a unix emulation
              environment like msys/mingw.

CHANGES FOR VERSION 3.1.6

       [1]    Fixed issue #21. While the multi-definition of the stub-table pointer variables was
              ok  with  for  all  the C linkers seen so far C++ linkers did not like this at all.
              Reworked the code to ensure that this set of variables is generated only  once,  in
              the wrapper around all the pieces to assemble.

       [2]    Fixed   issue   #22,   the   handling   of  the  command  identifier  arguments  of
              critcl::ccommand, critcl::cproc, and critcl::cdata. We now properly allow  any  Tcl
              identifier and generate proper internal C identifiers from them.

              As  part  of  this the signature of command critcl::name2c changed. The command now
              delivers a list of four values instead of three. The new value  was  added  at  the
              end.

              Further   adapted   the   implementation   of  package  critcl::class,  a  user  of
              critcl::name2c.  This package is now at version 1.0.6 and requires critcl 3.1.6

              Lastly  fixed  the  mis-handling  of  option  -cname   in   critcl::ccommand,   and
              critcl::cproc.

       [3]    Fixed issue #23.

CHANGES FOR VERSION 3.1.7

       [1]    Fixed issue #24. Extract and unconditionally display compiler warnings found in the
              build log. Prevents users from missing warnings which, while not causing the  build
              to fail, may still indicate problems.

       [2]    New  feature.  Output hook. All non-messaging user output is now routed through the
              command critcl::print, and users are allowed to override it when using  the  critcl
              application-as-package.

       [3]    New  feature, by Ashok P. Nadkarni. Platform configurations can inherit values from
              configurations defined before them.

CHANGES FOR VERSION 3.1.8

       [1]    Fixed issue with package indices generated for Tcl 8.4.  Join the list of  commands
              with semi-colon, not newline.

       [2]    Fixed issue #26 which brought up use-cases I had forgotten to consider while fixing
              bug #21 (see critcl 3.1.6).

CHANGES FOR VERSION 3.1.9

       [1]    Fixed issue #27. Added missing platform definitions for various alternate linux and
              OS X targets.

       [2]    Fixed  issue  #28.  Added  missing  -mXX  flags  for linking at the linux-{32,64}-*
              targets.

       [3]    Fixed issue #29. Replaced the use of raw "cheaders" information in  the  processing
              of "cdefines" with the proper include directives derived from it.

       [4]    Fixed  the  issue  behind  rejected pull request #30 by Andrew Shadura. Dynamically
              extract the stubs variable declarations from the  Tcl  header  files  and  generate
              matching  variable definitions for use in the package code. The generated code will
              now be always consistent with the headers, even when critcl's own copy of  them  is
              replaced by system headers.

       [5]    Fixed  issue  #31.  Accepted  patch by Andrew Shadura, with changes (comments), for
              easier integration of critcl with OS package systems, replacing critcl's copies  of
              Tcl headers with their own.

       [6]    Fixed  issue  #32.  Merged  pull  request  by  Andrew  Shadura.   Various  typos in
              documentation and comments.

       [7]    Fixed issue #33. Handle files starting with a dot better.

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, 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-2013 Andreas Kupries