Jafar module

Overview

Jafar is a modular framework which is intended to gather algorithms developped by various people. A module contains classes and functions related to the same algorithm, or group of algorithms. A jafar module is constituted by:

• source code and headers,
• a piece of CMakeLists.txt
• errors definition (pageJafarError),
• swig wrapped interface definition (Swig .i files),
• documentation (Module documentation).

A jafar module provides:

• static and shared library,
• tcl package,
• html documentation generated by doxygen.

New module

A new module can easily be created with the jafar-module tool. jafar-module is a tcl script in the $JAFAR_DIR/bin directory. To create a new module with name toto:

$ $JAFAR_DIR/bin/jafar_create toto

A new directory toto will be created in $JAFAR_DIR/modules wich contains a minimal set of files with a already usable CMakeLists.txt to compile the module (refer to subsecFrameworkMakefile)

The name of the module.

Choosing the name of a module is an important step :-). You will try to find the perfect name, short enough, precise enough, for your module to become famous (do not forget the cool algo in it !). The name of a module must be unique, at least within the set of modules you may use. Note that the name should contain only lower-case caracters (this is currently a Swig limitation). This name defines several other names:

• of the subdirectories in $JAFAR_DIR/modules/, in $JAFAR_DIR/include/, in $JAFAR_DIR/tclpkg/$TARGET/
• of the c++ namespace in which your module will live, something like jafar::module,
• of the root exception class of all the exceptions of your module, ModuleException,
• of the tcl package you will load with package require module,
• of the tcl namespace in which all the classes and functions wrapped will lie in, module::,
• of the doxygen group in which one can access all the documentation of your module.

To go further with your new module please read Code and doc rules

CMakeLists.txt file

Customize the compilation process: standard flags

CMakeLists.txt is the file where developpers can configure the compilation process for their module.

Standard compilation flags can be modified (CPPFLAGS, CXXFLAGS, LDFLAGS, LIBS) so that the compiler finds all the necessary external libraries. Please make use of the variables defined by the cmake process.

Customize the compilation process: Jafar specific flags

Compilation process of Jafar is driven by a few flags:

• JFR_NDEBUG: when this flag is defined, the specific debug checks, messages and trace mechanism are disabled. The following macros are desactivated: JFR_PRECOND, JFR_POSTCOND, JFR_INVARIANT, JFR_DEBUG, JFR_VDEBUG, JFR_VVDEBUG, JFR_TRACE, JFR_TRACE_BEGIN, JFR_TRACE_POINT, JFR_TRACE_END. JFR_WARNING sends its messages to std::cerr.
• JFR_QUIET disable also warning messages (when JFR_NDEBUG is defined).

Inter modules dependancies

You are developping module pipo, and your module depends on module image, then you need to modify CMakeLists.txt in pipo:

• Add image to the list of modules in REQUIRED_MODULES. During the compilation process, these modules will be checked for beeing up to date.

Module versions policy

The version of a module is defined in CMakeLists.txt by two variables, VERSION and REVISION. REVISION should increment when small improvments are done which do not break the API. VERSION should increment when huge modifications are done, REVISION is then reset to 0.

Swig .i files

The shared library part of the tcl package of the module is generated using the Simple Wrapping Interface Generator. SWIG parses .i files in the include/ directory to know the classes and functions to be wrapped. This is up to the developper to add the needed directives in the module.i skeleton file that comes with the module. For more information please refer to the swig documentation (http://www.swig.org/Doc1.3/Sections.html).

At minimum, the developper will add some #include inside the %{ and %} section and %include. Swig will generate a file module_wrap.cpp in the src/tcl/ directory, do not edit this file as it is regenerated each time Swig is called.

%{ and %} section contains headers necessary to compile module_wrap.cpp, generally it constains the headers wrapped and also headers defining data types which appears in the wrapped classes or functions.

The %include specify headers containing classes and functions to be wrapped. These functions will be made available in a tcl shell throught the generated package. Note that the %include directive is not recursive by default. All data types that are needed, but are not wrapped (which are defined in a #included but not %included file) will be manipulated as pointers in tcl.

Also Swig comes with a library of .i files that enables to wrap standard data types such as std::string. This library is getting more powerfull and complete with new releases of Swig. A first example comes with the helloworld module:

For information about moduleException.i, please refer to Exceptions, Swig and Tcl. In the general case you will not have to modify this file.

moduleTools.i

This file initially contains a template print functions which may be instantiated with different types (in the .i file using %template). This file is intended to contain such helper functions to be used in the interactive shell (tclsh,...).

Tcl macros

You can add in the macro/ directory standard tcl procedures you want to include in the tcl package, they will be available after a package require module. You must follow a few rules:

• your tcl procedures must be declared in the module namespace,
• for each tcl script you must add a package provide command using the same version number as in CMakeLists.txt

Do not forget to follow Code and doc rules. Here is an example from helloworld module:

# $Id$ #

#
#/** demo macro for HelloWorld class. \file demoHello.tcl  \ingroup helloworld */
#

package require helloworld

namespace eval helloworld {

    proc demoHello { n } {
        # this is a demo tcl procedure
        # create n HelloWorld object and print them
        for {set i 0} {$i<$n} {incr i} {
            set h [helloworld::new_HelloWorld "Hello world ! ($i)"]
            $h printHello
      helloworld::delete_HelloWorld $h
        }
    }

}

package provide helloworld 0.3

Module documentation

In addition to the source documentation in the header files, one should add at least a short description of the module in the doc/module.doxy file.

The doc/doxygen/module.doxy file already contains a skeleton. Write general doc in this file and organize it as you wish, make use of sectionning commands and others to structure your document and add hyperlinks. Be aware that label names in doxygen are global, it is better to prefix them with the module name for example.