This is a first cut at some documentation for [CriTcl].  It will hopefully improve over time.
----
'''::critcl::cinit text exts'''

inject $text C code as is, to be executed at extension-init time
inject $exts C code as is, in a different place
(''sets code($file,init) $text and code($file,ext) $exts'')

'''::critcl::ccode text'''

inject $text C code as is (#includes, #defines, common defs, etc)
at the top of the generated code

'''::critcl::cdata name anydata'''

Creates a proc [[name]] which when called will return anydata (as byte array)

'''::critcl::cproc name adefs rtype body'''

Define a C procedure which can be called from Tcl
cproc lets you define a C proc $name, with C code as $body.
Args ($adefs) and return values ($rtype) must be typed.

There are no default args or ways to pass more sophisticated data items than
int/long/float/double/char* for now.

The return type can be ''string'', meaning it's a Tcl_Alloc'ed char* which
will at some point be Tcl_Free'd.

You can also use Tcl_Obj* args (no refcount change),
or return it (in which case it will be decref'ed).

If the first parameter to a cproc has type ''Tcl_Interp*'', that'll be passed in.

Lastly, if the return type is ''ok'', then an int return code of type TCL_OK/TCL_ERROR
is expected and will be processed as usual (errors must set the result, so
it is most likely that you'll also want to specify the Tcl_Interp* arg).

'''adef''': 

   * Tcl_Interp*
   * int
   * long
   * float
   * double
   * char*
   * Tcl_Obj*
   * void*

'''rtype''':

   * void -
   * ok -
   * int -
   * long -
   * float -
   * double -
   * char* - TCL_STATIC char*
   * string - TCL_DYNAMIC char*
   * dstring - TCL_DYNAMIC char*
   * vstring - TCL_VOLATILE char* 
   * default - Tcl_Obj*

'''::critcl::ccommand name anames {-clientdata data} {-delproc proc} args'''

Connects code to the Tcl_CreateObjCommand without further wrapping
ties code to the Tcl_CreateObjCommand without further wrapping

   -clientdata:   client data to be passed
   -delproc:   client delete process

anames {clientdata interp objc objv} are the default argument names.

'''::critcl::csources file ...'''

Additional source files passed to the compiler on the cmd line
(''sets code($file,srcs) $args'')

'''::critcl::cheaders file ...'''

set up file(s) to be available in compiles (also: "dir/*.h")
If "critcl::cheaders -g" is given, then the output file is not stripped
and the "-DNDEBUG" flag is not added to the gcc command line.
(''sets code($file,hdrs) $args'')

'''::critcl::clibraries file ...'''

additional libraries (args such as "-l..." are passed on as is)
(''sets code($file,libs) $args'')

----
'''::critcl::failed'''

check if the C compile failed

'''::critcl::done'''

stub - does nothing

'''::critcl::tk'''

configures tk 1

'''::critcl::cache'''

returns the [CriTcl Cache] directory for the current platform

'''::critcl::tsources'''

does nothing

'''::critcl::platform'''

return a platform descriptor ($OS-$machine)
of the platform CriTcl is being run on

'''::critcl::compiling'''

check that we can indeed run a compiler

'''::critcl::sharedlibext'''

returns the shared library extension for the target platform.

'''::critcl::scripting'''

inverse of [[::critcl::compiling]] - we can't run a compiler
----
'''::critcl::config option value'''

   * general format of command to set an option to a value

'''::critcl::config option'''

   * returns the current value of an option

'''::critcl::config outdir''' some_dir_name

   * the compiled library will be saved for permanent use if the outdir option is set (in which case rebuilds will no longer be automatic).  Default value "" causes library to be saved to the user's cache.

'''::critcl::config keepsrc''' 1

   * the generated source will be kept (default value 0 causes source to be deleted)

'''::critcl::config appinit''' some_value

   * no meaning (default value "")

'''::critcl::config force''' 1

   * force recompilation. (default value 0 causes cached files to be used if available)

'''::critcl::config I''' some_value

   * if non-empty, add -Isome_value to command line
   * default value is ""

'''::critcl::config L''' some_value

   * no meaning (default value "")

'''::critcl::config tk''' 1

   * compile for Tk (default value 0 compiles without Tk)

'''::critcl::config language''' some_value

   * if non-empty, add '-x some_value' to the gcc options, causing it to interpret source files as written in the programming language specified by "some_value"
   * default value "" causes '-x none' to be added to the gcc options, so files are interpreted according to their file name suffix, as if -x is not used at all

'''::critcl::config lines''' some_value

   * use the #line preprocessor directive in the generated C source
   * default value 1 switches this feature on; value 0 switches it off
----
'''::critcl::config combine''' some_value

Adjust compiler/linker options to produce different types of binary output file.

some_value = ""
   * ''(the default value of combine)''
   * gcc -shared -DUSE_TCL_STUBS -fPIC
   * ''with additional optimisation options "-O2 -DNDEBUG -Wl,-s" if '-g' is not specified (?) among the headers''
   * use shared library filename suffix (*.so, *.dll);
some_value = dynamic
   * gcc -r -nostdlib -DUSE_TCL_STUBS -fPIC
   * use *_pic.o filename suffix
some_value = standalone
   * gcc -r -nostdlib
   * use *.o filename suffix
some_value = static
   * gcc -r -nostdlib -DUSE_TCL_STUBS
   * use *_stub.o filename suffix
some_value = anything else
   * gcc -r -nostdlib -DUSE_TCL_STUBS  ''(same as for "static")''
   * use no filename suffix

'''Notes''' on ::critcl::config combine
   * Distinct filename suffices are used so that switching between values of "combine" causes a rebuild
   * On Windows, OSF1 and Darwin, gcc options differ from those stated above
   * Only the default value "" works for me, with gcc 4.0.2 and binutils 2.15.94 on Linux/x86.  It is likely that gcc's interpretation of command options has changed since Critcl was written.

----

[RLH] 09-June-2006: What does one need to make Critcl work?

[KJN] 09-June-2006: Critcl is supplied as a [Starkit].  Try it first with the appropriate [Tclkit] for your architecture - the two files should be all you need.  If you then wish to use Critcl with a non-Tclkit installation, see [Critcl FAQ] for instructions on unpacking the Starkit and installing its files.