Modules

Guidelines for adding C++ modules

A Graphlet module is

The Initialization File

A module mod must provide its initialization code in a file named mod.cpp and mod.h.

The following headers are required for module initialization files: 

#include <gt_base/Graphlet.h>
#include <gt_tcl/Tcl_Algorithm.h>
#include <gt_tcl/GraphScript.h>

The Initialization Procedure

The initialization procedure for a module mod must be declared as follows: 

int Gt_mod_Init (Tcl_Interp* interp)

where interp is the current Tcl interpreter. The initialization procedure must return TCL_OK if the initialization was successful, and TCL_ERROR otherwise.

Warning: the name must be exactly as above. The first character must be a capital letter, and it must end with _Init. 

int Gt_sample_Init (Tcl_Interp* interp)
{
    int code = TCL_OK;

    //------------------------------------------
    //
    // INSERT YOUR OWN CODE HERE
    //
    //------------------------------------------

    // Step (1) : Create a command object
    GT_Tcl_Command* sample_algorithm_cmd =
    new GT_Tcl_Sample_Algorithm ("sample_algorithm");
    
    // Step (2) : Install the the command
    code = sample_algorithm_cmd->install (interp);

    // Step (3) : check the return code
    if (code != TCL_OK) {
    return code;
    }

    // Step (4) : Initialize your code (optional)
    code = Tcl_Eval (interp, "GT_Sample::init");
    if (code != TCL_OK) {
        return code;
    }

    //------------------------------------------
    //
    // END INSERT YOUR OWN CODE HERE
    //
    //------------------------------------------
    
    return TCL_OK; 
}

Warning: Initialization procedures must never make any assumptions on the sequence in which initialization procedures are called. The only valid assumption is that Graphlet's initializations are called before any algorithm modules are initialized.

Guidelines for adding Graphscript modules

Where to place Files

During development, Graphscript files are best kept in the developers directory. This is best done with autoloading (see the Tcl documentation for details). For inclusion in the source code distribution, Graphscript files should be placed in the directory lib/graphscript within Graphlet, or in subdirectories of lib/graphscript.

Filenames in lib/graphscript

The filenames should reflect the name of the module:

Tcl code Initialization

To initialice your Tcl code, implement an initialization procedure in Tcl (preferably called GT_init_name for module name) and execute that procedure in the initialization procedure of the C++ code. Your code should look like this: 

code = Tcl_Eval (interp, "GT_name_init");
if (code == TCL_ERROR) {
    return code;
}

Building Graphscript Interpreters

After new Graphscript commands have been implemented, it is necessary to build a new interpreter which contains these new commands. Technically, this the same procedure as needed for a standard Tcl interpreter, with Graphscript as an additional module.

The main procedure

Generally, a main procedure for a Graphscript interpreter should have the following form: 

int main (int argc, char **argv) 
{
    return GT_GraphScript::gt_main (argc, argv, application_init);    
}

GT_GraphScript:gt_main is standard method which calls Tk's Tk_Main procedure (see the Tk documentation for details) and parses the command line in argc and argv for GraphScript specific options. application_init must be provided by the application and initializes Graphscript and algorithm modules.

Note: gt_main is mostly a wrapper for the Tcl/Tk initialization sequence, with the exception that it understands the command line switch -tcl_only. It is possible to replace gt_main with a standard tcl/tk initialization procedure, although one would loose the additional command like switch.

The procedure application_init

Each interpreter must provide a procedure application_init which must have the following form: 

static int application_init (Tcl_Interp *interp)
{
    int code;
    code = Tcl_Init (interp);
    if (code == TCL_ERROR) {
        return code;
    }

    code = Tk_Init (interp);
    if (code == TCL_ERROR) {
        return code;
    }
    
    code = Gt_tcl_Init (interp);
    if (code == TCL_ERROR) {
        return code;
    }

#include "graphscript/modules.cpp"

    //------------------------------------------
    //
    // INSERT YOUR OWN CODE HERE
    //
    //------------------------------------------

    code = Gt_sample_Init (interp);
    if (code == TCL_ERROR) {
        return code;
    }

    //------------------------------------------
    //
    // END INSERT YOUR OWN CODE HERE
    //
    //------------------------------------------
    
    return GT_OK;
}

Linking the Program

UNIX

Link our code with the following libraries:

(1) Graphlet libraries
MODULES -lgt_tcl -lgt_base where MODULES is the list of modules as used in application_init above.
(2) Tcl/Tk libraries
-ltk -ltcl
(3) GTL libraries (release 3.4)
-lGTL
(4) X11 and system libraries
This depends on your operating system, flavor of X11 and local installation policy. Here are some recommendations:

The order in which libraries are linked is important. If libraries are not linked in the above order, then you are likely to get a linker error.

<- Tcl Interface | Up | Makefiles ->