Provided by: critcl_3.1.17+dfsg-1_all bug


       critcl_introduction - Introduction To CriTcl


       Welcome  to the C Runtime In Tcl, CriTcl for short, a system to build C extension packages
       for Tcl on the fly, from C code embedded within Tcl scripts, for  all  who  wish  to  make
       their code go faster.

       CriTcl  started  life as an experiment by Jean-Claude Wippler and was a self-contained Tcl
       package to build C code into a Tcl/Tk extension on the fly. It was  somewhat  inspired  by
       Brian Ingerson's Inline for Perl, but is considerably more lightweight.

       It  is  for  the last 5% to 10% when pure Tcl, which does go a long way, is not sufficient
       anymore. I.e. for

       [1]    when the last bits of performance are needed,

       [2]    access to 3rd party libraries,

       [3]    hiding critical pieces of your library or application, and

       [4]    simply needing features provided only by C.

       The following sections first reference a few related documents which may or may not be  of
       interest  to  you,  depending on if you are just a plain user of the system, trying to get
       and build/install it, or are going deep into  the  internals  for  either  edification  or

       This is followed by an introduction to the modes of operation supported by the system, and
       its general architecture as seen by a user.


       [1]    Critcl - License.

       [2]    Using Critcl

       [3]    Critcl - How To Get The Sources.

       [4]    Critcl - The Installer's Guide.

       [5]    Critcl - Application Package Reference

       [6]    Critcl - Package Reference

       [7]    Critcl - The Developer's Guide.


       CriTcl can be used in three different modes of operation, called

       [1]    Compile & Run, and

       [2]    Generate Package

       [3]    Generate TEA Package

       Of these three Compile & Run came  first  and  is  the  default  when  using  the  package
       directly.  In  that  case the package collects the C fragments, builds them as needed, and
       caches the results for quick reuse when the same code is used in the future again.

       The second mode, Generate Package, was introduced to enable  the  creation  of  (prebuilt)
       deliverable  packages  which  do  not  depend  on  the existence of a build system, i.e. C
       compiler, on the target machine.   This  was  originally  done  through  the  experimental
       Critbind tool, and is now handled by the CriTcl Application, also named critcl.

       Newly  introduced  with  Critcl  version 3 is Generate TEA Package. This mode constructs a
       directory hierarchy from the package which can later be built like a regular TEA  package,
       i.e. using

                .../configure --prefix ...
                make all isntall


       The  system consists of two main layers, as seen in the figure below, plus a support layer
       containing general packages the system uses during operation.

       |Applications    |
       | critcl         |
       | critcl::app    |

       |Core Packages   |
       | critcl         |
       | critcl::util   |

       |Support Packages|
       | stubs::*       |
       | md5, platform  |
       |  ...           |

       [1]    At the top we have an application built on top  of  the  core  packages,  providing
              command  line access to the second and third usage modes, i.e. Generate Package and
              Generate TEA Package.



       [2]    Below that is the core package providing the essential functionality of the system,
              plus various utility packages which make common tasks more convenient.



       [3]    Lastly a layer of supporting packages, mostly external to critcl.

              md5    For  this  pure-Tcl  package  to  be  fast  users  should get one of several
                     possible accelerator packages:

                     [1]    tcllibc

                     [2]    Trf

                     [3]    md5c














       The sources of Critcl, should you have gotten them, contain several larger examples  show-
       casing various aspects of the system. These demonstration packages can all be found in the
       sub-directory "examples/" of the sources.

       Lots of smaller examples can be found in the document Using  CriTcl,  an  introduction  to
       Critcl  by  way  of  a  of examples. These focus more on specific critcl commands than the
       overall picture shown by the large examples mentioned in the previous paragraph.

       The latest changes are found at the top.


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

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

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


       [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

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


       [1]    Fixed version number bogosity with 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

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


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


       [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

              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


       [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

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


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


       [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}-*

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


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


       [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

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


       [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

              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

       [3]    Fixed issue #23.


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


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


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


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


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


       [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

       [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

              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

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


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


       [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 shown by


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


       [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

       [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

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


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


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


       [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

       [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

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


       [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

              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

       [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

              Please see section Package Meta  Data  of  the  critcl  package  documentation  for


       [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

       [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

       [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

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


       Jean Claude Wippler, Steve Landers, Andreas Kupries


       This document, and the package it describes,  will  undoubtedly  contain  bugs  and  other
       problems.   Please report them at  Ideas
       for enhancements you may have for either package, application,  and/or  the  documentation
       are   also   very   welcome   and   should   be  reported  at
       kupries/critcl/issues as well.


       C code, Embedded C Code, code generator, compile & run, compiler, dynamic code generation,
       dynamic   compilation,   generate  package,  linker,  on  demand  compilation,  on-the-fly


       Glueing/Embedded C code


       Copyright (c) Jean-Claude Wippler
       Copyright (c) Steve Landers
       Copyright (c) 2011-2015 Andreas Kupries