DllLoad | load a plugin |
DllUnload | unload a plugin |
DllEnumerate | enumerate all loaded plugins |
StubApiCStart | begin a C++ plugin API description |
StubApiCPrettyName | give a descriptive name for documentation |
StubApiCPluginPurpose | document the purpose of the plugin |
StubApiCShortIntegerConstant | declare integer constant in plugin |
StubApiCInclude | declare include file in plugin |
StubApiCFunction | declare C++ function in plugin |
StubApiCRemark | provide more documentation for plugin |
StubApiCSetEnv | access Yacas environment in plugin |
StubApiCFile | set file name for plugin API |
StubApiCStruct | declare C struct in plugin |
The plugin feature allows Yacas to interface with other libraries that support additional functionality. For example, there could be a plugin enabling the user to script a user interface from within Yacas, or a specific powerful library to do numeric calculations.
The plugin feature is currently in an experimental stage, and it will not work on each platform. To be precise, the libltdl library is used to load the plugins. This will only work on platforms which are supported by libltdl, which includes Linux, Mac OS X, Solaris, and HP-UX.
The remainder of the section is only of interest to users who want to write plugins themselves. It is assumed that the reader is comfortable programming in C++.
In addition to the plugin structure in the Yacas engine, there is a module cstubgen (currently still under development) that allows a rapid creation of a plugin that interfaces to an external library. Essentially all that is required is to write a file that looks like the header file of the original library, but written in Yacas syntax. The module cstubgen is then able to write out a C++ file that can be compiled and linked with the original library, and then loaded from within Yacas. To include a function in the plugin typically takes one line of Yacas code. There are a few examples in the plugins/ directory (the files ending with api.stub). The build system converts these automatically to the required C++ files.
In addition to the C++ stub file, cstubgen also automatically generates some documentation on the functions included in the stub. This documentation is put in a file with extension '.man.txt'.
An example describing the use of cstubgen can be found in the essay "Creating plugins for Yacas" . See Essays on Yacas, Chapter 5 for a description of the integration of plugins in the build system.
DllLoad(file) |
If the argument file does not specify a directory, all directories in the path for Yacas plugins are searched. This path is built up by calls to DllDirectory. In addition, it contains the default plugin directory which is specified by the command line option --dlldir (see The Yacas User's Function Reference, Chapter 1 ). If this option is not present, the default plugin directory is as specified at compile time (the default value is /usr/local/lib/yacas).
If the argument file does not specify the extension, then first the extension .la is appended. This is the standard extension for Libtool libraries. If no plugin with this name can be found, a platform-specific extension is tried (as an example, this is .so on platforms with ELF libraries).
In> DllLoad("example"); Out> True In> AddTwoIntegers(2,3); Out> 5 |
Note that it suffices to specify the string example. Yacas knows that the plugin resides in the file /usr/local/lib/yacas/example.la (if plugins are installed in the default locations).
DllUnload(file) |
DllUnload always returns True, even if no plugin with the name file is found.
In> DllLoad("example"); Out> True In> AddTwoIntegers(2,3); Out> 5 |
Then, we unload the plugin, and we check that the function AddTwoIntegers is indeed no longer defined.
In> DllUnload("example"); Out> True In> AddTwoIntegers(2,3); Out> AddTwoIntegers(2,3) |
DllEnumerate() |
In> DllEnumerate(); Out> {} |
This changes after we load the example plugin.
In> DllLoad("example"); Out> True In> DllEnumerate(); Out> {"example"} |
StubApiCStart(name) |
StubApiCPrettyName(name) |
This name is used for producing documentation. It will appear in the title of the documentation section describing the plugin.
StubApiCPrettyName("multithreaded GUI") |
StubApiCPluginPurpose(text) |
StubApiCShortIntegerConstant(const,value) |
value -- integer value the global should be bound to
#define FOO 10 |
StubApiCShortIntegerConstant("FOO","FOO") |
StubApiCInclude(file) |
StubApiCInclude("\<GL/gl.h\>") |
StubApiCInclude("\"GL/gl.h\"") |
StubApiCFunction(returntype,fname,args) StubApiCFunction(returntype,fname, fname2,args) |
fname -- function of built-in function
fname2 -- (optional) function name to be used from within Yacas
args -- list of arguments to the function
Return type, function name, and list of arguments should be literal strings (surrounded by quotes).
If fname2 is not supplied, it will be assumed to be the same as fname.
The return types currently supported are "int", "double" and "void".
The argument values that are currently supported are "int", "double", and "input_string".
Argument types can be specified simply as a string referring to their type, like "int", or they can be lists with an additional element stating the name of the variable: {"int","n"}. The variable will then show up in the automatically generated documentation as having the name "n".
StubApiCFunction("void","glVertex3d", {"double","double","double"}); |
StubApiCRemark(string) |
StubApiCSetEnv(func) |
There needs to ba a function in the plugin somewhere of the form
static LispEnvironment* env = NULL; void GlutSetEnv(LispEnvironment& aEnv) { env = &aEnv; } |
StubApiCSetEnv("GlutSetEnv"); |
StubApiCFile(pluginname,basename) |
basename -- name for the generation of the stub file
pluginname should be the name as passed to DllLoad. If the plugin name is loaded with DllLoad("example"), then pluginname should be "example".
StubApiCStruct(name) StubApiCStruct(name,freefunction) |
freefunction -- function that can be called to clean up the object
By default the struct will be deleted from memory with a normal call to free(...). This can be overridden with a function given as second argument, freefunction. This is needed in the case where there are additional operations that need to be performed in order to delete the object from memory.
typedef struct SomeStruct { int a; int b; } SomeStruct; |
StubApiCStruct("SomeStruct*") |