These files are source code that defines the operation of the plug-in. They use the Alias API, the support functions, and define the UI functionality of the plug-in. The function handle encapsulates all of the operations on a UI menu button. A plug-in can define and control any number of menu buttons. A plug-in must define a entry function called plugin_init(). The exit function called plugin_exit() is optional. Plug-ins without exit functions will not be unloaded.
plugin_init(): This function must be defined as:
extern "C" int plugin_init( const char* pluginDirPath )
It is executed immediately after the plug-in is loaded. pluginDirPath is a NULL terminated string which contains the absolute pathname to the directory that the plug-in was loaded from. This path is provided as a convenience to the plug-in. It is intended to be passed to the initialization routines as an additional argument. This allows the plug-in to specify the exact location of its Scheme and icon files if they are not located in the default directories.
The developer uses this function to initialize the OpenAlias universe, and uses instances of the AlFunctionHandle class and AlMomentaryFunction or AlContinuousFunction classes (declared in the file scope to be available to the plugin_exit() function as well) to define the interface between Alias and the plug-in. On successful completion this function should return zero. If a non-zero value is returned from the plugin_init function, OpenAlias will assume that some error condition was encountered in initialization and will automatically unload the plug-in.
Note: we suggest doing the bare minimum in the plugin_init function. Allocate any user data that the plug-in will need but do not allocate any OpenAlias classes.
plugin_exit(): This function must be declared as:
extern "C" int plugin_exit( void )
It is called when the plug-in is removed or Alias is shut down. The programmer uses this function to do whatever is necessary to clean up the plug-in. This function should remove the plug-in from all menus using the deleteObject() method for each declared AlFunctionHandle and destroy any created AlFunctions using the deleteObject() method. On successful completion this function should return zero. Failing to remove all references may result in core dumps if they are accessed by Alias after the plug-in has been removed. In addition, ensure that any callbacks that have been installed are removed.
Plug-ins are not unloaded when Alias exits. This decreases the time that Alias takes to exit but results in static destructors of C++ classes not being called. The DSO is not explicity unloaded but is removed when Alias exits.
Static destructors will be called when a plug-in is unloaded manually. We suggest not performing operations within the static destructors of your classes. Note that plug_init() will still be called when Alias exits so any saving of data can be performed within that function.
If the plug-in requires an option box the first Scheme file is used to define it. All Alias option boxes are written in Scheme which is described below. For many examples of option box files, examine the .o.scm files that reside in subdirectories in the Alias install area.
If the plug-in requires an option box and the option box requires default values for its variables, these default values are set in this file which is invoked from plugin_init()
Debugging can be done with any standard debugger such as dbx or cvd. By using the interactive plug-in loader, plug-ins can be dynamically loaded, debugged, unloaded, modified and then reloaded without having to exit the debugger. Alias can be invoked with the -d option for starting it up in a debugger.
summer% Alias -d dbx debugging: /usr/aw/alias/bin/.Alias dbx version 6.2 Mar 9 1996 15:23:28 Executable /usr/aw/alias/bin/.Alias (dbx)
The environment variable AW_DEBUGGING must be set in order to use a debugger on the Alias binary. The Alias script automatically sets this variable when it is invoked with the -d flag.