Provided by: critcl_3.1.18.1+dfsg-3_amd64 bug

NAME

       critcl - CriTcl Application

SYNOPSIS

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

_________________________________________________________________________________________________

DESCRIPTION

       C  Runtime In Tcl, or CriTcl , is a system for compiling C code embedded in Tcl on the fly
       and either loading the resulting objects into Tcl for immediate use or packaging them  for
       distribution.  Use CriTcl to improve performance by rewriting in C those routines that are
       performance bottlenecks.

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

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>

       The latest changes are found at the top.

CHANGES FOR VERSION 3.1.18.1

       [1]    Attention: While the overall version (of the bundle) moves to 3.1.18.1 the versions
              of packages critcl and critcl::app are unchanged.

       [2]    Bugfix  Generally  removed a number of 8.5-isms which slipped into 3.1.18, breaking
              ability to use it with Tcl 8.4.

       [3]    Bugfix Corrected broken build.tcl uninstall.

       [4]    Bugfix Package critcl::class  bumped  to  version  1.1.1.  Fixed  partial  template
              substitution breaking compilation of the generated code.

CHANGES FOR VERSION 3.1.18

       [1]    Feature  (Developer  support).  Merged  pull  request  #96 from sebres/main-direct-
              invoke. Enables direct invokation of the "main.tcl" file for starkits from within a
              dev checkout, i.e. outside of a starkit, or starpack.

       [2]    Feature.  Added  channel types to the set of builtin argument and result types. The
              argument types are for simple channel access, access requiring  unshared  channels,
              and taking the channel fully into the C level, away from Tcl. The result type comes
              in variants for newly  created  channels,  known  channels,  and  to  return  taken
              channels  back  to  Tcl.  The  first  will  register  the  returned  value  in  the
              interpreter, the second assumes that it already is.

       [3]    Bugfix. Issue #96. Reworked the documentation around the argument type  Tcl_Interp*
              to  make its special status more visible, explain uses, and call it out from result
              types where its use will be necessary or at least useful.

       [4]    Feature. Package critcl::class bumped to version 1.1.  Extended with the ability to
              create  a  C  API for classes, and the ability to disable the generation of the Tcl
              API.

       [5]    Bugfix. Merged pull  request  #99  from  pooryorick/master.  Fixes  to  the  target
              directory calculations done by the install code.

       [6]    Merged pull request #94 from andreas-kupries/documentation.  A larger documentation
              cleanup. The main work was done by pooryorick, followed by tweaks done by myself.

       [7]    Extended the test suite with lots of cases based on the examples  for  the  various
              generator  packages.  IOW the new test cases replicate/encapsulate the examples and
              demonstrate that the packages used by the examples generate working code.

       [8]    Bugfix. Issue #95. Changed the field critcl_bytes.s  to  unsigned  char*  to  match
              Tcl's  type. Further constified the field to make clear that read-only usage is the
              common case for it.

       [9]    Bugfix/Feature.  Package  critcl::cutil  bumped  to  version  0.2.   Fixed  missing
              inclusion  of  header  "string.h"  in  "critcl_alloc.h", needed for memcpy in macro
              STREP.  Added macros ALLOC_PLUS and STRDUP.  Moved documentation of STREP... macros
              into proper place (alloc section, not assert).

       [10]   Merged  pull request #83 from apnadkarni/vc-fixes.  Removed deprecated -Gs for MSVC
              builds, and other Windows fixups.

       [11]   Feature. Package critcl::iassoc bumped to version  1.1.   Refactored  internals  to
              generate  an  include  header  for  use  by  .c files.  This now matches what other
              generator packages do.  The template file is inlined and removed.

       [12]   Merged pull request #82 from gahr/home-symlink Modified tests to handle possibility
              of $HOME a symlink.

       [13]   Merged  pull request #81 from gahr/test-not-installed Modified test support to find
              uninstalled critcl packages when running tests. Handles all but critcl::md5.

       [14]   Merged  pull  request  #85  from  snoe925/issue-84  to  fix  Issue   #84   breaking
              installation on OSX.

       [15]   Merged  pull  request  #87  from apnadkarni/tea-fixes to fix Issue #86, broken -tea
              option, generating an incomplete package.

       [16]   Feature.  New  package  critcl::callback  providing  C-level  functions  and   data
              structures to manage callbacks from C to Tcl.

       [17]   Feature. Package critcl::literals bumped to version 1.3.  Added mode +list enabling
              the conversion of multiple literals into a list of their strings.

       [18]   Feature. Package critcl::enum bumped to version 1.1.  Added  basic  mode  handling,
              supporting  tcl  (default) and +list (extension enabling the conversion of multiple
              enum values into a list of their strings).

       [19]   Feature. Package critcl::emap  bumped  to  version  1.2.   Extended  existing  mode
              handling  with +list extension enabling the conversion of multiple emap values into
              a list of their strings.

       [20]   Feature. Extended the set of available types by applying a few  range  restrictions
              to the scalar types (int, long, wideint, double, float).

              Example: int > 0 is now a viable type name.

              This is actually more limited than the description might let you believe.

              See the package reference for the details.

CHANGES FOR VERSION 3.1.17

       [1]    Extension:  Allow  duplicate  arg-  and  result-type  definitions if they are fully
              identical.

       [2]    Bugfix.   The   application   mishandled   the   possibility   of   identical-named
              critcl::tsources.  Possible  because  critcl::tsources  can be in subdirectories, a
              structure which is not retained in the assembled package,  causing  such  files  to
              overwrite  each other and at least one lost. Fixed by adding a serial number to the
              file names in the assembled package.

       [3]    Bugfix in the static scanner which made it loose requirement  information.  Further
              added code to generally cleanup results at the end (removal of duplicates, mainly).

       [4]    Bugfix:  Fixed  issue  #76.   Support installation directories which are not in the
              auto_path.  Without the patch the installed critcl will not find its  own  packages
              and fail. Thank you to Simon Bachmann [https://github.com/lupylucke] for the report
              and patch, and then his patience with me to getting to actually apply it.

       [5]    Bugfix: Fixed issue #75.  Extended critcl::include to now take multiple paths.

       [6]    Added new compatibility package lmap84.

       [7]    Fixed typos in various documentation files.

       [8]    Fixed bug introduced by commit  86f415dd30  (3.1.16  release).  The  separation  of
              critcl::ccode into user and work layers means that location retrieval has to go one
              more level up to find the user location.

       [9]    New supporting package critcl::cutil. Provides common C level facilities useful  to
              packages (assertions, tracing, memory allocation shorthands).

       [10]   Modified  package  critcl  to  make  use  of  the new tracing facilities to provide
              tracing  of  arguments  and  results   for   critcl::ccommand   and   critcl::cproc
              invokations.

       [11]   Modified  packages  critcl  and  critcl::class to provide better function names for
              (class) method tracing.  Bumped package critcl::class to version 1.0.7.

       [12]   Extended the support package critcl::literals with limited configurability.  It  is
              now  able  to  generate code for C-level access to the pool without Tcl types (Mode
              c).  The previously existing functionality is accesssible  under  mode  tcl,  which
              also is the default. Both modes can be used together.

       [13]   Extended  the  support package critcl::emap with limited configurability. It is now
              able to generate code for C-level access to the mapping without Tcl types (Mode c).
              The  previously  existing functionality is accessible under mode tcl, which also is
              the default. Both modes can be used together.

CHANGES FOR VERSION 3.1.16

       [1]    New feature. Extended critcl::cproc's argument handling to allow  arbitrary  mixing
              of required and optional arguments.

       [2]    New feature.  Potential Incompatibility.

              Extended critcl::cproc's argument handling to treat an argument args as variadic if
              it is the last argument of the procedure.

       [3]    New feature. Added two introspection commands, critcl::has-argtype and critcl::has-
              resulttype.   These  enable a user to test if a specific (named) type conversion is
              implemented or not.

       [4]    Added new result type Tcl_Obj*0, with alias object0. The difference to Tcl_Obj*  is
              in the reference counting.

       [5]    Extended  the  command  critcl::argtypesupport  with  new optional argument through
              which  to  explicitly  specify  the  identifier  for  guarding   against   multiple
              definitions.

       [6]    Bugfix:  Fixed  problem  with  the implementation of issue #54 (See 3.1.14). Always
              create  the  secondary  log  file.  Otherwise  end-of-log   handling   may   break,
              unconditionally assuming its existence.

       [7]    Bugfix:  Fixed  problem  with the internal change to the hook HandleDeclAfterBuild.
              Corrected the forgotten critcl::cconst.

       [8]    Debugging aid: Added comment holding the name of  the  result  type  when  emitting
              result conversions.

       [9]    Bugfix:  Fixed  issue  #60.  Unbundled  the package directories containing multiple
              packages. All directories under "lib/" now contain exactly one package.

       [10]   Bugfix: Fixed issue #62, a few dict exists commands operating  on  a  fixed  string
              instead of a variable.

       [11]   Bugfix: Fixed issue #56. Release builders are reminded to run the tests.

       [12]   Bugfix:  Fixed  issue #55. For FreeBSD critcl's platform package now identifies the
              Kernel  ABI  version.  Initialization  of  the  cache  directory  now   also   uses
              platform::identify for the default path, instead of platform::generic.

       [13]   Bugfix:  Fixed issue #58. Simplified the setup and use of md5. Critcl now makes use
              of its own package for md5, using itself to  built  it.  There  is  no  chicken/egg
              problem  with this as the -pkg mode used for this does not use md5. That is limited
              to mode compile & run.

CHANGES FOR VERSION 3.1.15

       [1]    Fixed version number bogosity with 3.1.14.

CHANGES FOR VERSION 3.1.14

       [1]    Fixed issue #36. Added message to target all of  the  Makefile  generated  for  TEA
              mode. Additionally tweaked other parts of the output to be less noisy.

       [2]    Accepted  request  implied  in  issue #54. Unconditionally save the compiler/linker
              build log into key log of the dictionary returned by cresults, and save a  copy  of
              only the execution output in the new key exl ("execution log").

       [3]    Fixed   issue  #53.  Clarified  the  documentation  of  commands  critcl::load  and
              critcl::failed with regard to their results and the throwing of  errors  (does  not
              happen).

       [4]    Fixed issue #48. Modified mode "compile & run" to allow new declarations in a file,
              after it was build, instead of erroring out. The new decls are build  when  needed.
              Mode "precompile" is unchanged and will continue to trap the situation.

       [5]    Fixed issue #52. Updated the local Tcl/Tk headers to 8.4.20, 8.5.13, and 8.6.4.

       [6]    Fixed issue #45. New feature command critcl::cconst.

       [7]    critcl::util:  New  command locate to find a file across a set of paths, and report
              an error when not found. This is  for  use  in  autoconf-like  header-searches  and
              similar configuration tests.

       [8]    Modified  'AbortWhenCalledAfterBuild'  to dump the entire stack (info frame!). This
              should make it easier to determine the location of the troubling declaration.

CHANGES FOR VERSION 3.1.13

       [1]    Merged PR #43. Fixed bug loading adjunct Tcl sources.

       [2]    Fixes in documentation and generated code  of  package  "critcl::enum".  Bumped  to
              version 1.0.1.

       [3]    Fixes in documentation of package "critcl::bitmap".

       [4]    New  package "critcl::emap". In essence a variant or cross of "critcl::bitmap" with
              behaviour like "critcl::enum".

       [5]    Merged PR #49. Fixed documentation typo.

       [6]    Merged PR #46. Fixed documentation typo.

       [7]    Merged PR #47. Fixes to test results to match the accumulated  code  changes.  Also
              made portable across Tcl versions (varying error syntax).

       [8]    New predefined argument- and result-type "wideint" mapping to Tcl_WideInt.

       [9]    New  predefined  argument-type  "bytes"  mapping  to  tuple  of byte-array data and
              length. Note: The existing "bytearray" type (and its aliases) was  left  untouched,
              to keep backward compatibility.

       [10]   Modified  the  internal  interface  between  the Tcl shim and C function underneath
              "critcl::cproc" with respect to the handling of optional  arguments.   An  optional
              argument  "X"  now  induces  the  use of two C arguments, "X" and "has_X".  The new
              argument "has_X" is of boolean (int) type. It is set to true when X is set, and set
              to  false  when  X  has  the default value. C code which cares about knowing if the
              argument is default or not is now able to check that  quickly,  without  having  to
              code  the  default value inside.  NOTE: This change is visible in the output of the
              advanced commands "argcnames", "argcsignature", "argvardecls", and "argconversion".

       [11]   Fixed issue  #50  and  documented  the  availability  of  variable  "interp"  (type
              Tcl_Interp*)  within  "critcl::cinit"  C  code fragments.  Note that while the old,
              undocumented name of the variable, "ip", is still usable, it is deprecated. It will
              be  fully  removed in two releases, i.e. for release 3.1.15.  The variable name was
              changed to be consistent with other code environments.

       [12]   Fixed issue #51. Disabled the generation of #line  directives  for  "critcl::config
              lines  0"  coming from template files, or code generated with them before the final
              value of this setting was known.

       [13]   Fixed  issue  with  handling  of  namespaced  package  names  in  "critcl::iassoc".
              Equivalent to a bug in "critcl::class" fixed for critcl 3.1.1, critcl::class 1.0.1.
              Note: "literals", "enum", "emap", and "bitmap" do not require a fix as they are all
              built on top of "iassoc".

CHANGES FOR VERSION 3.1.12

       [1]    Fixed  issue  42. Clear ::errorInfo immediately after startup to prevent leakage of
              irrelevant (caught) errors into our script and confusing the usage code.

       [2]    Fixed issue 40. Keep the order of libraries, and allow duplicates. Both are  things
              which are occasionally required for proper linking.

       [3]    Extended  the utility package critcl::literals to declare a cproc result-type for a
              pool.

              Further fixed the generated header to handle multiple inclusion.

              Bumped version to 1.1.

       [4]    Fixed issue with utility package critcl::bitmap.

              Fixed the generated header to handle multiple inclusion.

              Bumped version to 1.0.1.

       [5]    Created new utility package critcl::enum for the quick and easy setup  and  use  of
              mappings between C values and Tcl strings.  Built on top of critcl::literals.

       [6]    Added  examples  demonstrating  the  use  of the utility packages critcl::literals,
              critcl::bitmap, and critcl::enum

CHANGES FOR VERSION 3.1.11

       [1]    Fixed issue #37, via pull request #38, with thanks to Jos DeCoster. Information was
              stored into the v::delproc and v::clientdata arrays using a different key than when
              retrieving the same information, thus failing the latter.

       [2]    New convenience command critcl::include for easy inclusion of headers and  other  C
              files.

       [3]    New  command  critcl::make  to  generate a local header of other C files for use by
              other parts of a package through inclusion.

       [4]    New utility package critcl::literals for quick and easy  setup  of  and  access  to
              pools of fixed Tcl_Obj* strings.  Built on top of critcl::iassoc.

       [5]    New  utility  package  critcl::bitmap  for quick and easy setup and use of mappings
              between C bitsets and Tcl lists whose string elements represent that set.  Built on
              top of critcl::iassoc.

CHANGES FOR VERSION 3.1.10

       [1]    Fixed code version numbering forgotten with 3.1.9.

       [2]    Fixed issue #35. In package mode (-pkg) the object cache directory is unique to the
              process, thus we do not need content-hashing  to  generate  unique  file  names.  A
              simple counter is sufficient and much faster.

              Note that mode "compile & run" is not as blessed and still uses content-hasing with
              md5 to ensure unique file names in its per-user object cache.

       [3]    Fixed issue where the ccommand forgot to  use  its  body  as  input  for  the  UUID
              generation. Thus ignoring changes to it in mode compile & run, and not rebuilding a
              library for changed sources. Bug and fix reported by Peter Spjuth.

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 #34. Handle files starting with a dot better.

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

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

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

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-2018 Andreas Kupries