Embedding Tcl in C/C++ Applications

Programming Models

Mainstream Tcl Programming Model:		Embedded Tcl Programming Model:
Add bits of C code to a large Tcl program		Add bits of Tcl code to a large C program
Main Tcl script loads extensions written in C		Main C procedure invokes the Tcl interpreter
Tcl/Tk is a programming language		Tcl/Tk is a C library
Most of the Tcl2K conference is about		This tutorial is about

"Hello, World!" Using The Tcl Library

#include <tcl.h>				Always include <tcl.h>
int main(int argc, char **argv){   Tcl_Interp *interp;
interp = Tcl_CreateInterp();				Create a new Tcl interpreter
Tcl_Eval(interp, "puts {Hello, World!}");				Execute a Tcl command.
return 0; }

Compiling "Hello, World!"

Unix:

$ gcc hello.c -ltcl -lm -ldl
$ ./a.out
Hello, World!

Windows using Cygwin:

C:> gcc hello.c -ltcl80 -lm
C:> a.exe
Hello, World!

Windows using Mingw32:

C:> gcc -mno-cygwin hello.c -ltcl82 -lm

Also works with VC++

Where Does -ltcl Come From On Unix?

Build it yourself using these steps:

• Get tcl8.2.2.tar.gz from Scriptics

• zcat tcl8.2.2.tar.gz | tar vx

• cd tcl8.2.2/unix

• ./configure --disable-shared

• make

• Move libtcl8.2.a to your lib directory.

• Copy ../generic/tcl.h into /usr/include.

What Other Libraries Are Required For Unix?

• The sequence of -l options after -ltcl varies from system to system

• Observe what libraries the TCL makefile inserts when it is building tclsh

• Examples in this talk are for RedHat Linux 6.0 for Intel

How To Compile Under Unix Without Installing Tcl

Specify the *.a file directly:

  $ gcc -I../tcl8.2.2/generic hello.c \ 
      ../tcl8.2.2/unix/libtcl8.2.a -lm -ldl
  $ strip a.out
  $ ./a.out
  Hello, World!

Or, tell the C compiler where to look for *.a files:

  $ gcc -I../tcl8.2.2/generic hello.c \ 
      -L../tcl8.2.2/unix -ltcl -lm -ldl
  $ strip a.out
  $ ./a.out
  Hello, World!

The -I../tcl8.2.2 argument tells the compiler where to find <tcl.h>.

What's "Cygwin"?

• An implementation of GCC/G++ and all development tools for Windows95/98/NT/2000

• Available for free download at

  http://sourceware.cygnus.com/cygwin/

• Also available shrink-wrapped at your local software retailer or online at

  http://www.cygnus.com/cygwin/index.html

• Programs compiled using Cygwin require a special DLL (cygwin1.dll) that provides a POSIX system API

• Cygwin1.dll cannot be shipped with proprietary programs without purchasing a license from Cygnus.

• Mingw32 is the same compiler as Cygwin, but generates binaries that do not use cygwin1.dll

Where Does -ltcl82 Come From On Windows?

Build it like this:

• Get tcl82.lib and tcl82.dll from Scriptics.

• echo EXPORTS >tcl82.def

• nm tcl82.lib | grep 'T _' | sed 's/.* T _//' >>tcl82.def

• dlltool --def tcl82.def --dllname tcl82.dll --output-lib libtcl82.a

• Move libtcl82.a to the lib directory and tcl82.dll to the bin directory.

Where Does Your Code Go?

#include <tcl.h>   int main(int argc, char **argv){   Tcl_Interp *interp;   interp = Tcl_CreateInterp();
/* Your application code goes here */				Insert C code here to do whatever it is your program is suppose to do
return 0; }

Building A Simple TCLSH

#include <tcl.h>   int main(int argc, char **argv){   Tcl_Interp *interp;   char *z;   char zLine[2000];   interp = Tcl_CreateInterp();
while( fgets(zLine,sizeof(zLine),stdin) ){				Get one line of input
Tcl_Eval(interp, zLine);				Execute the input as Tcl.
z = Tcl_GetStringResult(interp);     if( z[0] ){       printf("����P�X�\n", z);     }				Print result if not empty
}   return 0; }

What if user types more than 2000 characters?

Building A Simple TCLSH

Use TCL to handle input. Allows input lines of unlimited length.

#include <tcl.h>   /* Tcl code to implement the ** input loop */ static char zLoop[] =    "while {![eof stdin]} {\n"
"  set line [gets stdin]\n"				Get one line of input
"  set result [eval $line]\n"				Execute input as Tcl
"  if {$result!=\"\"} {puts $result}\n"				Print result
"}\n" ;   int main(int argc, char **argv){   Tcl_Interp *interp;   interp = Tcl_CreateInterp();
Tcl_Eval(interp, zLoop);				Run the Tcl input loop
return 0; }

But what about commands that span multiple lines of input?

Better Handling Of Command-Line Input

The file "input.tcl"

set line {} while {![eof stdin]} {
if {$line!=""} {     puts -nonewline "> "   } else {     puts -nonewline "% "   }   flush stdout				Prompt for user input. The prompt is normally "%" but changes to ">" if the current line is a continuation.
append line [gets stdin]   if {[info complete $line]} {
if {[catch {uplevel #0 $line} result]} {				If the command is complete, execute it.
puts stderr "Error: $result"     } elseif {$result!=""} {       puts $result     }     set line {}
} else {     append line \n   }				If the command is incomplete, append a newline and get another line of text.
}

Better Handling Of Command-Line Input

The file "input.c"

#include <tcl.h>   int main(int argc, char **argv){   Tcl_Interp *interp;   interp = Tcl_CreateInterp();
Tcl_Eval(interp, "source input.tcl");				Read and execute the input loop
return 0; }

But now the program is not standalone!

Converting Scripts Into C Strings

Compile Tcl Scripts Into C Programs

#include <tcl.h>
static char zInputLoop[] =    /* Actual code omitted */ ;				Copy and paste the converted Tcl script here
int main(int argc, char **argv){   Tcl_Interp *interp;   interp = Tcl_CreateInterp();
Tcl_Eval(interp, zInputLoop);				Execute the Tcl code
return 0; }

Converting Scripts To Strings
Using SED Or TCLSH

sed -e 's/\\/\\\\/g' \				Convert \ into \\
-e 's/"/\\"/g' \				Convert " into \"
-e 's/^/  "/' \				Add " to start of each line
-e 's/$/\\n"/' input.tcl				Add \n" to end of each line
while {![eof stdin]} {   set line [gets stdin]
regsub -all {\} $line {&&} line				Convert \ into \\
regsub -all {"} $line {\"} line				Convert " into \"
puts "\"$line\\n\""				Add " in front and \n" at the end
}

Converting Scripts Into C Strings

You may want to save space by removing comments and extra whitespace from scripts.

static char zInputLoop[] =    "set line {}\n"   "while {![eof stdin]} {\n"   "if {$line!=\"\"} {\n"   "puts -nonewline \"> \"\n"   "} else {\n"   "puts -nonewline \"% \"\n"   "}\n"   "flush stdout\n"   "append line [gets stdin]\n"   "if {[info complete $line]} {\n"   "if {[catch {uplevel #0 $line} result]} {\n"   "puts stderr \"Error: $result\"\n"   "} elseif {$result!=\"\"} {\n"   "puts $result\n"   "}\n"   "set line {}\n"   "} else {\n"   "append line \\n\n"   "}\n"   "}\n" ;

Converting Scripts To Strings

sed -e 's/\\/\\\\/g' \    -e 's/"/\\"/g' \
-e '/^ *#/d' \				Delete lines that begin with #
-e '/^ *$/d' \				Delete blank lines
-e 's/^ */  "/' \				Delete leading spaces
-e 's/$/\\n"/' input.tcl       while {![eof stdin]} {   set line [gets stdin]
set line [string trimleft $line]				Remove leading space
if {$line==""} continue				Delete blank lines
if {[string index $line 0]=="#"} {     continue   }				Delete lines starting with #
regsub -all {\} $line {&&} line   regsub -all {"} $line {\"} line   puts "\"$line\\n\"" }

Removing Comments Or Leading Space
Will Break Some Tcl Scripts!

image create bitmap smiley -data {
#define smile_width 15 #define smile_height 15				These lines begin with # but are not comment
static unsigned char smile_bits[] = {    0xc0, 0x01, 0x30, 0x06, 0x0c, 0x18,    0x04, 0x10, 0x22, 0x22, 0x52, 0x25,    0x01, 0x40, 0x01, 0x40, 0x01, 0x40,    0x12, 0x24, 0xe2, 0x23, 0x04, 0x10,    0x0c, 0x18, 0x30, 0x06, 0xc0, 0x01}; }     text .t pack .t .t insert end [string trim {
She walks in beauty, like the night      Of cloudless climes and starry skies; And all that's best of dark and bright      Meet in her aspect and her eyes;				Indentation is deleted on lines 2 and 4
}]

Problems like these are rare

Adding A "continue" Command

set line {} while {![eof stdin]} {   if {$line!=""} {     puts -nonewline "> "   } else {     puts -nonewline "% "   }   flush stdout   append line [gets stdin]   if {[info complete $line]} {
if {[lindex $line 0]=="continue"} {       break;				Break out of the loop if the command is "continue"
} elseif {[catch {uplevel #0 $line} result]} {       puts stderr "Error: $result"     } elseif {$result!=""} {       puts $result     }     set line {}   } else {     append line \n   } }

Stop For Tcl Input At Various Points
In A C Program

#include <tcl.h>   static char zInputLoop[] =    /* Tcl Input loop as a C string */ ;   int main(int argc, char **argv){   Tcl_Interp *interp;   interp = Tcl_CreateInterp();
/* Application C code */				Do some computation
Tcl_Eval(interp, zInputLoop);				Stop for some Tcl input
/* More application C code */				Do more computation
Tcl_Eval(interp, zInputLoop);				Stop for more Tcl input
/* Finish up the application */				Finish the computation
return 0; }

Using Tcl For Testing

#include <tcl.h>   static char zInputLoop[] =    /* Tcl Input loop as a C string */ ;
int main(int argc, char **argv){ #ifdef TESTING   Tcl_Interp *interp;				Create interpreter only if TESTING is defined
interp = Tcl_CreateInterp(); #endif   /* Application C code */
#ifdef TESTING   Tcl_Eval(interp, zInputLoop); #endif				Accept command-line input only if TESTING is defined
/* More application C code */ #ifdef TESTING   Tcl_Eval(interp, zInputLoop); #endif   /* Finish up the application */   return 0; }

Creating A New Tcl Command In C

#include <tcl.h>   int NewCmd(
void *clientData,   Tcl_Interp *interp,   int argc,   char **argv				The Tcl command is implemented as a C function with four arguments.
){   printf("Hello, World!\n");
return TCL_OK;				Returns TCL_OK or TCL_ERROR
}   static char zInputLoop[] =    /* Tcl code omitted... */ ;   int main(int argc, char **argv){   Tcl_Interp *interp;   interp = Tcl_CreateInterp();
Tcl_CreateCommand(interp, "helloworld",                     NewCmd, 0, 0);				Tell the interpreter which C function to call when the "helloworld" Tcl command is executed
Tcl_Eval(interp, zInputLoop);   return 0; }

Linkage From Tcl To C

• 3rd parameter of Tcl_CreateCommand() is a pointer to the C subroutine that implements the command.

• 4th parameter to Tcl_CreateCommand() becomes the 1st parameter to the C routine whenever the Tcl command is executed.

• 1st parameter to Tcl_CreateCommand() must be a valid Tcl interpreter. The same pointer appears as the second parameter to the C routine whenever the Tcl command is executed.

Linkage From Tcl To C

• 5th parameter of Tcl_CreateCommand() is a pointer to the C subroutine that is called when the Tcl command is deleted.

• 4th parameter to Tcl_CreateCommand() becomes the 1st parameter to the C routine.

When To Use A Delete Proc

Examples of where the delete proc is used in standard Tcl/Tk:

button .b -text Hello pack .b
rename .b {}				Deleting the .b command causes the button to be destroyed
image create photo smiley \      -file smiley.gif
rename smiley {}				Deleting the smiley command destroys the image and reclaims the memory used to hold the image

• Always use a delete proc if the clientData is a pointer to malloced memory or some other resource that needs freeing

• Delete procs are never used in the Tcl core but are used extensively in Tk

Linkage From Tcl To C

The argc and argv parameters work just like in main()

helloworld one {two three} four

argc = 4 argv[0] = "helloworld" argv[1] = "one" argv[2] = "two three" argv[3] = "four" argv[4] = NULL

A Short-Cut

In a program with many new Tcl commands implemented in C, it becomes tedious to type the same four parameters over and over again. So we define a short-cut.

#define TCLARGS \      void *clientData, \      Tcl_Interp *interp, \      int argc, \      char *argv				Define TCLARGS once in a header file
int NewCmd(TCLARGS){				Use the TCLARGS macro to define new C functions that implement Tcl commands.
/* implementation... */ }

For brevity, we will use the TCLARGS macro during the rest of this talk.

Returning A Value From C Back To Tcl

int NewCmd(TCLARGS){				Note that the C function returns an "int"
return TCL_OK;				Return value is TCL_OK or TCL_ERROR
}

• TCL_OK and TCL_ERROR are defined in <tcl.h>

• Other valid return values TCL_RETURN, TCL_BREAK and TCL_CONTINUE are rarely used

• Common mistake: forgetting to return TCL_OK

Returning A Value From C Back To Tcl

int NewCmd(TCLARGS){
Tcl_SetResult(interp,"Hello!",TCL_STATIC);				Set the result to "Hello!"
return TCL_OK; }

• Result should be the text of an error message if you return TCL_ERROR.

• 3rd argument to Tcl_SetResult() can be TCL_STATIC, TCL_DYNAMIC, TCL_VOLATILE, or a function pointer.

• Also consider using Tcl_AppendResult().

• Direct access to interp->result is deprecated.

• See the man pages for details.

The Tcl_Obj Interface

• A new way to write Tcl commands in C code

• First introduced in Tcl8.0

• Can be much faster, especially for lists or numeric values.

• Able to handle arbitrary binary data.

• More difficult to program.

The Tcl_Obj Interface

int NewObjCmd(   void *clientData,   Tcl_Interp *interp,   int objc,
Tcl_Obj *const* objv				4th parameter is an array Tcl_Objs, not an array of strings
){   /* Implementation... */   return TCL_OK; }   static char zInputLoop[] =    /* Tcl code omitted... */ ;   int main(int argc, char **argv){   Tcl_Interp *interp;   interp = Tcl_CreateInterp();
Tcl_CreateObjCommand(interp, "newcmd",                        NewObjCmd, 0, 0);				Use a different function to register the command
Tcl_Eval(interp, zInputLoop);   return 0; }

The Tcl_Obj Interface

• There are countless access methods for reading information from and placing information in Tcl_Objs. Always use the access methods.

• Details provided at Lee Bernhard's talk this afternoon.

• Definitely use Tcl_Objs if you are writing a new Tcl extension.

• Tcl_Objs address some of the weaknesses of Tcl relative to C/C++.
  • Tcl_Objs are faster
  • Tcl_Objs work with binary data
  But C/C++ is faster still and better for working with binary data.

• When mixing C/C++ with Tcl/Tk the benefits of Tcl_Objs are less important. Using Tcl_Objs in this context may not be worth the extra trouble.

• This talk will focus on the string interface.

Nickel Tour Of The Tcl API

Memory allocation functions

Functions useful in the implementation of new Tcl commands

Functions for controlling the Tcl interpreter

Nickel Tour Of The Tcl API

I/O functions

Names and meanings of system error codes

Nickel Tour Of The Tcl API

General Operating System Calls

String Manipulation And Comparison

Dynamically Resizable Strings

Nickel Tour Of The Tcl API

Event Handlers

Functions For Reading And Writing Tcl Variables

Functions For Executing Tcl Code

Nickel Tour Of The Tcl API

Functions For Dealing With Unicode

Functions For Dealing With Tcl_Objs

Too numerous to list...

Documentation Of The Tcl API

• Tcl comes with excellent man pages

• "Use the source, Luke"

• See tclDecl.h for a list of API functions

• The header comments on the implementation of API functions usually gives a good description of what the function does and how it should be used.

• Most API functions are used within Tcl and Tk. Use grep to locate examples.

Initialization Scripts

• Run the mini TCLSH implemented above and execute the parray command

• It doesn't work! What's wrong?

• parray is really a Tcl proc that is read in when the interpreter is initialized.

• parray (and several other commands) are stored in a handful of "Initialization Scripts"

• All the initialization scripts are stored in the "Tcl Library" - a directory on the host computer.

Invoke the Tcl_Init() function to locate and read the Tcl initialization scripts.

The Tcl_Init() Function

#include <tcl.h>   static char zInputLoop[] =    /* Tcl code omitted... */ ;   int main(int argc, char **argv){   Tcl_Interp *interp;   interp = Tcl_CreateInterp();
Tcl_Init(interp);				Locate and read the initialization scripts
/* Call Tcl_CreateCommand()? */   Tcl_Eval(interp, zInputLoop);   return 0; }

But Tcl_Init() can fail. We need to check its return value...

The Tcl_Init() Function

#include <tcl.h>   static char zInputLoop[] =    /* Tcl code omitted... */ ;   int main(int argc, char **argv){   Tcl_Interp *interp;   interp = Tcl_CreateInterp();
if( Tcl_Init(interp)!=TCL_OK ){     fprintf(stderr,"Tcl_Init() failed: ����P�X�",        Tcl_GetStringResult(interp));   }				Print error message if Tcl_Init() fails
/* Call Tcl_CreateCommand()? */   Tcl_Eval(interp, zInputLoop);   return 0; }

But now the program is not standalone.

How Tcl_Init() Works

• Computes the value of variable tcl_libPath.

• Invokes the procedure named "tclInit"

• A default tclInit procedure is built into Tcl. You can define an alternative tclInit procedure prior to calling Tcl_Init().

The Default initTcl Procedure

The Default Initialization Sequence

• The tclInit procedure locates and sources the init.tcl script. The directory that contains init.tcl is stored in the tcl_library variable.

• The init.tcl script creates an unknown procedure. The unknown procedure will run whenever Tcl encounters an unknown command.

• The unknown procedure consults the file tclIndex in the tcl_library directory to see if the command is defined by one of the initialization scripts.

• The unknown procedure sources any needed initialization scripts and retries the command.

Commands defined in the initialization scripts are loaded on demand.

Standalone Initialization Techniques

Manually execute all initialization scripts

• Convert all initialization scripts into C strings and put them in the executable.

• Call Tcl_Eval() on each initialization script and omit the call to Tcl_Init()

• Or, redefine tclInit so that it does not attempt to source init.tcl then call Tcl_Eval() on each initialization script after Tcl_Init() returns.

This approach is not recommended

Standalone Initialization Techniques

Redefining the builtin source command

• Convert all initialization scripts into C strings and put them in the executable.

• Create a new source command that calls Tcl_Eval() on the appropriate built-in string instead of reading from the disk.

• Read from disk if the named file is not one that is built in.

Redefining source

static char zInitTcl[] = "..."; static char zParrayTcl[] = "...";				Scripts init.tcl and parray.tcl
int NewSourceCmd(TCLARGS){
if( !strcmp(argv[1],"/builtin/init.tcl") )     return Tcl_Eval(interp, zInitTcl);   if( !strcmp(argv[1],"/builtin/parray.tcl") )     return Tcl_Eval(interp, zParrayTcl);				Call Tcl_Eval() on builtin strings if the names match
return Tcl_EvalFile(interp, argv[1]);				Call Tcl_EvalFile() if no match
}   int main(int argc, char **argv){   Tcl_Interp *interp;
setenv("TCL_LIBRARY","/builtin");				Causes tclInit to look for init.tcl in /builtin
interp = Tcl_CreateInterp();
Tcl_CreateCommand(interp, "source",                     NewSourceCmd, 0, 0);				Redefine source
Tcl_Init(interp);   Tcl_Eval(interp, zInputLoop);   return 0; }

Redefining source

• This approach works for all versions of Tcl and Tk.

• Also need to redefine the "file exists" Tcl command since it too is used by tclInit.

• To verify that the program is really standalone, remove the call to Tcl_EvalFile().

Standalone Initialization Techniques

Use the Tcl*InsertProc() functions

• Three routines that overload basic file I/O operations:
  • TclStatInsertProc()
  • TclAccessInsertProc()
  • TclOpenFileChannelInsertProc()

• Allows us to implement a virtual filesystem that overlays the real filesystem.

• The virtual filesystem contains all the initialization scripts as compiled-in strings. The initialization scripts look like they are resident on disk even though they are built in.

• These functions first appeared in Tcl8.0.3. Presumably to support TclPro Wrapper.

• The only documentation is comments on the code. See the Tcl source file generic/tclIOUtil.c

The TclStatInsertProc() Function

• Sole argument is a pointer to a function whose interface is the same as stat()

• Functions are stacked. Tcl tries each stat function on the list, beginning with the most recently inserted, until one succeeds.

The TclStatInsertProc() Function

#include <tclInt.h>				Rather than <tcl.h>!
static int BltinFileStat(char *path,struct stat *buf){   char *zData;   int nData;
zData = FindBuiltinFile(path, 0, &nData);				Check if path is a builtin
if( zData==0 ){     return -1;   }				Fail if path is not a builtin
memset(buf, 0, sizeof(*buf));   buf->st_mode = 0400;   buf->st_size = nData;
return 0;				Success if it is builtin
}   int main(int argc, char **argv){   Tcl_Interp *interp;
TclStatInsertProc(BltinFileStat);				Register new stat function
interp = Tcl_CreateInterp();   Tcl_Init(interp);   Tcl_Eval(interp, zInputLoop);   return 0; }

The TclAccessInsertProc() Function

#include <tclInt.h>				Rather than <tcl.h>!
/* BltinFileStat() not shown... */   static int BltinFileAccess(char *path, int mode){   char *zData;
if( mode & 3 ) return -1;				All builtins are read-only
zData = FindBuiltinFile(path, 0, &nData);				Check if path is a builtin
if( zData==0 ) return -1;				Fail if path is not a builtin
return 0;				Success if it is builtin
}   int main(int argc, char **argv){   Tcl_Interp *interp;
TclStatInsertProc(BltinFileStat);   TclAccessInsertProc(BltinFileAccess);				Register new stat and access functions
interp = Tcl_CreateInterp();   Tcl_Init(interp);   Tcl_Eval(interp, zInputLoop);   return 0; }

The TclOpenFileChannelInsertProc() Function

The TclOpenFileChannelInsertProc() Function

For additional information see:

• The man page for Tcl_CreateChannel()
• Tk source code file generic/tkConsole.c

Initializing Tk

• All the same initialization script issues as Tcl

• Tk initialization scripts are in a different directory than the Tcl initialization scripts - the "Tk Library"

• Call Tk_Init() after Tcl_Init()

• Must have an event loop or Tk will not work!

Implementing An Event Loop

button .b -text Hello -command exit pack .b				Create a Tk interface
bind . <Destroy> {   if {![winfo exists .]} exit }				Close the application when the main window is destroyed
while 1 {vwait forever}				The event loop

"Hello, World!" Using Tk

#include <tk.h>
static char zHello[] =				The application code
"button .b "     "-text {Hello, World} "     "-command exit\n"   "pack .b\n";
static char zEventLoop[] =				The event loop
"bind . <Destroy> {\n"   "  if {![winfo exists .]} exit\n"   "}\n"   "while 1 {vwait forever}\n";   int main(int argc, char **argv){   Tcl_Interp *interp;   interp = Tcl_CreateInterp();
Tcl_Init(interp);   Tk_Init(interp);				We really should check the return values of the init functions...
Tcl_Eval(interp, zHello);
Tcl_Eval(interp, zEventLoop);				The event loop never returns
/*NOTREACHED*/ }

Compiling "Hello, World!" For Tk

Unix:

  $ gcc hello.c -ltk -L/usr/X11R6/lib \ 
        -lX11 -ltcl -lm -ldl
  $ ./a.out

Windows using Cygwin:

  C:> gcc hello.c -mwindows -ltk80 -ltcl80 -lm
  C:> a.exe

Windows using Mingw32:

  C:> gcc -mno-cygwin hello.c -mwindows \ 
           -ltk82 -ltcl82 -lm
  C:> a.exe

Making The Program Standalone

To make a Tcl application standalone you have to convert the following initialization scripts to C strings and compile them into the executable:

To make a Tk application standalone requires these additional initialization scripts from the Tk Library:

Total of about 13K lines and 400K bytes of text or 9K lines and 250K bytes if you strip comments and leading spaces

A Review Of The Features We Want

1. Combine C/C++ with Tcl/Tk into a single executable.

2. The executable should be standalone. It must not depend on files not normally found on the system.

3. It should be difficult for end users to alter the program (and introduce bugs).

Available Programming Aids

Several tools are available. The chart below shows which tools help achieve which objectives.

	Features The Tool Helps To Achieve
Tool Name	Mix C and Tcl	Standalone	Hide Source
SWIG
TclPro Wrapper
FreeWrap
Wrap
mktclapp

SWIG

Creates an interface between an existing C/C++ library and a high-level programming language. Support for: Tcl/Tk Perl Python Java Eiffel Guile No changes required to C/C++ code. Can be used with legacy libraries. Generates an extension, not a standalone binary The tutorial on SWIG was yesterday afternoon. http://www.swig.org/

Wrapper Programs

Convert a pure Tcl/Tk program into a standalone binary Several wrapper programs are available: TclPro Wrapper - http://www.scriptics.com/ FreeWrap - http://www.albany.net/~dlabelle/freewrap/freewrap.html Wrap - http://members1.chello.nl/~j.nijtmans/wrap.html No C compiler required! TclPro will convert Tcl script into bytecode so that it cannot be easily read by the end user. FreeWrap encrypts the scripts. FreeWrap uses compression on its executable. Wrap uses compression on both the executable and on the bundled script files. Usually include extensions like winico and/or BLT

mktclapp

Mix C/C++ with Tcl/Tk into a standalone binary mktclapp generates an application initialization file that contains Tcl scripts as strings and makes all necessary calls to Tcl_Init, Tcl_CreateCommand, Tcl*InsertProc, etc. Features to make it easier to write new Tcl command in C xmktclapp.tcl provides a GUI interface to mktclapp http://www.hwaci.com/sw/mktclapp/

"Hello, World!" Using Mktclapp

• Download mktclapp.c and xmktclapp.tcl from http://www.hwaci.com/sw/mktclapp/

• Compile mktclapp:

    cc -o mktclapp mktclapp.c
    

• Create "Hello, World!" as a Tcl script in file hw.tcl:

    button .b -text {Hello, World!} -command exit
    pack .b
    

• Launch xmktclapp:

    wish xmktclapp.tcl
    

"Hello, World!" Using Mktclapp

Set "Command Line Input?" to "None" Set "Standalone?" to "Yes" Enter "hw.mta" for the Configuration File Enter "hw.c" for the Output C File

"Hello, World!" Using Mktclapp

Go to the "Tcl Scripts" page Press "Insert" and add hw.tcl to the list of Tcl scripts Change the "Startup Script" to be hw.tcl. Select File/Build and File/Exit

"Hello, World!" Using Mktclapp

• Mktclapp generates hw.c. Compile it something like this:

    cc hw.c -ltk -L/usr/X11R6/lib -lX11 -ltcl -lm -ldl
    

• Or, if using Cygwin:

    gcc hw.c -mwindows -ltk80 -ltcl80 -lm
    

• Or, if using Mingw32:

    gcc -mno-cygwin hw.c -mwindows -ltk82 -ltcl82 -lm
    

• And you're done!

Adding C Code To Your Program

Put the new C code in a new source file named "add.c"

#include "hw.h"				Generated by mktclapp
int ET_COMMAND_add(ET_TCLARGS){				ET_TCLARGS is a macro defined in hw.h
int a, b;   char zResult[30];   a = atoi(argv[1]);   b = atoi(argv[2]);   sprintf(zResult, "-1073742724", a+b);   Tcl_SetResult(interp, zResult, TCL_VOLATILE);   return TCL_OK; }

Adding C Code To Your Program

Go to the "C/C++ Modules" page of xmktclapp.tcl Press "Insert" and add add.c to the list of C/C++ modules Select File/Build and File/Exit

Adding C Code To Your Program

• Compile as follows:

    cc add.c hw.c -ltk -L/usr/X11R6/lib -ltcl -lm -ldl
    

• Or construct a Makefile that compiles add.c into add.o and hw.c into hw.o and then links them.

• Compile the same way for Windows except use the usual Windows libraries and options...

Don't have to worry with Tcl_CreateCommand() - Mktclapp takes care of that automatically.

Checking Parameters In The add Command

Modify add.c to insure the add command is called with exactly two integer arguments

#include "hw.h"   int ET_COMMAND_add(ET_TCLARGS){   int a, b;   char zResult[30];
if( argc!=3 ){     Tcl_AppendResult(interp,       "wrong # args: should be: \"",       argv[0], " VALUE VALUE\"", 0);     return TCL_ERROR;   }				Report an error if there are not exactly 2 arguments
if( Tcl_GetInt(interp, argv[1], &a)!=TCL_OK ){     return TCL_ERROR;   }				Report an error if the first argument is not an integer
if( Tcl_GetInt(interp, argv[2], &b)!=TCL_OK ){     return TCL_ERROR;   }				Do the same for the second argument
sprintf(zResult, "-1073742724", a+b);   Tcl_SetResult(interp, zResult, TCL_VOLATILE);   return TCL_OK; }

Using The Tcl_Obj Interface

In the file objadd.c put this code:

#include "hw.h"
int ET_OBJCOMMAND_add2(ET_OBJARGS){   int a, b;				Use "ET_OBJCOMMAND" instead of "ET_COMMAND" and "ET_OBJARGS" instead of "ET_TCLARGS"
if( objc!=3 ){     Tcl_WrongNumArgs(interp, 1, objv,       "number number");     return TCL_ERROR;   }				A special routine for "wrong # args" error
if( Tcl_GetIntFromObj(interp, objv[1], &a) ){				Instead of Tcl_GetInt
return TCL_ERROR;   }   if( Tcl_GetIntFromObj(interp, objv[2], &b) ){     return TCL_ERROR;   }
Tcl_SetIntObj(Tcl_GetObjResult(interp), a+b);				Result stored as integer, not a string
return TCL_OK; }

Speed Of Tcl_Obj Versus "char*" Interfaces

• Compile both add and add2 into the same executable.

• Compare their speeds:

     time {add 123456 654321} 10000
    26 microseconds per iteration
     time {add2 123456 654321} 10000
    4 microseconds per iteration
    

• The Tcl_Obj version is 650 faster!

• Replace the addition with a "real" computation that takes 10 milliseconds.

• Now the Tcl_Obj version is only 0.2 faster!

In many real-world problems, the Tcl_Obj interface has no noticeable speed advantage over the string interface.

More About Built-in Tcl Scripts

Comments and leading white-space are removed from the script by default. Use the "Don't Strip Comments" button to change this. The file name must exactly match the name that is used by the source command.

Locations Of Libraries

Tells mktclapp where to look for script libraries. All Tcl scripts in the indicated directories are compiled into the appinit.c file. Comments and extra white-space are removed. There is no way to turn this off.

Built-in Binary Data Files

Arbitrary files become part of the virtual filesystem No comment or white-space removal is attempted Useful for images or other binary data

New Commands In Namespaces

Two underscores (__) are replaced by two colons (::) in command names, thus giving the ability to define new commands in a namespace

#include <hw.h>
int ET_COMMAND_adder__add(ET_TCLARGS){   int a, b;				Creates the Tcl command called "adder::add"
char *zResult[30];   if( argc!=3 ){     Tcl_AppendResult(interp,       "wrong # args: should be: \"",       argv[0], " VALUE VALUE\"", 0);     return TCL_ERROR;   }   if( Tcl_GetInt(interp, argv[1], &a)!=TCL_OK ){     return TCL_ERROR;   }   if( Tcl_GetInt(interp, argv[1], &b)!=TCL_OK ){     return TCL_ERROR;   }   sprintf(zResult, "-1073742724", a+b);   Tcl_SetResult(interp, zResult, TCL_VOLATILE);   return TCL_OK; }

Adding Your Own main()

int main(int argc, char **argv){   /* Application specific initialization */
Et_Init(argc, argv);				Never returns!
/*NOTREACHED*/   return 0; }

The "Autofork" feature is disabled if you supply your own main()

Initializing The Tcl Interpreter

#include <tcl.h>   int counter = 0;   int main(int argc, char **argv){    Et_Init(argc, argv);    /*NOTREACHED*/    return 0; }   int Et_AppInit(Tcl_Interp *interp){
if( Blt_Init(Interp) ){     return TCL_ERROR;   }				Example: Initialize an extension
Tcl_LinkVar(interp, "counter", &counter,               TCL_LINK_INT);				Or link a C variable to a Tcl variable
return TCL_OK;				Return TCL_OK if successful
}

Writing Your Own Event Loop

#include <tcl.h>
void Et_CustomMainLoop(Tcl_Interp *interp){				Replaces the default event loop
return;				Ex: Return without handling any events.
}   int main(int argc, char **argv){
Et_Init(argc, argv);				This now returns after initializing Tcl
/* Application code here */   return 0; }

Writing Your Own Event Loop

#include <tcl.h>   void Et_CustomMainLoop(Tcl_Interp *interp){
for(;;){     Tcl_DoOneEvent(TCL_ALL_EVENTS|TCL_DONT_WAIT);     /* Other processing... */   }				Intermix processing and event handling
}   int main(int argc, char **argv){
Et_Init(argc, argv);				Never returns
/*NOTREACHED*/   return 0; }

Mktclapp Initialization Sequence

• Initialization starts when the Et_Init() function is called either by client code or by the main() that mktclapp generates

• Create the main Tcl interpreter

• Construct the virtual filesystem overlay by redefining the source command and by using the Tcl*InsertProc() functions

• Call Et_PreInit() if the client defines it

• Call Tcl_Init() and Tk_Init()

• Call Tcl_CreateCommand() and Tcl_CreateObjCommand() for every ET_COMMAND_* and ET_OBJCOMMAND_* function in the client code

• Call Et_AppInit() if the client defines it

• Run the main Tcl script if there is one

• Call Et_CustomMainLoop() if defined by client code or else run the built-in event loop

Invoking Tcl From C

• Use one of the built-in evaluation functions:

  Tcl_Eval() Tcl_VarEval() Tcl_EvalFile() Tcl_GlobalEval()

  Tcl_EvalObj() Tcl_GlobalEvalObj()

• Mktclapp provides evaluation functions with variable argument lists as in printf():
  • Et_EvalF()
  • Et_GlobalEvalF()

• Mktclapp provides a global variable Et_Interp which is a pointer to the main interpreter

Invoking Tcl From C

Example: A C function that pops up an error message dialog box

#include "appinit.h"   void ErrMsg(char *zMsg){   Tcl_SetVar(Et_Interp, "zMsg", zMsg, TCL_GLOBAL_ONLY);   Tcl_GlobalEval(Et_Interp,      "tk_messageBox -icon error -msg $zMsg -type ok");   Tcl_UnsetVar(Et_Interp, "zMsg", TCL_GLOBAL_ONLY); }

Invoking Tcl From C

The same C function implemented using Et_EvalF() instead of Tcl_GlobalEval()

#include "appinit.h"   void ErrMsg(char *zMsg){   Et_EvalF(Et_Interp,      "tk_messageBox -icon error -msg {����P�X�} -type ok",     zMsg); }

• Suppose the function is called as follows:

  ErrMsg("Syntax error near \"}\"");

• The command that gets executed is:

      tk_messageBox -icon error -msg \ 
          {Syntax error near "}"} -type ok
    

• But this is an ill-formed Tcl command!

Invoking Tcl From C

Use the "" format to generate a quoted string

#include "appinit.h"   void ErrMsg(char *zMsg){   Et_EvalF(Et_Interp,      "tk_messageBox -icon error -msg \"%\" -type ok",     zMsg); }

• The puts a backslash before all characters that are special to Tcl

• The Tcl command becomes:

      tk_messageBox -icon error -msg \ 
          "Syntax error near \"\}\"" -type ok
    

Other Functions Provided By Mktclapp

• void Et_ResultF(Tcl_Interp*, ...);

• char *Et_DStringAppendF(Tcl_DString*, ...);

• int Et_AppendObjF(Tcl_Obj*, ...);

• char *mprintf(const char *format, ...);
  char *vmprintf(const char *format, va_list);

• void Et_NewBuiltinFile(char *filename, char *data, int amt);

Operating Mktclapp From The Command Line

• Generate the appinit.h header file like this:

  mktclapp -header >appinit.h

• Generate the appinit.c file like this:

  mktclapp -f appinit.mta >appinit.c

• The *.mta file is just a list of command-line options

• Enter

  mktclapp -help

  to get a list of available options

• Look at MTA files generated by xmktclapp.tcl for examples

Format Of An MTA File

# Configuration file generated by xmktclapp # Hand editing is not recommended #				Comments begin with one #
## Autofork No ## CFile:add.c 1 ## CFile:objadd.c 1 ## CmdLine Console ## ConfigFile hw.mta ## Data:check.gif 1 ## MainScript hw.tcl ## Mode Tcl/Tk ## NoSource No ## OutputFile hw.c ## Shroud No ## Standalone Yes ## TclFile:hw.tcl 1 ## TclLib /usr/lib/tcl8.0 ## TkLib /usr/lib/tk8.0				Lines beginning with two #s are used by xmktclapp.tcl and ignored by mktclapp
-console -main-script "hw.tcl" -tcl-library "/usr/lib/tcl8.0" -tk-library "/usr/lib/tk8.0" "add.c" "objadd.c" -i "check.gif" -strip-tcl "hw.tcl"				All other lines are read by mktclapp and ignored by xmktclapp.tcl

Summary

• Use Tcl for the things Tcl is good at and use C/C++ for the things that C/C++ is good at

• Use wrapper programs to make pure Tcl programs standalone

• Use mktclapp to combine Tcl/Tk with C/C++ into a standalone