procomp(1)

NAME
procomp - TclPro Compiler

SYNOPSIS
procomp ?options? file1 ?file2 ...?

OPTIONS

-help
    Displays usage information, then exits without doing anything.

-nologo
    Hides the copyright and version information.

-force
    Force overwrite; if the output file exists, delete it before the run, to ensure that the compilation does not fail because of permission errors. Because TclPro Compiler creates the output file with the same permissions as the input file, a .tbc file generated from a readonly .tcl file will also be readonly; a second compilation will fail unless the -force flag is given.

-out name
    Specifies that the output path is name. If only one file is being compiled, name may specify the complete output file name. Otherwise name must be the name of an existing directory to which all compiled files will be written.

-prefix type
    Specifies the type of prefix string that should be prepended to the output files. The type value can be one of the following:

    none
        Do not add a prefix string.

    auto
        Extract the prefix from the input file: everything from the start of the file to the first non-comment or empty line is prepended to the output file.

    tag Extract the prefix from the input file: everything from the start of the file to the first occurrence of a comment line starting with the text TclPro::Compiler::Include is prepended to the output file.

    Any other value for type is assumed to be a path to a file whose contents are prepended to the output file. The default for this option is auto.

-quiet
    Suppresses warnings about non-existent files.

-verbose
    Verbose mode: messages are generated to log the progress of the compilation.

DESCRIPTION

The command procomp is used to start TclPro Compiler. For each input file, TclPro Compiler creates an output file containing an equivalent script stored as bytecodes for the Tcl bytecode interpreter in Tcl 8.0.3 or later.

By default, the resulting bytecode files will be created in the same directory as the input files, but will be given a different extension (.tbc). The -out flag can be used to specify an alternate directory where the output files will be created. If only one file is being compiled, the -out flag can also be used to specify the complete name of the output file, including the extension.

COMPILED FILES

TclPro Compiler creates an internal representation of a compiled script using the Tcl bytecode compiler that is built into the Tcl core, performs some additional computations, and then emits a representation of the compiled script to the output file. The output file itself is a simple Tcl script that loads the bytecode runtime package (the tbcload package), and then instructs the runtime to load the internal state and execute the script. Since the compiled bytecodes are a valid Tcl script, you can use them anywhere you could use the input script, such as the source and eval commands. You can also invoke compiled scripts directly as shell commands, just as you could the input script, as long as you have created a proper header (see below).

One of the additional computations that TclPro Compiler performs is to collect all procedure bodies that were defined in the script, and create a compiled representation for them as well as the script (the Tcl interpreter compiles procedure bodies lazily, whereas TclPro Compiler forces a compilation early). Thus, scripts that contain mostly procedure definitions are compiled into efficient representations.

Because the compiled file is itself a Tcl script, there may be situations where you will want to add some specialized setup code at the start of the script. For example, in order to invoke a Tcl script directly from a Unix shell, the first lines of the script should look like the following (where tclsh may be replaced with the name of a different interpreter, such as wish):

#!/bin/sh # the next line restarts using tclsh \ exec tclsh "$0" "$@"

By default, the compiler will not generate such a construct. However, you can place such a header in the Tcl source file (or in some other file) and instruct TclPro Compiler to copy it to the output file using the -prefix switch.

LIMITATIONS
Currently the compiler will compile all code and code in any control structure or procedure at the top level of a script. However, code, including procedures, inside of some commands (most notably namespace eval) will not be compiled.

The .tbc file can only be loaded in the protclsh and prowish interpreters or a standard Tcl 8.0.3 (or later) that has the tbcload package available. The tbcload package may be distributed by TclPro users to their customers as needed.

Some constructs that are legal with regular Tcl scripts are not supported with compiled scripts. For example, the info body command cannot return the body of a compiled procedure, because that information is not available; it will return instead a body that was automatically generated by the tbcload package and that has no relation to the actual body of the procedure. This new body contains a call to error; thus, if we define two procedures A and B like this:

proc A {args} { return "hello world $args" } proc B {args} [info body A]

a call to B TEST from an uncompiled Tcl script will return the string "hello world TEST", as expected. A call from a compiled script will cause an error to be generated instead.

EXAMPLES

The simplest command line to compile a Tcl script is shown below:

procomp filename.tcl

Which will create a file filename.tbc containing the bytecodes. To compile all .tcl files in /dir1, type:

procomp /dir1/*.tcl

To place the output files in a different directory, use the -out flag to specify where they should be created:

procomp -out /dir2 /dir1/*.tcl

To have TclPro Compiler extract a header from each .tcl file compiled by looking for the TclPro::Compiler::Include tag, and place it at the start of the corresponding .tbc file:

procomp -out /dir2 -prefix tag /dir1/*.tcl

KEYWORDS
compiler bytecodes