load_package

load_package name

This loads the dynamic library named (eg) libname.so. The "lib" and ".so" components of this library name a system dependent strings. The system will automatically use the correct local terminology depending on the system type.

Firstly the $STADLIB/name directory is appended to Tcl auto_path variable. Next the $STADTABL/namerc file is used to specify the package menus and defaults (which are saved as a keyed list in the global tcl variable name_defs). The .namerc file is also loaded up from the callers HOME directory and from the current directory, if they exist, in this order. This means that a user can override defaults specified in the STADTABL directory by creating an rc file in their home directory, and then to override these specifications further in a project-by-project fashion by adding configurations to the current directory.

Next the library itself is dynamically loaded. The file to be loaded is held within the $STADLIB/$MACHINE-binaries directory. If the library does not exist within this directory then it is not loaded and no error is produced.

Finally if existent, the package initialisation function in C will then be called with a Tcl interpreter as the sole argument and returns an integer (TCL_OK or TCL_ERROR). It is this function which performs the registering of new commands to the Tcl language. The C function name must be the package name with the first character as upper case, the following characters as lowercase, and suffixed by _Init. See the Tcl load manual page for full details.

So for the tk_utils library the $STADLIB/tk_utils directory is added to the auto_path variable, the $STADTABL/tk_utilsrc file is processed, and executes the C function Tk_utils_Init().

load_package tcldir libdir name ?init?

This is the more versatile form of the load_package command. The procedures performed are the same, however the location of the files is no longer controlled solely by environment variables.

Tcldir specifies the directory to add to the Tcl auto_path variable and is used for the search path of the namerc file. As with the simpler form of load_package the STADTABL, HOME, and current directory versions of the rc file are also loaded, with each file overriding values specified in the earlier copies.

The libdir argument specifies the location to find the dynamic library file to load. Specifying this as a single - (minus sign) requests that no dynamic library is to be loaded. In this way libraries consisting solely of Tcl files may be used. Specifying libdir as a blank string (either "" or {}) indicates that the library is to be searched for in the users LD_LIBRARY_PATH instead.

Both the tcldir and libdir variables allow a few substitutions to expand up to common locations.

%L

Expands to $STADLIB

%S

Expands to $STADENROOT/src

%%

Expands to a single percent sign

The init argument is used to indicate whether the dynamic library loaded has an initialisation routine. It should be set to 0 or 1. The current implementation always attemps to execute the initialisation routine, but when init is 0 errors will be ignored.