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.

---