High-Level API Manual Page

package require tcc4tcl

tcc4tcl::new

Creates a new TCC interpreter instance.

Synposis:

    tcc4tcl::new ?<outputFile> ?<packageNameAndVersionAsAList>??

Returns an opaque handle which is also a Tcl command to operate on.

If neither <outputFile> nor <packageNameAndVersionAsAList> are specified, compilation (which happens when [$handle go] is called) is performed to memory.

If only <outputFile> is specified then an executable is written to the file named.

If <packageNameAndVersionAsAList> is also specified then a Tcl extension is written as a shared library (shared object, dynamic library, dynamic linking library) to the file named. The format is a 2 element list, the first is the name of the package and the second is the version number.

Examples:

1. Create a handle that will compile to memory:
   1. set handle [tcc4tcl::new]
2. Create a handle that will compile to an executable named "myProgram":
   1. set handle [tcc4tcl::new myProgram]
3. Create a handle that will compile to a shared library named "myPackage" with the package name "myPackage" and version "1.0":
   1. set handle [tcc4tcl::new myPackage "myPackage 1.0"]

$handle cproc

Creates a Tcl procedure that calls C code.

Synoposis:

    $handle cproc <procName> <argList> <returnType> ?<code>?

1. <procName> is the name of the Tcl procedure to create
2. <argList> is a list of arguments and their types for the C function;
   1. The list is in the format of: type1 name1 type2 name2 ... typeN nameN
   2. The supported types are:
      1. Tcl_Interp*: Must be first argument, will be the interpreter and the user will not need to pass this parameter
      2. int
      3. long
      4. float
      5. double
      6. char*
      7. Tcl_Obj*: Passes the Tcl object in unchanged
      8. Tcl_WideInt
      9. void*
3. <returnType> is the return type for the C function
   1. The supported types are:
      1. void: No return value
      2. ok: Return TCL_OK or TCL_ERROR
      3. int
      4. long
      5. float
      6. double
      7. Tcl_WideInt
      8. char*: TCL_STATIC string (immutable from C -- use this for constants)
      9. string, dstring: return a (char*) that is a TCL_DYNAMIC string (allocated from Tcl_Alloc, will be managed by Tcl)
      10. vstring: return a (char*) that is a TCL_VOLATILE string (mutable from C, will be copied be Tcl -- use this for local variables)
      11. default: Tcl_Obj*, a Tcl Object
4. <code> is the C code that comprises the function. If the <code> argument is omitted it is assumed there is already an implementation (with the name specified as <procName>, minus any namespace declarations) and this just creates the wrapper and Tcl command.

$handle cwrap

Creates a Tcl procedure that wraps an existing C function

Synoposis:

    $handle cwrap <procName> <argList> <returnType>

Notes:

This only differs from the cproc subcommand with no <code> argument in that it creates a prototype before referencing the function.

$handle ccode

Compile arbitrary C code.

Synopsis:

    $handle ccode <code>

$handle tk

Request that Tk be used for this handle.

Synposis:

    $handle tk

$handle linktclcommand

Create a Tcl command that calls an existing C command as a Tcl command.

Synopsis:

    $handle linktclcommand <CSymbol> <TclCommandName> ?<ClientData>?

$handle add_include_path

Search additional paths for header files

Synopsis:

    $handle add_include_path <dir...>

$handle add_library_path

Search additional paths for libraries

Synopsis:

    $handle add_library_path <dir...>

$handle add_library

Link to an additional library

Synopsis:

    $handle add_library <library...>

$handle code

Return text of what code will be compiled when the go subcommand is called.

Synposis:

    $handle code

$handle go

Execute all requested operations and output to memory, an executable, or DLL.

Once this command completes the handle is released.

Synopsis:

    $handle go

See also Low-Level API