Provided by: critcl_3.1.9-1build1_all bug

NAME

       critcl::app - Critcl - Application Package Reference

SYNOPSIS

       package require Tcl  8.4

       package require critcl::app  ?3.1.8?

       package require critcl  ?2?

       package require platform  ?1.0.2?

       package require cmdline

       ::critcl::app::main commandline

_________________________________________________________________________________________________

DESCRIPTION

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

       This  document is the reference manpage for the critcl::app package. Its intended audience
       are developers working on critcl's internals.  Writers of packages with  embedded  C  code
       can  ignore this document.  If you are in need of an overview of the whole system instead,
       please go and read the Introduction To CriTcl.

       This package resides in the Application Layer of CriTcl.

       *================*
       |Applications    |
       | critcl         |
       | critcl::app    |
       *================*

       +----------------+
       |Core Packages   |
       | critcl         |
       | critcl::util   |
       +----------------+

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

       , implementing the functionality of the CriTcl Application, and  through  this,  the  mode
       generate  package.   The actual application is (only) a shim wrapping around this package.
       It itself is build on top of the core package critcl.

API

       The package exports a single command

       ::critcl::app::main commandline
              The commandline is a list of options and input files,  in  this  order,  with  both
              parts  possibly  empty.   The  exact  set  of options supported, their meaning, and
              interaction is detailed in section Options below.  For a  larger  set  of  examples
              please see section "Building Critcl Packages" in the document about Using CriTcl.

OPTIONS

       The following options are understood

       -v

       --version
              These options cause critcl to print its version to stdout and then exit.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

              all    This mode activates both memory and symbols.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

              Examples:

                ... -pkg ... foo

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

                ... -pkg ... foo bar.tcl

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

                ... -pkg ... foo.tcl

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

                ... -pkg ... foo.so bar.tcl

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

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

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

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

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

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

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

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

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

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

              Examples:

                ... -tea ... foo

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

                ... -tea ... foo bar.tcl

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

                ... -tea ... foo.tcl

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

                ... -tea ... foo.so bar.tcl

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

       -with-name value
              This option sets the value of the custom build configuration option name to value.

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

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

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

       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

PACKAGE STRUCTURE

       Packages generated by critcl have the following basic structure:

              <TOP>
              +- pkgIndex.tcl
              +- critcl-rt.tcl
              +- license.terms (optional)
              |
              +- tcl (optional)
              |  +- <tsources files>
              |
              +- <platform>
                 +- <shared library>

       Notes

       [1]    The file "pkgIndex.tcl" is the  standard  package  index  file  expected  by  Tcl's
              package  management.  It  is sourced during a search for packages, and declares the
              package to Tcl with its files, and how to handle them.

       [2]    The file "critcl-rt.tcl" is a helper  file  containing  the  common  code  used  by
              "pkgIndex.tcl" to perform its tasks.

       [3]    The  file  "license.terms"  is  optional and appears only if the ".critcl" file the
              package is generated from used  the  command  critcl::license  to  declare  package
              author and license.

       [4]    All files declared with the command critcl::tsources are put into the sub-directory
              "tcl".

       [5]    The shared library generated  by  critcl  is  put  into  a  platform-specific  sub-
              directory.

       The  whole  structure, and especially the last point, enable us to later merge the results
       (for the same package, and version) for multiple target platforms into a single  directory
       structure  without  conflict,  by  simply copying the top directories over each other. The
       only files which can conflict are in the <TOP> and "tcl" directories,  and  for  these  we
       know that they are identical across targets. The result of such a merge would look like:

              <TOP>
              +- pkgIndex.tcl
              +- critcl-rt.tcl
              +- license.terms (optional)
              |
              +- tcl (optional)
              |  +- <tsources files>
              |
              +- <platform1>
              |  +- <shared library1>
              +- <platform2>
              |  +- <shared library2>
              ...
              +- <platformN>
                 +- <shared libraryN>

CHANGES FOR VERSION 2.1

       [1]    Fixed  bug  where  critcl::tsources  interpreted  relative paths as relative to the
              current working directory instead of relative  to  the  ".critcl"  file  using  the
              command, as all other commands of this type do.

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

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

       [4]    Fixed the critcl application's interference with the "compile & run"  result  cache
              in  -pkg  mode  by  having  it  use  a  wholly  separate (and by default transient)
              directory for that mode.

       [5]    Fixed bug where changes to a ".critcl" file did not result in a  rebuild  for  mode
              "compile & run". All relevant API commands now ensure UUID changes.

       [6]    Fixed bug in the backend handling of critcl::debug where the companion c-sources of
              a ".critcl" file were not compiled with debug options, although the ".critcl"  file
              was.

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

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

       [9]    Fixed long-standing bug in the handling of namespace qualifiers in the command name
              argument  of  critcl::cproc  and  critcl::ccommand. It is now possible to specify a
              fully qualified command name without issues.

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

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

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

       [13]   Extended  critcl::failed  to  be  callable  more than once in a ".critcl" file. The
              first call forces the build, if it was not done already, to get the result. Further
              calls return the cached result of the first call.

       [14]   Extended  the  handling  of  environment  variable  CC  in the code determining the
              compiler to use to deal with (i.e. remove) paths to  the  compiler,  compiler  file
              extensions,  and compiler options specified after the compiler itself, leaving only
              the bare name of the compiler.

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

       [16]   A  new  command  critcl::tcl  can  be  used to declare the version of Tcl minimally
              needed to build and run the ".critcl" file and package.  Defaults  to  8.4  if  not
              declared.  Extended  critcl  to have the stubs and headers for all of Tcl 8.4, 8.5,
              and 8.6.

       [17]   A new command critcl::load forces the build and load of a ".critcl" file.  This  is
              the official way for overriding critcl's default lazy-build-&-load-on-demand scheme
              for mode "compile & run".

              Note that after using critcl::load / critcl::failed in a ".critcl" file it  is  not
              possible to use critcl commands in that file anymore. Doing so will throw an error.

       [18]   Extended  the  generation  of  '#line'  pragmas to use info frame (if available) to
              provide the C compiler with exact line numbers into  the  ".critcl"  file  for  the
              reporting of warnings and errors.

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

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

       [21]   Added  a  new  command critcl::msg for messaging, like command critcl::error is for
              error reporting. Likewise this is a hook a  user  of  the  package  is  allowed  to
              override.  The default implementation, used by mode compile & run does nothing. The
              implementation for mode generate package prints the message to stdout.

              Envisioned use is for the reporting of  results  determined  by  critcl::check  and
              critcl::checklink during building, to help with debugging when something goes wrong
              with a check.

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

              [1]    critcl::argnames

              [2]    critcl::argcnames

              [3]    critcl::argcsignature

              [4]    critcl::argvardecls

              [5]    critcl::argconversion

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

       [23]   Extended the critcl package to intercept package provide and  record  the  file  ->
              package  name  mapping. Plus other internal changes now allow the use of namespaced
              package names while still using proper path names and init function.

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

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

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

CHANGES FOR VERSION 3

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

       [2]    The  command  critcl::compiled  was  kept  with  in  version  2.1 with semantics in
              contradiction to its, for  compatibility.  This  contradiction  has  been  removed,
              changing the visible semantics of the command to be in line with its name.

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

       [4]    Extended the application package with code handling a new option  -tea.  Specifying
              this option invokes a special mode where critcl generates a TEA package, i.e. wraps
              the input into a directory hierarchy  and  support  files  which  provide  it  TEA-
              lookalike buildsystem.

              This  new option, and -pkg, exclude each other. If both are specified the last used
              option takes precedence.

              The generated package directory hierarchy is mostly self-contained, but not  fully.
              It  requires not only a working installation of Tcl, but also working installations
              of the packages md5 and cmdline. Both of these are provided by the  Tcllib  bundle.
              Not  required,  but recommended to have installed are any of the packages which can
              accelerate md5's operation, i.e. cryptkit, tcllibc, or Trf.

       [5]    Extended the critcl package with a new command critcl::scan taking the  path  to  a
              ".critcl"  file,  statically scanning it, and returning license, version, a list of
              its companion files, list of imported APIs, and list of developer-specified  custom
              configuration  options.  This data is the foundation for the TEA wrapping described
              above.

              Note that this is a static scan. While the other build modes can (must) execute the
              ".critcl" file and make platform-specific decisions regarding the assembled C code,
              companion files, etc. the TEA wrap mode is not in  a  position  to  make  platform-
              specific  decisions.  It  has  to wrap everything which might conceivably be needed
              when actually building. Hence the static scan.  This has however  its  own  set  of
              problems,  namely the inability to figure out any dynamic construction of companion
              file paths, at least on its own. Thus:

       [6]    Extended the API used by critcl-based packages with the command critcl::owns. While
              this  command  is  ignored  by the regular build modes the static scanner described
              above takes its arguments as the names of companion files which have to be  wrapped
              into  the  TEA  package  and  could  not  be figured by the scanner otherwise, like
              because of dynamic paths to  critcl::tsources,  critcl::csources,  getting  sourced
              directly, or simply being adjunct datafiles.

       [7]    Extended the API used by critcl-based packages with the command critcl::api for the
              management of stubs tables, be it their use, and/or declaration and export.

              Please see section Stubs Table Management of the critcl package  documentation  for
              details.

       [8]    Extended  the API used by critcl-based packages with the command critcl::userconfig
              for the management of developer-specified custom configuration options, be it their
              use and/or declaration.

              Please  see  section Custom Build Configuration of the critcl package documentation
              for details.

       [9]    Extended   the   API   used   by   critcl-based   packages   with   the    commands
              critcl::description,    critcl::summary,    critcl::subject,    critcl::meta,   and
              critcl::buildrequirement for the declaration of  TEApot  meta  data  for/about  the
              package.

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

CHANGES FOR VERSION 3.0.1

       [1]    Bugfixes all around. In detail:

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

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

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

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

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

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

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

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

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

CHANGES FOR VERSION 3.0.2

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

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

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

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

CHANGES FOR VERSION 3.0.3

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

CHANGES FOR VERSION 3.0.4

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

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

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

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

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

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

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

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

CHANGES FOR VERSION 3.0.5

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

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

CHANGES FOR VERSION 3.0.6

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

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

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

CHANGES FOR VERSION 3.0.7

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

CHANGES FOR VERSION 3.1

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

CHANGES FOR VERSION 3.1.1

       [1]    Bugfixes all around. In detail:

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

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

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

CHANGES FOR VERSION 3.1.2

       [1]    Enhancement. In detail:

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

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

CHANGES FOR VERSION 3.1.3

       [1]    Enhancement. In detail:

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

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

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

CHANGES FOR VERSION 3.1.4

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

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

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

CHANGES FOR VERSION 3.1.5

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

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

CHANGES FOR VERSION 3.1.6

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

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

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

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

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

       [3]    Fixed issue #23.

CHANGES FOR VERSION 3.1.7

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

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

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

CHANGES FOR VERSION 3.1.8

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

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

CHANGES FOR VERSION 3.1.9

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

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

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

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

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

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

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

AUTHORS

       Jean Claude Wippler, Steve Landers, Andreas Kupries

BUGS, IDEAS, FEEDBACK

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

KEYWORDS

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

CATEGORY

       Glueing/Embedded C code

COPYRIGHT

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