critcl_introduction man page on DragonFly

Man page or keyword search:  
man Server   44335 pages
apropos Keyword Search (all sections)
Output format
DragonFly logo
[printable version]

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
       existence of a build system, i.e. C compiler, on	 the  target  machine.
       This was originally done through the experimental Critbind tool, and is
       now handled by the CriTcl Application, also named critcl.

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

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

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

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

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

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

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

	      critcl

	      critcl::app

       [2]    Below that is the core package providing the essential 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
	      returned by cresults, and save a copy of only the execution out‐
	      put 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
	      "interp"	(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
	      DeCoster.	  Information  was  stored  into  the  v::delproc  and
	      v::clientdata arrays using a different key than when  retrieving
	      the same information, thus failing the latter.

       [2]    New  convenience	command	 critcl::include for easy inclusion of
	      headers and other C files.

       [3]    New command critcl::make to generate a local header of  other  C
	      files for use by other parts of a package through inclusion.

       [4]    New utility package critcl::literals for quick and easy setup of
	      and access to pools of fixed Tcl_Obj* strings.  Built on top  of
	      critcl::iassoc.

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

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

       [2]    Fixed  issue #35. In package mode (-pkg) the object cache 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
	      ensure that this set of variables is generated only once, in the
	      wrapper around all the pieces to assemble.

       [2]    Fixed issue #22, the handling of the  command  identifier	 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
	      digest smaller chunks without causing the generation of multiple
	      packages.

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

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

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

       [7]    Extended the API with commands helping developers with the  gen‐
	      eration  of  proper C #line directives. This allows higher-level
	      code generators to generate and  insert  their  own  directives,
	      ensuring	that compile errors in their code are properly 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
	      define custom argument and result types for ::critcl::cproc.

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

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

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

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

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

CHANGES FOR VERSION 3.0.5
       [1]    Fixed bug in the new code for #line pragmas triggered when 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
	      libraries 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
	      options. Simplified the handling	of  bufferoverflowU.lib	 also,
	      making use of the same mechanism and collapsing the two configu‐
	      rations 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
	      assume that the library must be linked when present. This should
	      be no harm if the library	 is  present,  yet  not	 needed.  Just
	      superfluous. We search for the library in the paths specified by
	      the environment variable LIB.

CHANGES FOR VERSION 3
       [1]    The command critcl::platform  was	 deprecated  in	 version  2.1,
	      superceded  by  critcl::targetplatform, yet kept for compatibil‐
	      ity. 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
	      incompatible visible changes above.

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

	      This new option, and -pkg, exclude each other. If both are 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
	      decisions regarding the assembled C code, companion files,  etc.
	      the TEA wrap mode is not in a position to make platform-specific
	      decisions. It has to wrap everything which might conceivably  be
	      needed  when actually building. Hence the static scan.  This has
	      however its own set of problems, namely the inability to	figure
	      out  any	dynamic construction of companion file paths, at least
	      on its own. Thus:

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

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

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

       [8]    Extended the API used by critcl-based packages with the  command
	      critcl::userconfig  for  the  management	of developer-specified
	      custom configuration options, be it their	 use  and/or  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
	      determining the compiler to use to deal with (i.e. remove) paths
	      to  the compiler, compiler file extensions, and compiler options
	      specified after the compiler itself, leaving only the bare  name
	      of the compiler.

       [15]   Extended the code handling the search for preloaded libraries to
	      print the paths it searched, making debugging of a search	 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
	      errors.

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

       [20]   Added a new command critcl::checklink which not  only  tries  to
	      check the environment via compiling the code, but also its 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::include.

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

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

AUTHORS
       Jean Claude Wippler, Steve Landers, Andreas Kupries

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

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

CATEGORY
       Glueing/Embedded C code

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

doc				    3.1.15		critcl_introduction(n)
[top]

List of man pages available for DragonFly

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net