Introduction

Many people think that Tcl/Tk is just a scripting language. They think the only way to use Tcl/Tk is to write a script of Tcl commands, then run that script using either the "tclsh" or "wish" interpreters.

But this perception is false. At its heart, Tcl/Tk is really a C library, just like Motif, Gtk or MFC. To use Tcl/Tk as it was originally intended, you have to write a C program that calls the library. "Tclsh" and "wish" are just two programs that happen to be implemented using the Tcl/Tk library.

This is not to disparage the use of scripts that are interpreted by "tclsh" or "wish". The use of scripts is a very powerful idea and has many important applications. But sometimes problems work out better if you approach them with a C or C++ program rather than a script. Unfortunately, the mixing of C or C++ and Tcl/Tk into the same program is a topic that has been neglected in the Tcl/Tk literature and documentation.

The article is about a utility called mktclapp. Mktclapp simplifies the task of building a program that uses both C/C++ code and Tcl/Tk. Using mktclapp, you can quickly write programs that:

• Implement powerful GUIs or command-line interfaces using Tcl or Tcl/Tk,
• Do speedy computation on complex data structures using C or C++,
• Compile under both Unix and Windows98/NT with no source code changes,
• Are realized in a single standalone executable file,
• Run on machines without "tclsh" or "wish" installed, and
• Are difficult for end-users to read and reverse-engineer.

Mktclapp is very easy to learn to use. If you already know how to program in C and you are familiar with writing Tcl/Tk scripts, then you should be able to start using mktclapp in just a few minutes. If you are inexperienced, it might take you just a little longer, but it still is not hard.

A Quick Overview

This is what mktclapp does for you: You begin with a collection of source files, some written in C or C++ and others written in pure Tcl or Tcl/Tk. (See figure 1 below). The mktclapp program scans these source files and uses the information it gleans to build an application initialization module, shown as appinit.c in the figure. You then use your regular C compiler to turn the application initialization module and your C/C++ code into a standalone executable.

The mktclapp program performs a number of services for you:

• It takes care of the messy details of creating and initializing a Tcl or Tcl/Tk interpreter.
• It converts all your Tcl/Tk scripts into static C strings inside the application initialization module so they will be compiled into the executable.
• It optionally "shrouds" your Tcl/Tk scripts so that they are not easily visible to end users.
• It provides some extra library functions that make it easier to write C code that invokes Tcl/Tk subroutines.
• It registers certain C functions as Tcl/Tk commands so that your Tcl/Tk scripts can directly execute those C functions.

It short, mktclapp takes care of a lot of the mundate details of writing a mixed C/C++/Tcl/Tk program so that you have more time left over to focus on solving the interesting problems.

Mktclapp is a command-line program which you can call from your project's Makefile. But there is also a GUI wrapper for mktclapp (written in Tcl/Tk, of course) that makes the program easier to operate. The GUI is called xmktclapp.tcl. With xmktclapp.tcl, all you have to do is select the options you want, choose your C, C++ and Tcl/Tk source files from a file list, and press "Build". The application initialization file will be built for your automatically. Then just run your compiler as you normally would and the job is done. A snapshot of the xmktclapp.tcl GUI is show in figure 2.

Setting Up Your Development Environment

Are you ready to get started? This section will guide you step-by-step into setting up your development environment to use mktclapp. The process is not difficult and should not take very long. There are three simple steps:

Hello, World!

We'll begin by using xmktclapp.tcl to build a simple program that involves just 9 lines of Tcl/Tk and no C/C++. The Tcl/Tk code is contained in a single file named hello.tcl and looks like this:

button .b -text Go -command Hello
button .e -text Quit -command exit
pack .b .e -side left
proc Hello {} {
  catch {destroy .hi}
  toplevel .hi
  button .hi.b -text {Hello, World!} -command {destroy .hi}
  pack .hi.b
}

This code creates a small window containing two buttons labeled "Go" and "Quit". If you press the Quit button, the program exits. If you press "Go", it pops up another small window containing a single button labeled "Hello, World!". If you press the Hello, World! button, the new window disappears.

To build your first mktclapp program, first type the code above into a file named hello.tcl. Then, just to make sure you didn't mistype anything, run the script by double-clicking the icon in Windows or in Unix by typing:

wish hello.tcl

Once you are satisfied that the script is right, launch xmktclapp.tcl by typing

wish xmktclapp.tcl

If you are using windows and have installed a binary release of Tcl/Tk from Scriptics, then you can double-click on the xmktclapp.tcl icon to launch it. But when you do, you will not be running the Cygwin version of Tcl/Tk. This can cause some problems. It is best to run xmktclapp.tcl using the Cygwin version of the Tcl/Tk interpreter. To do so, bring up a Cygwin DOS box and type

cygwish80 xmktclapp.tcl

If You Are Having Trouble

Are you having difficulty getting your first mktclapp program to compile or run? This section is designed to help you fix the problem.

Problem: The compiler complains that it can't find library ABC.

Adding More Tcl Code

Now let's consider the case where your program consists of two or more Tcl files. Typically the way this works is that the first Tcl file (the "main" Tcl file) uses the "source" command of Tcl to load the contents of all the other Tcl files.

Making The Program Standalone

The programs we built above do not depend on the files hello.tcl and balloon.tcl. The contents of those files have been compiled into the executable, so the program will run on machines that do have those files resident. But the program still will not run on machines that do not have Tcl/Tk installed. This is because every Tcl/Tk program depends on a couple dozen Tcl script files that are part of the Tcl/Tk installation. These files are sometimes call "Tcl/Tk Initialization Scripts" or the "Tcl/Tk Library".

You can see a list of the Tcl/Tk Library scripts on your machine be starting up a copy of "wish" and entering the following command:

lsort [concat [glob $tcl_library/*] [glob $tk_library/*]]

If you have more than one version of Tcl/Tk installed on your machine, then you will have more than one Tcl/Tk Library. On my main development machine, I have both Tk7.6 and Tk8.0 installed. So I will get a different response to the above command depending on whether I run "wish" or "wish8.0".

Here's the issue: In order to make your programs completely standalone, so that they will run on machines that do not have Tcl/Tk installed, you have to make sure all of the Tcl/Tk Library scripts are compiled in.

To accomplish this goal, all you have to do is enter the name of the directories that contain your Tcl and Tk libraries on the "Libraries" page of xmktclapp.tcl, then on the "Settings" page set Standalone to either "Yes" or "Strict". When you do this, all the Tcl/Tk Library scripts will be added to your program automatically.

You may want to avoid making your program standalone during early development. There are a lot of Tcl/Tk Library scripts. Their total size approaches a half megabyte. Your code will compile a lot faster if you leave them out at the beginning. Just be sure to include the library scripts before you ship your program so that people that do not have Tcl/Tk installed will be able to run your code.

There's more: To be truely standalone, your program should also be statically linked. This means you will need to link against static libraries for Tcl and Tk instead of the usual shared libraries. Otherwise, your program will not run on machines that do not have the Tcl/Tk shared libraries installed.

On Unix systems, the usual way to link against static libraries is to add an option like -static or perhaps -Bstatic to the last compiler command line. This will do the trick if static libraries are available on your system. If static libraries are not available, you may need to recompile Tcl/Tk to generate them. You might also need to specify the name of the static library directly, as in ../tcl8.0/unix/libtcl.a instead of using the "-l" option like this: -ltcl8.0. Most Unix systems have an "ldd" command which will tell you what shared libraries a program needs. Do whatever it takes to get this list down to only those libraries you know will be on every system.

You may notice that statically linking your program causes it to be much larger. A typical "Hello, World" Tk program will grow to be a couple of megabytes or more in size. It takes a lot longer to compile, and uses more disk space. So, again, you might want to hold off on making your program fully standalone until just before final testing and delivery.

Statically linking a program on Windows is more problematic. I usually deal with the problem by ignoring it altogether. For Windows builds, I just ship the resulting EXE file together with the DLLs it needs in the same directory on a CD-ROM. This works on Windows because Windows programs look for the DLLs they need in the same directory as the EXE file. (Unix systems do not work this way for security reasons. Windows can get away with it because it has no security, other than the fact that it is a single-user operating system.) After you compile your EXE on Windows, you can find out what DLLs it needs using this command:

objdump -p a.exe | grep DLL

The kernel32.dll file is part of Windows and doesn't need to be included with your program. I typically ship with just these extra DLLs: cygwin1.dll, cygtcl80.dll and cygtk80.dll.

Common Mistakes

Here are some mistakes people commonly make when they are first beginning to use mktclapp. Take care to avoid these mistakes yourself.

• The name of the argument to the "source" command must match exactly, character-for-character, the name that appears in the upper "Tcl Scripts" listbox of xmktclapp.tcl. If xmktclapp.tcl shows an absolute pathname, then you should give an absolute pathname when you "source" the file. If the name in the listbox is relative, then the argument to "source" must be relative. Note also that case is significant. Even though Windows will match names with differing case, mktclapp uses the strcmp() function from the C library to compare names, so the names really do have to be identical.
• Be sure that every file that you "source" really is listed on the "Tcl Scripts" page. If a file isn't listed in "Tcl Scripts" your program will fall back and read it from the disk on your development machine. But when you move the program to a different computer, that script won't be there anymore and the program will fail.

  You can guard against this error by setting the Standalone option on the "Settings" page to "Strict". In strict mode, the "source" command of mktclapp will check for built-in files, but if it doesn't find one it won't fall back to the disk. Instead it just returns an error.

• Be sure to include your main script (the Tcl script that runs first) both in the upper listbox and the lower entry box on the "Tcl Scripts" page. It has to be in both places.
• In order to conserve memory and run faster, mktclapp tries to remove comments and extra whitespace from the Tcl scripts before it compiles them into the program. But on some rare occasions, these changes can break scripts. If you are having problems, try turning off the comment removal and see if that helps. To turn off comment removal for a particular script, click on the script so that it is highlighted, then press the "Don't Strip Comments" button.
• When you set Standalone to "Yes" or "Strict", the two Tcl/Tk Library directories specified on the Libraries page of xmktclapp.tcl must be compatible with each other and with the Tcl/Tk C library that you link against. If this isn't the case, the Tcl/Tk initialization will fail and your program will not run.

Adding In Some C Code

We've seen how to link Tcl/Tk scripts into your program. Now let's look at how you can add in some C or C++ code.

As an example, create a C source code file named hw.c and put in the following text. (Omit the line numbers. They are for reference only.)

0001 /* A C module */
0002 #include <stdio.h>
0003 #include "hello.h"
0004 
0005 int ET_COMMAND_print_hello(ET_TCLARGS){
0006   printf("Hello, out there!\n");
0007   return TCL_OK;
0008 }

To compile this C module into your program, bring up xmktclapp.tcl again and go to the C/C++ Modules page. Click on the Insert button and select "hw.c" from the menu. The C/C++ Modules pages should look like figure 4.

Next return to the Settings page, press the "Build" button and exit.

The C code in the hw.c file implements a new Tcl command named print_hello. Adding the name of the C source code file to the C/C++ Modules page of xmktclapp.tcl instructs mktclapp to scan the source code looking for function definitions of the the form

int ET_COMMAND_aaaaa(ET_TCLARGS){
  ...
  return TCL_OK;
}

where the string "aaaaa" in the function name can be any valid C identifier. For every such function found, mktclapp will create a new Tcl command named "aaaaa". And whenever that Tcl command is invoked from within a script, the function will be called.

This is one of the primary means of communication between the C/C++ side of your application and the Tcl/Tk scripts. Whenever you want your Tcl/Tk script to execute some C code, you put the C code inside a function whose name begins with "ET_COMMAND_". The C code can then be executed by calling the Tcl command whose name matches the suffix of the new C function.

In our example, we've created a new Tcl command named "print_hello", but that command is never being called. Let's modify the "hello.tcl" script a bit to change that. Edit hello.tcl so that it looks like this:

button .b -text Go -command print_hello
button .e -text Quit -command exit
pack .b .e -side left

gcc -o hello2 hw.c hello.c -ltk8.0 -ltcl8.0 -L/usr/X11R6/lib -lX11 -lm -ldl

Notice that we now have to add the "hw.c" file to the compiler command line. If you have a lot of C source files, it is probably best to construct a Makefile that compiles each C modules separately then links them all together in the end. Like this:

gcc -c hw.c
gcc -c hello.c
gcc -o hello hw.o hello.o -ltk8.0 -ltcl8.0 -L/usr/X11R6/lib -lX11 -lm -ldl

That way, there is less to recompile if you make changes to a subset of your C modules.

Now run the program. Click on the "Print" button and verify that the message "Hello, out there!" is printed on standard output. (Note that "printf" is a no-op on Windows. If you want to try this example in Windows, you'll need to alter hw.c to write its message to a file that you explicitly open instead of writing to standard output.)

Implementing New Tcl Commands In C

• TCL_OK. This means the command completed successfully.

• TCL_ERROR. This means that an error occurred while executing the command. In this case, the result string that is returned is an error message describing what when wrong.

• TCL_RETURN. This means that the interpreter should immediately return from the Tcl procedure it is currently executing. Returning this value from a C function is the same as executing the return command in Tcl.

• TCL_BREAK. This means that the interpreter should immediately exit the inner-most loop that is currently active. This is the same as executing the break command in Tcl.

• TCL_CONTINUE. This means that the interpreter should skip the rest of the body of the inner-most loop and continue with the next iteration of that loop. This is the same as the continue command in Tcl.

Using The Tcl_Obj Interface For Tcl New Commands

Beginning with version 8.0, Tcl/Tk supports a new interface to commands that is faster in some circumstances. We won't go into the details of how the new interface works. (You can get that information from the Tcl/Tk documentation) But we would like to point out that mktclapp can create Tcl commands that use the new Tcl_Obj interface. All you have to do is preface the name of your function with ET_OBJCOMMAND instead of ET_COMMAND, and use ET_OBJARGS instead of ET_TCLARGS as the argument. So instead of

int ET_COMMAND_print_hello(ET_TCLARGS){
   printf("Hello, out there!\n");
   return TCL_OK;
}

write code like this:

int ET_OBJCOMMAND_print_hello(ET_OBJARGS){
   printf("Hello, out there!\n");
   return TCL_OK;
}

The new Tcl_Obj command interface is a little faster, but not that much faster. The big advantage to the Tcl_Obj interface is that it cleanly handles binary data. The main disadvantage is that the Tcl_Obj interface is harder to use. I recommend using the Tcl_Obj interface only for commands that deal with binary data and continuing to use the older string interface for all other commands.

Using Tcl Namespaces

The names of C functions may contain only alphanumeric and underscore characters. But in order to generate a Tcl command in a namespace, you need to embed colons in the name. To accomodate this, whenever mktclapp sees an ET_COMMAND_ function name that contains two underscores in a row, it changes both underscores to colons in the corresponding Tcl command. This allows you to create new Tcl commands in a namespace.

For example, suppose you wanted to created a new Tcl command named ns1::func1. Your C code would look something like this:

int ET_COMMAND_ns1__func1(ET_TCLARGS){
  ...
  return TCL_OK;
}

The two underscores between "ns1" and "func1" in the C function name will be converted into colons for the corresponding Tcl command, thus giving the desired result.

Executing Tcl/Tk Commands From C Code

The previous sections described how you can transfer control from Tcl/Tk over to C. Now let's see how to go the other direction: how to execute Tcl/Tk code from within a C function.

The Tcl API provides several functions that will cause a string to be interpreted as a Tcl/Tk script. We find:

• Tcl_Eval
• Tcl_VarEval
• Tcl_GlobalEval
• Tcl_EvalFile

All of these functions are fully documented by the Tcl manpages, so we won't go into a lot of detail here about how they work. But a quick example won't hurt.

Consider the Tcl_Eval() function. This function takes two argument.

1. A pointer to a Tcl interpreter, and
2. A string that contains Tcl code to be executed.

0001 /* Implementation of the factor command */
0002 #include "hello.h"
0003
0004 int ET_COMMAND_factor(ET_TCLARGS){
0005   int i, n;
0006   char *zCmd;
0007   if( argc!=3 ){
0008     Et_ResultF(interp,"wrong # args: should be \"%s NUM PROC\"",argv[0]);
0009     return TCL_ERROR;
0010   }
0011   zCmd = Tcl_Alloc( strlen(argv[2]) + 100 );
0012   if( zCmd==0 ){
0013     Et_ResultF(interp,"out of memory");
0014     return TCL_ERROR;
0015   }
0016   n = atoi(argv[1]);
0017   for(i=1; i<=n; i++){
0018     if( (n/i)*i!=n ) continue;
0019     sprintf(zCmd, "%s %d", argv[2], i);
0020     if( Tcl_Eval(interp, zCmd)!=TCL_OK ){
0021       Tcl_Free(zCmd);
0022       return TCL_ERROR;
0023     }
0024   }
0025   Tcl_Free(zCmd);
0026   return TCL_OK;
0027 }

Let's have a look at the code. We begin, as always, by including the necessary header files on line 0002. The rest of the code is an implementation of the "factor" Tcl command on lines 0004 through 0027. The first thing the factor command does is make sure it was called with exactly two arguments. If not, an error message is created and the function returns with an error. Next, on line 0011, we allocate space to hold the Tcl commands that we will execute for each factor. We have to dynamically allocate this space, since we cannot know in advance how big the name of the callback procedure will be. The Tcl library imposes no length limitations on strings and you should strive to do the same with the code you add.

The loop from lines 0017 to 0024 iterates over all values between 1 and the target number, and line 0018 discards those that are not factors. (This is not a very efficient way to compute the factors of a number, by the way. But a better algorithm would require considerably more code which would obsure the point of the example.) On line 0019, we construct the text of a Tcl command to execute for the single factor in the variable i. Then the command is executed using Tcl_Eval on line 0020. Notice that we test to make sure Tcl_Eval returns TCL_OK, and we abort immediately if it does not. Finally, after the loop exits, we free the dynamically allocated memory and return successfully.

You will notice in this example that a considerable amount of code was used to dynamically allocate space for the Tcl command that was to be executed. A lot of this extra could can be avoided by using a special function provided by mktclapp that does the same work as Tcl_Eval, but with more flexible calling parameters. The Et_EvalF function executes Tcl code like Tcl_Eval, but it constructs the Tcl code using printf-style arguments. Take a look at the same "factor" command coded using Et_EvalF instead of Tcl_Eval:

0001 /* Implementation of the factor command */
0002 #include "hello.h"
0003
0004 int ET_COMMAND_factor(ET_TCLARGS){
0005   int i, n;
0006   if( argc!=3 ){
0007     Et_ResultF(interp,"wrong # args: should be \"%s NUM PROC\"",argv[0]);
0008     return TCL_ERROR;
0009   }
0010   n = atoi(argv[1]);
0011   for(i=1; i<=n; i++){
0012     if( (n/i)*i!=n ) continue;
0013     if( Et_EvalF(interp, "%s %d", argv[2], i)!=TCL_OK ){
0014       return TCL_ERROR;
0015     }
0016   }
0017   return TCL_OK;
0018 }

What a difference! The use of Et_EvalF reduced the size of the factor command by one third. It also helped reduce the danger of memory leaks that would result if (for example) line 0021 were accidently omitted from the Tcl_Eval implementation. Et_EvalF executes Tcl code in the same way as Tcl_Eval, but with a much more convenient interface. Experience with Et_EvalF shows it can greatly decrease coding effort and the number of coding errors.

Other Functions Provided By Mktclapp

We've already seen two functions that are provided by mktclapp that do not appear in the standard Tcl library: Et_ResultF and Et_EvalF. There are others which haven't been mentioned.

• Et_GlobalEvalF. This works just like Et_EvalF, except that all variables are evaluated in the global context. Et_GlobalEvalF is to Et_EvalF what Tcl_GlobalEval is to Tcl_Eval.

• Et_DStringAppendF. This routine works like Tcl_DStringAppend with the addition that the string to be appended is constructed using printf-style arguments. For more information on what Tcl_DStringAppend does, refer to the Tcl manpages.

• mprintf. This helpful routine works like the sprintf routine from the standard C library. Except, instead of taking the buffer into which the results are written as its first parameter, the mprintf routine mallocs for sufficient space to hold the result and returns a pointer to the malloced space. The calling function is responsible for freeing the memory to avoid a memory leak. This implementation of mprintf actually uses Tcl_Alloc to obtain its memory, so the memory really should be freed by calling Tcl_Free. Tcl_Alloc and Tcl_Free are fully documented in the Tcl manpages.

• vmprintf. This is a varargs version of mprintf().

In addition to these function, mktclapp also provides a global variable named Et_Interp which is a pointer to the main Tcl interpreter for your application. A pointer to an interpreter is required as the first parameter to many routines in the Tcl library, as well as to mktclapp routines like Et_EvalF. If your program only uses a single Tcl interpreter (most programs fulfill this constraint) then you can use the global variable Et_Interp rather than pass a pointer to the interpreter as a parameter to every C subroutine you write.

The %q Format Field

There is subtle danger in using the %s format field within the Et_EvalF function and its kin. Consider what would happen if the string that is inserted in place of the %s contains characters with special meaning to Tcl.

For example, suppose you have a Tcl/Tk command named PopupMessage that takes a text string as its only argument and displays that string as a message in a popup dialog box. If the your C code frequently needs to pop up messages, you might consider writing a C subroutine to do the work for you, like this:

void DoPopup(const char *zMsg){
  Et_EvalF(Et_Interp,"PopupMessage \"%s\"", zMsg);
}

If you invoke this subroutine with a message that read "Hello, World!", then the Et_EvalF function would construct a Tcl command that said

PopupMessage "Hello, World!"

which would do what you intend. But now consider what would happen if you invoke DoPopup with a string like this:

DoPopup("Missing \";\" on line 11");

In this case, Et_EvalF would construct its Tcl command to read as follows:

PopupMessage "Missing ";" on line 11"

And this command will not work. The Tcl interpreter will break this string into two commands. The first command will invoke the PopupMessage procedure with the string "Missing ", and the second command will consist of the text " on line 11". Certainly not what you intended.

You might try to work around this problem by using curly braces rather than double quotes to enclose the argument to PopupMessage, like this:

void DoPopup(const char *zMsg){
  Et_EvalF(Et_Interp,"PopupMessage {%s}", zMsg);
}

This changes the problem, but does not make it go away. Now the function fails when the input string is something like

DoPopup("Missing \"}\" on line 11");

The solution to this conundrum is to never use the %s format directive when the string to be inserted can possibly contain characters that are special to Tcl. Et_EvalF provides an alternative formatting directived called %q (the "q" stands for "quote") that works just like %s except that it inserts a backslash character before every character in the inserted string that has special meaning to Tcl. So what we have to do is change the DoPopup function to read as follows:

void DoPopup(const char *zMsg){
  Et_EvalF(Et_Interp,"PopupMessage \"%q\"", zMsg);
}

Now when the DoPopup function is called with an input string that contains special characters, like this:

DoPopup("Missing \";\" on line 11");

the Tcl command that Et_EvalF constructs reads as follows:

PopupMessage "Missing \";\" on line 11"

The Et_EvalF function has inserted a backslash before each double-quote character in the string. This Tcl command gives the intended result.

The %q formatting directive is available in all of the extension functions provided by mktclapp: Et_EvalF, Et_ResultF, Et_GlobalEvalF, Et_DStringAppendF, mprintf, and vmprintf. Some general guidelines on how and when to use %q instead of %s follow:

• Always use %q for strings whose content can be influenced by the user or by input data. To do otherwise will open security holes in your program.

• Use %q rather than %s for any string that might contain characters that are special to Tcl.

• The %q formatter does not escape spaces, so it is best to put you %q inside of double-quotes.

• %q is designed for use within double-quotes, not curly braces. Use the %q like this: \"%q\" Not like this: {%q}.

Putting A  main() In Your C Code

Every C program requires a main() function. If you don't supply one in the C code you link with mktclapp, then mktclapp will put its own main() in the application initialization module that it builds. This is the recommended practice. But for special circumstances, you may want to provide your own main() function. That's fine. The code that mktclapp generates will still work. But you need to remember two things:

1. At some point, you need to call the routine Et_Init() and pass it the value of argc and argv from main(), in order to initialize the Tcl/Tk interpreter. Your code might look something like this:

   int main(int argc, argv){
      /* Your code goes here */
      Et_Init(argc, argv);
      return 0;
   }
   

   The Et_Init() function doesn't return until the Tcl/Tk interpreter has been terminated. For a GUI application, this means it never returns. So don't put any code after your call to Et_Init() that you want to execute.

2. The "Fork Into Background" feature that can be optionally enabled using mktclapp will not work if you supply your own main() routine.

C Functions For Application Initialization

If the C code that you link using mktclapp contains a function named Et_AppInit(), then that function will be called right after the Tcl/Tk interpreter has been initialized. So if you need to do any additional setup to the Tcl/Tk interpreter, such as loading an extension, the Et_AppInit() function is a great place to do it.

For example, suppose you need to include the BLT extensions in your application. You could simply add C code that looks like the following:

0001 #include "appinit.h"
0002 #include <blt.h>
0003
0004 int Et_AppInit(Tcl_Interp *interp){
0005   Blt_Init(interp);
0006   return TCL_OK;
0007 }

Let's look more closely at this code. Line 0001 sources the header file that mktclapp generates. (Depending on what name you choose for the generated files, you might need to alter this line.) We also need to include the header file for BLT on line 0002. The implementation of Et_AppInit begins on line 0004. Notice that it takes a single parameter which is a pointer to the Tcl interpreter and returns an integer. On Line 0005, the BLT extension is initialized. Finally on line 0006 we return from Et_AppInit(). Notice the Et_AppInit() should return TCL_OK if there were no errors.

Other Tcl/Tk extensions are initialized in a similar way. To initialize an extension named ABC you typically invoke a function named Abc_Init(interp) inside of Et_AppInit(). Refer to the documentation for the particular extension you want to initialize for details. Some Tcl/Tk extensions (such as TclX) include additional Tcl Script files that must be loaded with the application in order for the application to run standalone. For these extensions, you will need to list those script files on the "Tcl Scripts" page of xmktclapp.tcl so that they will be compiled into the initialization module. Or (beginning with version 3.0 of mktclapp) you can list the directories containing the extra scripts in the "Other Libraries" entry field on the "Libraries" page of xmktclapp.tcl. I'm told that you might also need to make some change to the "auto_path" variable in order to get Tix and IncrTcl to work right. But the only major extension I ever use is BLT, so I can not say from personal experience.

The Et_AppInit() function is also a convenient place in which to make calls the the Tcl_LinkVar function in order to create a link between Tcl variables and C variables. Refer to the documentation of the Tcl_LinkVar() function for additional information.

In addition to Et_AppInit(), the code generated by mktclapp will also call a function named Et_PreInit() if it is present. The difference between Et_AppInit() and Et_PreInit() is this: Et_PreInit() is called before the core Tcl/Tk modules are initialized, but Et_AppInit() is called afterwards. It is very unusual to need to use Et_PreInit(). If you do not clearly understand the difference, it is safer to stick with Et_AppInit().

Bundling Binary Data Files With The Executable

The principal magic of mktclapp is that it compiles your Tcl scripts into the executable as static character strings. Beginning with version 3.8 of mktclapp, you can do the same thing with binary data files, such as GIFs. Just add the name of each data file you want to insert on the Data Files page of the application wizard and mktclapp will add the contents of each file to the executable as an array of characters. You can access the data file using the normal file access commands of Tcl.

As an example, suppose you have the following Tcl/Tk code in a file named ckmail.tcl:

image create photo mailicon -file mailicon.gif
button .b -image mailicon -command {exec checkmail &}
pack .b

This program shows a single button containing a GIF icon where the GIF is loaded from a separate file mailicon.gif. To turn this script into a standalone program using mktclapp, bring up xmktclapp.tcl and enter the ckmail.tcl script in two places on the Tcl Scripts page. Then go over to the Data Files pages of xmktclapp.tcl and enter the name of the GIF icon. Like this:

Then select File/Build from the menu and exit xmktclapp.tcl. Mktclapp will include both the Tcl script ckmail.tcl and the image mailicon.gif in the generated application initialization file (ckmail.c). All you have to do now is compile that file.

gcc -o ckmail ckmail.c -ltk8.0 -L/usr/X11R6/lib -lX11 -ltcl8.0 -lm -ldl

The ability to access data files as if they were normal files on the disk depends on certain API functions that appeared in Tcl beginning with release 8.0.3. So this feature will not work if you are using an earlier version of Tcl.

Building Tcl Extensions Using Mktclapp

Another new feature to mktclapp as of version 3.8 is the ability to generate an application initialization file that works as a Tcl extension rather than as a standalone program. To build a Tcl extension, enter the names of C/C++ modules, Tcl scripts, and Data Files into xmktclapp.tcl as you normally would. But on the Settings page select Extension for the Application Mode. Then select File/Build from the menu. Assuming the name of the generated application initialization file is hello.c, you can compile the extension for Unix as follows:

gcc -shared -o hello.so hello.c -ltk -L/usr/X11R6/lib -lX11 -ltcl -lm -ldl

For Windows, the compilation process is more involved. These are the steps:

gcc -c hello.c
echo EXPORTS >hello.def
echo Hello_Init >>hello.def
dllwrap --def hello.def -v --export-all -dllname hello.dll \
   hello.o -ltk -ltcl

The above will generate an extension that can be loaded only by the cygwish version of wish that comes with Cygwin. If you want to make the extension usable by any version of wish, you have to enable stubs support. Do so by adding the options "-DUSE_TCL_STUBS" and "-mno-cygwin" to the compiler command line and link against a compatible Tcl stubs library. You'll have to build a version of the stubs libraries that is compatible with cygwin in order for this to work. The sources to this library are in files named tclStubLib.c and tkStubLib.c in the Tcl/Tk source tree.

The name of the initialization function within the generated extension is based on the name of the initialization file. In the example above, the initialization file was named hello.c so the initialization function for the extension will be named Hello_Init. The initialization function name is formed by taking the root name of the initialization file, making the first letter upper case and all other letters lower case, and appending "_Init".

You can compile Tcl scripts and Data Files into your extension just like you can with standalone applications. If your extension contains an Et_AppInit() function, that function will be executed as soon as the extension is loaded. If you specify a Startup Script, the script will be executed when the extension is loaded, right after the Et_AppInit() function has run.

Running Mktclapp From The Command Line
Or In A Makefile

The xmktclapp.tcl GUI really just collects data. The mktclapp command-line program is what does all the work. So if you want to fully understand mktclapp, you have to understand what the command-line program does.

The mktclapp command line program is what generates both the application initialization code and the corresponding header file. Mktclapp is controlled completely by command-line arguments. Its output appears on standard output.

To generate a header file, use the following command:

mktclapp -header >appinit.h

If you want to generate an application initialization file for hello.tcl, then do this:

mktclapp hello.tcl -main-script hello.tcl >appinit.c

Everything is controlled by command-line options. But it doesn't take a large project for the number of command-line options to become excessive. So mktclapp allows you to specify the name of a file which is read to extract additional command-line options. In fact, the .mta configuration files that xmktclapp.tcl generates are just such files.

Suppose, for example, that you use xmktclapp.tcl to generate a configuration file named hello.mta. Then to use this configuration file to generate an application initialization file, you just type:

mktclapp -f hello.mta >hello.c

In fact, this is all xmktclapp.tcl does when you press the "Build" button. (Grep for "exec mktclapp" on the xmktclapp.tcl source code and you will see.) If you look at the content of a configuration file, you will see that it consists of comments and command-line options for mktclapp. Go ahead. Look at an .mta file now. The contents are instructive.

So one easy way to add mktclapp to a Makefile is to generate the configuration file (the .mta file) using xmktclapp.tcl, then add a rule like this to your Makefile:

hello.c:    hello.mta
            mktclapp -f hello.mta >hello.c

That's all I'm going to say about running mktclapp from the command line. If you want to know more about the command-line options available with mktclapp and how they work, you should look at the output of

mktclapp -help

and study some of the configuration files that xmktclapp generates. It isn't difficult and you should have no trouble figuring it out given the above hints.

Using MkTclApp With The MingW32 Compiler For Windows

By default, the cygwin compiler generates an executable that requires a special DLL named cygwin1.dll. This DLL is covered by the GNU Public License. Consequently, you cannot distribute the DLL with your product unless you are also willing to distribute your source code. Many managers find this restruction unacceptable.

If you don't want to use the cygwin1.dll library, you can still use the cygwin compiler. You simply have to give the compiler a special command-line option: -mno-cygwin. With the -mno-cygwin command-line option, the cygwin compiler will generate an executable that uses only native Windows DLLs. You are free to distribute such an executable without having to make the source code available.

The only problem with this approach is that the Tcl/Tk libraries that come with cygwin depend on the cygwin1.dll DLL. So if you use the -mno-cygwin switch, you won't be able to use the Tcl/Tk libraries that come in the cygwin package. You'll have to either compile the Tcl/Tk libraries yourself (using VC++) or get a copy from Scriptics.

Here is how you can use the Tcl/Tk DLLs and libraries from the standard Scriptics distributions with the cygwin compiler. First get and install the binary distribution of Tcl/Tk from Scriptics. The binary distribution contains the DLLs you'll need along with C header files and interface libraries. The DLLs and header files you can use as is. However, the libraries (tcl82.lib and tk82.lib) will only work with VC++. You'll need to create new libraries named tcl82.a and tk82.a for use with cygwin. I'll describe how to do this using the Tcl library as an example.

The first step is to generate a suitable DEF file. Execute the following commands from a Cygwin shell:

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

If you do it right, the DEF file will begin with the keyword "EXPORTS" then contain the name of every API function in the TCL library, one function name per line. Use the DEF file to generate the library libtcl82.a as follows:

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

Follow the same steps to generate libtk82.a, then link your program against the new libtcl82.a and libtk82.a library files. Put the tcl82.dll and tk82.dll DLLs from the standard distribution in the same directory as your executable and everything should work.

History Of Mktclapp And Summary

I first started programming Tcl/Tk back in 1994, with Tk3.6. Right away, I needed a simple way to mix C/C++ with Tcl/Tk so I wrote the "Embedded Tk" or "ET" package. ET was and continues to be widely used even if its interface is a bit clunky.

Mktclapp was written as a follow-on to ET. It has the same goal as ET, to make it easier to program with a mixture of C/C++ and Tcl/Tk, but the interface is very different. I think the interface is much cleaner and easier to use. It is certainly much easier to maintain. I encourage all ET users to transition to using mktclapp as soon as possible.

The development of mktclapp began in the early fall of 1998. I have personally used mktclapp to develop applications for three separate clients. And other users have had success with mktclapp too, to judge from my e-mail and from the number of downloads.

Bibliography