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

FreeBSD Manual Pages

  
 
  

home | help
critcl_introduction(n)	   C Runtime In	Tcl (CriTcl)	critcl_introduction(n)

______________________________________________________________________________

NAME
       critcl_introduction - Introduction To CriTcl

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.

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

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

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

       [2]    access to	3rd party libraries,

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

       [4]    simply needing features provided only by C.

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

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

RELATED	DOCUMENTS
       [1]    Critcl - License.

       [2]    Using Critcl

       [3]    Critcl - How To Get The Sources.

       [4]    Critcl - The Installer's Guide.

       [5]    Critcl - Application Package Reference

       [6]    Critcl - Package Reference

       [7]    Critcl - The Developer's Guide.

MODES OF OPERATION/USE
       CriTcl can be used in three different modes of operation, called

       [1]    Compile _	Run, and

       [2]    Generate Package

       [3]    Generate TEA Package

       Of  these  three	Compile	_ Run came first and is	the default when using
       the package directly. In	that case the package  collects	 the  C	 frag-
       ments,  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  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

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

       +----------------+
       |Applications	|
       | critcl		|
       | critcl::app	|
       +----------------+

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

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

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

	      critcl

	      critcl::app

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

	      critcl

	      critcl::util

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

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

		     [1]    tcllibc

		     [2]    Trf

		     [3]    md5c

	      cmdline

	      platform

	      stubs::container

	      stubs::reader

	      stubs::writer

	      stubs::gen

	      stubs::gen::init

	      stubs::gen::header

	      stubs::gen::decl

	      stubs::gen::macro

	      stubs::gen::slot

	      stubs::gen::lib

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

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

       The latest changes are found at the top.

CHANGES	FOR VERSION 3.1.15
       [1]    Fixed version number bogosity with 3.1.14.

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

       [2]    Accepted request implied in issue	#54. Unconditionally save  the
	      compiler/linker  build  log  into	 key log of the	dictionary 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.

CHANGES	FOR VERSION 3.1.13
       [1]    Merged PR	#43. Fixed bug loading adjunct Tcl sources.

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

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

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

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

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

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

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

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

       [10]   Modified the internal interface between the Tcl shim and C 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
	      known.

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

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

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

CHANGES	FOR VERSION 3.1.11
       [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
	      critcl::iassoc.

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

CHANGES	FOR VERSION 3.1.10
       [1]    Fixed code version numbering forgotten with 3.1.9.

       [2]    Fixed  issue #35.	In package mode	(-pkg) the object cache	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.

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

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

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

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

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

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

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

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

CHANGES	FOR VERSION 3.1.6
       [1]    Fixed issue #21. While the multi-definition  of  the  stub-table
	      pointer  variables was ok	with for all the C linkers seen	so far
	      C++ linkers did not like this at all. Reworked the code  to  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.

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

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

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

CHANGES	FOR VERSION 3.1.3
       [1]    Enhancement. In detail:

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

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

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

CHANGES	FOR VERSION 3.1.2
       [1]    Enhancement. In detail:

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

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

CHANGES	FOR VERSION 3.1.1
       [1]    Bugfixes all around. In detail:

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

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

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

CHANGES	FOR VERSION 3.1
       [1]    Added a new higher-level package critcl::iassoc.

	      This  package  simplifies	 the creation of code associating data
	      with an interpreter via Tcl's Tcl_(Get|Set)AssocData() APIs. The
	      user can concentrate on his data while all the necessary 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-
	      mand.

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

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

	      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.

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

CHANGES	FOR VERSION 3.0.6
       [1]    Fixed github issue 10. The critcl	 application  now  delivers  a
	      proper  exit  code (1) on	build failure, instead of always 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
	      README.md	shown by github

CHANGES	FOR VERSION 3.0.5
       [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.

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

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

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

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

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

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

CHANGES	FOR VERSION 3.0.1
       [1]    Bugfixes all around. In detail:

       [2]    Fixed  recording	of Tcl version requirements. Keep package name
	      and version together, unbreaking generated meta data and	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.

CHANGES	FOR VERSION 3
       [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
	      buildsystem.

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

	      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.

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 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  &
	      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 er-
	      rors.

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

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

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

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

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

AUTHORS
       Jean Claude Wippler, Steve Landers, Andreas Kupries

BUGS, IDEAS, FEEDBACK
       This  document,	and the	package	it describes, will undoubtedly contain
       bugs and	other problems.	 Please	report them at	https://github.com/an-
       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	https://github.com/andreas-ku-
       pries/critcl/issues as well.

KEYWORDS
       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

CATEGORY
       Glueing/Embedded	C code

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

doc				    3.1.15		critcl_introduction(n)

NAME | DESCRIPTION | RELATED DOCUMENTS | MODES OF OPERATION/USE | SYSTEM ARCHITECTURE | EXAMPLES | CHANGES FOR VERSION 3.1.15 | CHANGES FOR VERSION 3.1.14 | CHANGES FOR VERSION 3.1.13 | CHANGES FOR VERSION 3.1.12 | CHANGES FOR VERSION 3.1.11 | CHANGES FOR VERSION 3.1.10 | CHANGES FOR VERSION 3.1.9 | CHANGES FOR VERSION 3.1.8 | CHANGES FOR VERSION 3.1.7 | CHANGES FOR VERSION 3.1.6 | CHANGES FOR VERSION 3.1.5 | CHANGES FOR VERSION 3.1.4 | CHANGES FOR VERSION 3.1.3 | CHANGES FOR VERSION 3.1.2 | CHANGES FOR VERSION 3.1.1 | CHANGES FOR VERSION 3.1 | CHANGES FOR VERSION 3.0.7 | CHANGES FOR VERSION 3.0.6 | CHANGES FOR VERSION 3.0.5 | CHANGES FOR VERSION 3.0.4 | CHANGES FOR VERSION 3.0.3 | CHANGES FOR VERSION 3.0.2 | CHANGES FOR VERSION 3.0.1 | CHANGES FOR VERSION 3 | CHANGES FOR VERSION 2.1 | AUTHORS | BUGS, IDEAS, FEEDBACK | KEYWORDS | CATEGORY | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=critcl_introduction&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help