Critcl Manual

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

Critcl defines the init function as

  Your_package_name_Init(Tcl_Interp* ip)

(Where 'your_package_name' is the simple name of your package, plus any prefix you defined.) So if you need to inject code that uses the interpreter, the variable name is 'ip'. (This is true of both critcl.kit and critcl2.kit, for all the kits Duoas examined.)

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

Summary for adef:

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

Summary for 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*

Example (RS):

 critcl::cproc sum {int a int b} int {
      return a+b;
 }

::critcl::ccommand name anames ?-clientdata data? ?-delproc proc? args

Connects code to Tcl_CreateObjCommand without further wrapping

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

anames: {clientdata interp objc objv} are the default argument names. objv stand for "Tcl_Obj *const objv[ ]" in the compiled C code. interp is of course "Tcl_Interp *interp"

::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 10-June-2006: Critcl is supplied as a Starkit. Try it first with the appropriate Tclkit for your architecture - the two files (plus a working installation of gcc) 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.

Category Critcl