Mavrig - Rig How To's

The following list will be updated over time as more experience is gained with Rig and Mavrig.

Add Rig to existing apps

To "rig-enable" an existing Tcl application, you have to make two adjustments to your main application startup script:

1) source the "Rig.tcl" file as early as possible, i.e. add this at the top:

    source code/Rig.tcl

2) add Rigs boilerplate code for the main application event loop at the end:

    Rig notify main.Init $argv
    Rig notify main.Run
    if {![info exists Rig::exit]} { vwait Rig::exit }
    Rig notify main.Done $Rig::exit
    exit $Rig::exit

Download Rig.tcl from http://contrib.mavrig.org/0.x/Rig.tcl and make sure it is placed in an empty directory, which can be named "code" or anything else and which can be located anywhere to match your app's conventions. Launch your app, it should work as before.

If your app never reaches the new event logic at the end, you'll need to make changes to it so it does. That may entail removing your own vwait calls and adding a "Rig hook main.Done ..." call with the code you had placed after your vwait. This is a good time to create your first rig in say "code/myapp.tcl", where such hooks can be added. All code/*.tcl files will be auto-loaded by Rig.

Disable Rig's notification logging

By default, Rig prints one line to stdout whenever a notification is triggered. It uses the standard "tclLog" global proc for that. You can either redefine it to use your own logging mechanism or disable it altogether with:

    proc tclLog {args} {}

To tie into Rig's own logging mechanism, define tclLog as follows instead:

    proc tclLog {msg} { Log: {$msg} }

Note that these definitions have to precede the "source code/Rig.tcl" line.

Reload source file changes

The "Rig reload" command examines all *.tcl files located in the same directory as "Rig.tcl" and re-source any changed files it finds (as rigs).

So it all comes down to choosing a strategy for when and how often to call "Rig reload". In web-apps, this could be done at the start of each new http request. For example, the Httpd rig has a useful notification to hook into:

    Rig hook httpd.Accept "Rig reload ;#"

To only reload in development/debug mode, you could do something like:

    if {[Rig config mode] eq "debug"} {
      Rig hook httpd.Accept "Rig reload ;#"
    }

Or perhaps this, to reload only when not running as a starkit:

    if {![info exists ::starkit::topdir]} {
      Rig hook httpd.Accept "Rig reload ;#"
    }

Use Rig's configuration options

There is a simple config/options mechanism in Rig. The "config" command queries values in an array managed by Rig, and the "options" command sets those values.

A simple example:

    Rig options {mode release connect 0}
    if {[Rig config connect]} { ...}
    if {[Rig config mode] eq "debug"} { ... }
    if {[Rig config verbose 0]} { ... }

None of the above "if" conditions will evaluate to true.

A similar example, this picks up configuration settings from the command line:

    Rig hook main.Init OnMainInit
    proc OnMainInit {argv} {
      Rig options {
        # mode should be one of "release", "test", or "debug"
        mode release
        # do not connect to the registration server by default
        connect 0
        # verbose mode is unspecified by default
        verbose ""
      } $argv
    }

This illustrates a number of features:

comment lines are allowed in the options info (and removed by "Rig uncomment")
for option "xyz", the command line argument "-xyz" will be recognized
unrecognized options in $argv are silently ignored, there are no checks
$argv is taken from the "main.Init" notification argument, it's not a global
empty config settings still get replaced by defaults given in config calls

Another example, to read defaults from a config file and override it with $argv:

    Rig hook main.Init OnMainInit
    proc OnMainInit {argv} {
      Rig options [Rig readfile ~/.myapprc] $argv
    }

Like everything in Rig, the config/options mechanism is entirely optional.