Artifact [e525616e7a]

Artifact e525616e7a36d53cf68ee345b4873dfa4583c149:

Wiki page [Documentation] by rkeene on 2014-06-23 00:32:12.
D 2014-06-23T00:32:12.725
L Documentation
N text/x-markdown
P 8415446a14e0f327b6f7c457e1e3d0ec42ce1d9c
U rkeene
W 4092
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":
    2.  `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":
    3.  `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
  1. `<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
    1. 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
       1. int
       1. long
       1. float
       1. double
       1. char*
       1. Tcl_Obj*: Passes the Tcl object in unchanged
       1. void*
  1. `<returnType>` is the return type for the C function
    1. The supported types are:
       1. void: No return value
       1. ok: Return TCL\_OK or TCL_ERROR
       1. int
       1. long
       1. float
       1. double
       1. char*: TCL\_STATIC string (immutable from C -- use this for constants)
       1. string, dstring: return a (char*) that is a TCL\_DYNAMIC string (allocated from Tcl\_Alloc, will be managed by Tcl)
       1. vstring: return a (char*) that is a TCL\_VOLATILE string (mutable from C, will be copied be Tcl -- use this for local variables)
       1. default: Tcl\_Obj*, a Tcl Object
  1. `<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 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>

$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](wiki/Low-Level API)
Z 6ecaf7ec432228c121f54c589174b94f