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

NAME

       critcl_introduction - Introduction To CriTcl

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.

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

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

RELATED DOCUMENTS

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

MODES OF OPERATION/USE

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

       [1]    Compile & Run, and

       [2]    Generate Package

       [3]    Generate TEA Package

       Compile  &  Run  was  the original mode and is the default for critcl_pkg.  Collects the C
       fragments from the Critcl script, builds them as needed, and caches the results to improve
       load times later.

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

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

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

SYSTEM ARCHITECTURE

       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.

              critcl

              critcl::app

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

              critcl

              critcl::util

       [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

              cmdline

              platform

              stubs::container

              stubs::reader

              stubs::writer

              stubs::gen

              stubs::gen::init

              stubs::gen::header

              stubs::gen::decl

              stubs::gen::macro

              stubs::gen::slot

              stubs::gen::lib

EXAMPLES

       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.

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