Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
critcl::app(n)		   C Runtime In	Tcl (CriTcl)		critcl::app(n)


       critcl::app - Critcl - Application Package Reference

       package require Tcl  8.4

       package require critcl::app  ?3.1.18?

       package require critcl  ?2?

       package require platform	 ?1.0.2?

       package require cmdline

       ::critcl::app::main commandline


       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 im-
       prove performance by rewriting in C those routines that are performance

       This document is	the reference manpage for the critcl::app package. Its
       intended	audience are developers	working	on critcl's internals.	 These
       commands	are not	needed to simply write a Critcl	script.	 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.

       The package exports a single command

       ::critcl::app::main commandline
	      The commandline is a list	of zero	or more	 options  followed  by
	      zero or more Critcl script files.	 By default, the Critcl	script
	      files are	build and the results cached.	This cuts down on  the
	      time  needed  to	load the package.  The last occurrence of -pkg
	      and -tea,	if provided,  selects  the  corresponding  alternative
	      mode  of	operations.   For  a larger set	of examples please see
	      section "Building	Critcl Packages" in the	document  about	 Using

       The options are:

       The following options are understood:


	      Print the	version	to stdout and exit.

       -I path
	      Arranges	for  the compiler to search path for headers.  Uses of
	      this option are cumulative.

       Ignored when generating a TEA package (see option -tea below).

       -L path
	      Arranges for the linker to search	path.  Uses of this option are

       Ignored when generating a TEA package (see option -tea below).

       -cache path
	      Sets  path  as the directory to use as the result	cache. The de-
	      fault is	"~/.critcl/_platform_",	 or  "~/.critcl/_pid_._epoch_"
	      when generating a	package.  See option -pkg, below.

       Ignored when generating a TEA package (see option -tea below).

       -clean Arranges for all files and directories in	the result cache to be
	      deleted before compilation begins.

	      Ignored when generating a	package	because	this mode  starts  out
	      with a unique and	empty result cache.  See option	-pkg, below.

       Ignored when generating a TEA package (see option -tea below).

       -config path
	      Provides	a  custom configuration	file.  By default a configura-
	      tion included in the system core is used.	 When specified	multi-
	      ple times	the last value is used.

       Ignored when generating a TEA package (see option -tea below).

       -debug mode
	      Activates	one of the following debugging modes:

	      memory Track and report memory allocations made by the Tcl core.

		     Compile all ".c" files with debugging symbols.

	      all    Both memory and symbols.

       Ignored when generating a TEA package (see option -tea below).  Uses of
       this option are cumulative.

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

       Validated only if one of	the input files	for the	Critcl script actually
       defines and uses	a custom build configuration option with that name.

       Ignored when generating a TEA package (see option -tea below).

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

       Validated only if one of	the input files	for the	Critcl script actually
       defines and uses	a custom build configuration option with that name.

       Ignored when generating a TEA package (see option -tea below).

       -force Forces compilation even if a shared library for the file already
	      exists.  Unlike cleaning the cache, this is lazy in the destruc-
	      tion of files and	only affects relevant files.

	      Ignored when generating a	 package  (see	option	-pkg,  below),
	      which starts out with a unique and empty result cache.

       Ignored when generating a TEA package (see option -tea below).

       -help  Prints  a	 short	description of command line syntax and options
	      and then exits the application.

       -keep  Causes the system	to cache compiled ".c" files.	Also  prevents
	      the  deletion  of	 the  unique result cache used by the run when
	      generating a package (see	option -pkg below), Intended  for  de-
	      bugging  of  critcl itself, where	it may be necessary to inspect
	      the generated C code.

       Ignored when generating a TEA package (see option -tea below).

       -libdir directory
	      Adds directory to	the list of directories	 the  linker  searches
	      for  libraries  in (like -L).  With -pkg,	generated packages are
	      saved in directory.  When	 specified  multiple  times  the  last
	      value  is	 used.	The default is "lib", resolved relative	to the
	      current working directory.

       -includedir directory
	      Adds directory to	the list of directories	the compiler  searches
	      for  headers  in.	With -pkg, generated header files are saved in
	      directory.  Uses of this option are cumulative.  The last	 value
	      is  used as the destination for generated	header files.  The de-
	      fault is the relative directory "include", resolved relative  to
	      the current working directory.

       Ignored when generating a TEA package (see option -tea below).

       -pkg   Generates	 a  package from the Critcl script files.  Input files
	      are processed first as usual, but	are then bundled into a	single
	      library,	with  additional  generated  files to form the library
	      into a standard Tcl package.

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

	      Options  -clean  and  -force are ignored.	-libdir	is relevant in
	      both this	and -tea mode.

	      The basename of the first	file is	the name  of  the  package  to
	      generate.	 If  its  file	extension  indicates  a	shared library
	      (".so", ".sl", ".dylib", and ".dll") it is also removed from the
	      set  of  input files. Each Critcl	script file is kept as part of
	      the input. A single file without a suffix	is  assumed  to	 be  a
	      Critcl  script.  A  file without a suffix, but other input files
	      following	is treated like	the name of a shared  library  proper,
	      and removed from the set of input	files.


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

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

       -show  Prints the configuration of the chosen target to stdout and then
	      exits.  Set -target, below.

	      Prints the whole chosen configuration file to  stdout  and  then
	      exits.  See -config, above.

       -target name
	      Overrides	the default choice of build target.  Only the last oc-
	      currence of this option is used.	The named target must exist in
	      the  chosen configuration	file.  Use -targets (see below)	to get
	      a	list of	the acceptable targets.	 Use  -config  to  select  the
	      configuration file.

       Ignored when generating a TEA package (see option -tea below).

	      Prints  the list of all known targets from the chosen configura-
	      tion file	to stdout and then exits.  Use -config to  select  the
	      configuration file.

       -tea   Like -pkg, except	no binaries are	generated. Creates a directory
	      hierarchy	containing the Critcl script, its companion files, and
	      a	 TEA-conformant	 build	system with most of the	needed support
	      code, including copies of	the critcl packages.

	      If both -pkg and -tea are	specified the last occurrence wins.

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

	      The basename of the first	file is	the name  of  the  package  to
	      generate.	 If  its  file	extension  indicates  a	shared library
	      (".so", ".sl", ".dylib", and ".dll") it is also removed from the
	      set  of  input files. Each Critcl	script file is kept as part of
	      the input. A single file without a suffix	is  assumed  to	 be  a
	      Critcl  script.  A  file without a suffix, but other input files
	      following	is treated like	the name of a shared  library  proper,
	      and removed from the set of input	files.


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

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

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

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

       Ignored when generating a TEA package (see option -tea below).

       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  cre-
       ation of	(prebuilt) deliverable packages	which do not depend on the ex-
       istence 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

       Packages	generated by critcl have the following basic structure:

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


       [1]    The file "pkgIndex.tcl" is the standard package index  file  ex-
	      pected  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 tar-
       get 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:

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

       The latest changes are found at the top.

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

       [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 par-
	      tial template substitution breaking compilation of the generated

       [1]    Feature  (Developer  support).  Merged pull request #96 from se-
	      bres/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 vari-
	      ants 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	 argu-
	      ment  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	poory-
	      orick, 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_al-
	      loc.h",  needed  for  memcpy  in	macro STREP.  Added macros AL-
	      LOC_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 dep-
	      recated -Gs for MSVC builds, and other Windows fixups.

       [11]   Feature. Package critcl::iassoc bumped to	version	 1.1.	Refac-
	      tored  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	 func-
	      tions 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 ba-
	      sic 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 conver-
	      sion 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, dou-
	      ble, float).

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

	      This is actually more limited than the description might let you

	      See the package reference	for the	details.

       [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  as-
	      sembled  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 in-
	      formation. 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 Si-
	      mon Bachmann [] for the  report  and
	      patch,  and then his patience with me to getting to actually ap-
	      ply 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

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

       [10]   Modified package critcl to make use of the new  tracing  facili-
	      ties   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  con-
	      figurability. 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  config-
	      urability. It is now able	to generate code for C-level access to
	      the mapping without Tcl types (Mode c). The previously  existing
	      functionality  is	 accessible  under mode	tcl, which also	is the
	      default. Both modes can be used together.

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

       [2]    New feature.  Potential Incompatibility.

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

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

       [4]    Added new	result type Tcl_Obj*0, with alias object0. The differ-
	      ence 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 Han-
	      dleDeclAfterBuild. 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 con-
	      taining multiple packages. All directories under "lib/" now con-
	      tain exactly one package.

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

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

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

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

       [1]    Fixed version number bogosity with 3.1.14.

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

       [2]    Accepted request implied in issue	#54. Unconditionally save  the
	      compiler/linker  build  log  into	 key log of the	dictionary re-
	      turned 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 dec-
	      larations	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 loca-
	      tion of the troubling declaration.

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

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

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

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

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

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

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

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

       [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 func-
	      tion  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 "in-
	      terp"  (type  Tcl_Interp*)  within  "critcl::cinit" C code frag-
	      ments.  Note that	while the old, undocumented name of the	 vari-
	      able,  "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

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

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

       [2]    Fixed issue 40. Keep the order of	libraries,  and	 allow	dupli-
	      cates.  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

       [1]    Fixed issue #37, via pull	request	#38, with thanks  to  Jos  De-
	      Coster.	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

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

       [1]    Fixed code version numbering forgotten with 3.1.9.

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

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

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

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

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

       [3]    Fixed  issue #29.	Replaced the use of raw	"cheaders" information
	      in the processing	of "cdefines" with the proper  include	direc-
	      tives 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 defini-
	      tions 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

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

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

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

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

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

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

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

       [1]    Fixed issue #21. While the multi-definition  of  the  stub-table
	      pointer  variables was ok	with for all the C linkers seen	so far
	      C++ linkers did not like this at all. Reworked the code  to  en-
	      sure  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	 argu-
	      ments  of	critcl::ccommand, critcl::cproc, and critcl::cdata. We
	      now properly allow any Tcl identifier and	generate proper	inter-
	      nal 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::ccom-
	      mand, and	critcl::cproc.

       [3]    Fixed issue #23.

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

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

       [1]    Bugfix in	package	critcl::class. Generate	a dummy	field  in  the
	      class  structure	if  the	 class has no class variables. Without
	      this change the structure	would be empty,	and a number  of  com-
	      pilers 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

       [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

       [3]    Added new	methods	critcl::argtypesupport	and  ::critcl::argsup-
	      port  to	define and use additional supporting code for an argu-
	      ment type, here used by "pstring"	above to define	the  necessary

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

       [1]    Enhancement. In detail:

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

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

       [1]    Bugfixes all around. In detail:

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

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

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

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

	      This  package  simplifies	 the creation of code associating data
	      with an interpreter via Tcl's Tcl_(Get|Set)AssocData() APIs. The
	      user can concentrate on his data while all the necessary boiler-
	      plate 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  defini-
	      tion  with class-	and instance-variables and -methods similar to
	      a	TclOO class, with all the necessary boilerplate	C code to sup-
	      port 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 cur-
	      rently 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	gener-
	      ate the same type	of C identifiers as critcl itself.

	      The new package critcl::class (see above)	is a user of this com-

       [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 di-
	      gest smaller chunks without causing the generation  of  multiple

       [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

	      The new package critcl::class (see above)	is a user of these fa-

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

	      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  de-
	      fine custom argument and result types for	::critcl::cproc.

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

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

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

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

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

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

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

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

       [2]    Fixed github issue 11. Now using /LIBPATH	instead	of -L on  Win-
	      dows (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 li-
	      braries in preference over static. critcl	 handles  it  now,  as
	      older GNU	ld's do	not understand it, nor the various vendor-spe-
	      cific linkers.

       [4]    Fixed github issue #12. Critcl now  determines  the  version  of
	      MSVC in use and uses it to switch	between	various	link debug op-
	      tions. Simplified	the handling of	bufferoverflowU.lib also, mak-
	      ing  use of the same mechanism and collapsing the	two configura-
	      tions 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	embed-
	      ded documentation, and diagrams, and to generate a release.

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

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

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

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

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

       [1]    Bugfixes all around. In detail:

       [2]    Fixed  recording	of Tcl version requirements. Keep package name
	      and version together, unbreaking generated meta data and	gener-
	      ated 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 instal-
	      lation 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  as-
	      sume  that  the library must be linked when present. This	should
	      be no harm if the	library	is present, yet	not needed.  Just  su-
	      perfluous.  We  search for the library in	the paths specified by
	      the environment variable LIB.

       [1]    The command critcl::platform was deprecated in version 2.1,  su-
	      perceded	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 con-
	      tradiction 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 in-
	      compatible 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

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

	      The  generated  package  directory hierarchy is mostly self-con-
	      tained, but not fully. It	requires not only a working  installa-
	      tion  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 tak-
	      ing 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 config-
	      uration  options.	 This data is the foundation for the TEA wrap-
	      ping described above.

	      Note that	this is	a static scan. While the other build modes can
	      (must) execute the ".critcl" file	and make platform-specific de-
	      cisions 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  ad-
	      junct 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  declara-

	      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 docu-
	      mentation	for details.

       [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 sepa-
	      rate (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-win-
	      dows platforms.

       [9]    Fixed long-standing bug in the handling of namespace  qualifiers
	      in  the command name argument of critcl::cproc and critcl::ccom-
	      mand. 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 de-
	      termining	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	 fail-
	      ure 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  &

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

       [19]   Extended critcl::check  with  logging  to	 help  with  debugging
	      build-time  checks  of  the  environment,	plus an	additional op-
	      tional 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 link-

       [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	imple-
	      mentation,  used	by mode	compile	_ run does nothing. The	imple-
	      mentation	for mode generate package prints the message  to  std-

	      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	 pack-
	      age 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::in-

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

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

       Jean Claude Wippler, Steve Landers, Andreas Kupries

       This  document,	and the	package	it describes, will undoubtedly contain
       bugs and	other problems.	 Please	report them at
       dreas-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
       pries/critcl/issues as well.

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

       Glueing/Embedded	C code

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

doc				    3.1.18			critcl::app(n)


Want to link to this manual page? Use this URL:

home | help