Next Previous Contents

10. Utilities

10.1 slgtksh

Included within src/Makefile of the SLgtk distribution is a target which builds slgtksh, a version of the S-Lang shell, slsh, with SLgtk statically linked. See the SLIRP importify utility for details.

10.2 imdisplay

This is a wrapper around the imdisplay() function described above, suitable for use from the operating system command line. Input images are specified by file name, and all of the same transform options are supported. 

        unix% imdisplay
        Usage: imdisplay file_or_option [ file_or_option ...]

10.3 importify

This SLIRP utility script provides a simple mechanism for building the S-Lang shell, slsh with one or more importable modules statically linked. 

        unix% <slgtk>/slirp/importify -h

        importify, version 0.9 (mnoble@space.mit.edu)
        Emits to stdout a copy of slsh.c, modified to facilitate static
        loading of one or more embedded S-Lang modules.

        Usage: importify [options] module_name [ module_name ...]

        Options:
        -h                   generate this message
        -m symbol            allow main() to be overridden, by renaming it to symbol()
        -p                   do not generate prototype for module init func
        -q                   generate quiet code (no startup messages)
        -s path_to_slsh.c    useful when slsh.c is not in $PWD
Using modules in this manner simplifies debugging in two ways. First, since the module entry points are known at invocation, breakpoints can be set in module code, or within the library wrapped by the module, prior to launching the process. In contrast, when modules are imported into an S-Lang -enabled application at runtime (i.e., after launching the process) its entry points are made available to the debugger only after the module has been fully loaded (on UNIX systems, for example, after a successful dlopen() call), which makes setting breakpoints in the module code (or its wrapped library) much more difficult.

A second benefit of using a statically loaded module is that breakpoints set within the module persist when the parent application is restarted from within the debugger. With code imported at runtime such breakpoints are lost each time the parent application is restarted.

10.4 slirp_debug_pause

In situations where it is not desirable or possible to use slgtksh to debug your guilet, you may instead use the slirp_debug_pause() stub routine.

To activate this stub set the SLIRP_DEBUG_PAUSE environment variable before importing the SLgtk module. This will cause the parent process to wait a specified amount of time prior to entering the Gtk main loop. During this time you may set breakpoints within the codebase of the SLgtk module (since its symbol table will have been loaded prior to the invocation of the debugging stub), including Gtk and its constituent libraries, or within your own compiled code.

If SLIRP_DEBUG_PAUSE is unset in the environment the debugging stub will do nothing. Otherwise, if the variable evaluates to a negative integer N slirp_debug_pause() will sleep for abs(N) seconds. If SLIRP_DEBUG_PAUSE is set to any other value the stub will pause indefinitely, awaiting a keypress in the window from which the parent process was launched.

More information is available on the SLIRP website.

10.5 slgtk-demo

This script provides a convenient way to execute the demonstration code in the examples directory. The usage synopsis is: 

        slgtk-demo [--auto | guilet_name ]
The --auto option will cause the script to cycle through raising and lowering the entire suite of example guilets, and serves as a useful way to exercise the module at large. When invoked with the name of a specific guilet the script will launch the parent guilet and additionally raise the named example. When invoked with no options only the parent guilet will be raised.

10.6 checkgtk

This script allows the developer to quickly identify whether or not a given Gtk/Gdk/Pango/etc C function is available within the SLgtk module. 

        unix% <slgtk>/src/checkgtk
        Usage: checkgtk gtk_function_name [ gtk_function_name ...]

10.7 xvfb-run

The xvfb-run script supports the use of SLgtk in a display-less environment, such as a cron job or remotely-executed regression test. Intended for Unix-compatible systems running X11, the script was taken from Debian Linux and modified slightly to enhance its portability to non-Linux systems. It, along with the mcookie utility and md5 algorithm from the util-linux package, may be found within the src/batch directory of the distribution.

Next Previous Contents