TJC Compiler Manual
Module File

A tjc module file indicates where Tcl source files are located on your system and how they should be compiled.

EXAMPLE FILE: rec.tjc

PACKAGE com.chairsoft.recliner.controls
OPTIONS +inline-containers +inline-controls +cache-commands

SOURCE C:/tcl_source/modules/controls/*.tcl
INIT_SOURCE init.tcl

# Include zog.tcl in the jar but don't compile it
INCLUDE_SOURCE zog.tcl

PROC_OPTIONS {zog_setup} -inline-containers \
-inline-controls

A comment line begins with the # character. Both comment lines and empty lines are ignored. A line can be continued by adding a \ character to the end of the line.

The PACKAGE declaration in the above example indicates the name of the Java package that compiled Tcl procedures will be placed in. In the above example, a Tcl procedure named foo would be compiled and saved in a Java file named com/chairsoft/recliner/controls/FooCmd.java. Each module file must contain a PACKAGE declaration.

The OPTIONS declaration will define the set of options to be applied to all procedures compiled in this module. If the user needs to change the options for a specific procedure, one or more PROC_OPTIONS declarations can be used to add or subtract from the module options. The supported options flags are listed below.

The SOURCE declaration defines one or more paths or path patterns. A SOURCE declaration must not include two different files that have the same filename. A SOURCE declaration is required in each module config file.

The INIT_SOURCE declaration defines a single Tcl file that will be sourced when the package is loaded. This init file must already appear in the SOURCE declaration , so just the filename and not the whole path need appear in the INIT_SOURCE declaration. The init file for a package must source all other Tcl files included in the package. An INIT_SOURCE declaration is required in each tjc config file.

The INCLUDE_SOURCE declaration is like the SOURCE declaration except that it indicates that the given Tcl file should not be compiled and should be included as is. A file in the INCLUDE_SOURCE declaration must already appear in the SOURCE declaration, so only the filename need appear in the declaration. An INCLUDE_SOURCE declaration is optional for a tjc config file.

The supported flags for the OPTIONS and PROC_OPTIONS declarations are as follows:

+O

The +O option will enable all commonly used optimization options. Most users will set only this flag.

-compile

The -compile option will disable all compilation features. The generated Java class file will work exactly the same as a Tcl command defined via proc. This option is intended only for testing purposes and should not be used.

+inline-containers

The +inline-containers option will enable inlining for Tcl's catch, expr, for, foreach, if, switch, and while commands. These commands are called containers because they contain other Tcl commands to be executed. A significant performance improvement is achieved by inlining these container commands and the commands contained within. Tcl's for, foreach, and while loop commands are converted to Java for loops. The if Tcl command is converted directly to a Java if statement. Math operations are optimized in expr, for, if, and while commands. Be extra careful to enclose each math expression in braces, or container commands cannot be compiled. Note that Tcl's eval command and others like it cannot be inlined. This option is enabled by the +O option.

+inline-controls

The +inline-controls option will enable inlining for Tcl's break, continue, and return commands. The break and continue commands can only be inlined inside loops. The return command can be inlined unless it is in a catch block. This option is enabled by the +O option.

+cache-commands

The +cache-commands option will enable caching of Tcl command references inside the body of a TJC compiled proc. In interpreted operation, Jacl will lookup the implementation of a Tcl command by name each time the command is invoked. A TJC compiled proc can avoid looking up the Tcl command each time by saving a reference to the command implementation after the first invocation. The cache is refreshed whenever a command is deleted or renamed. This option will cache references to built-in Tcl commands and user defined Tcl commands. This option is enabled by the +O option.

-constant-increment

The -constant-increment option will enable an optimization that avoids incrementing and decrementing the ref count for shared constant values during Tcl method invocations. This option generates smaller code that executes more quickly. This option is enabled by the +O option.

+cache-variables

The +cache-variables option will enable caching of local scalar variables inside the body of a TJC compiled proc. A TJC compiled proc will execute more quickly when this option is enabled because variables are resolved only once instead of each time the variable is acccessed. Currently, only scalar variables are cached, array variables are resolved as usual. This option is enabled by the +O option.

+inline-commands

The +inline-commands option will enable generation of optimized inline code for built-in Tcl commands. TJC implements inlining of Tcl's append, global, incr, lappend, lindex, list, llength, and set commands. This option is enabled by the +O option.

+omit-results

The +omit-results option will omit code that resets or sets the interp result when the result of a command is not used by another command. Inlined Tcl commands will emit optimized code for the most common use cases when this option is enabled. This option is enabled by the +O option.

+inline-expr

The +inline-expr option will emit inlined code for expr commands and expr arguments to commands like if, while, and for. This option is enabled by the +O option.