Yacas supports dynamically loading libraries at runtime. This allows it 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. There are some examples in the plugins/ directory. These are not built by default because they cannot be guaranteed to compile on every platform (yet). The plugins need to be compiled after Yacas itself has been compiled and installed successfully. The plugins/ directory contains a README file with more details on compilation.
In addition to the plugin structure in the Yacas engine, there is a 'cstubgen' module (currently still in development) that allows rapid scripting of a plugin. 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 'cstubgen' module 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. Including a function in the plugin will typically take just one line of Yacas code. There are a few examples in the plugins/ directory (the files ending with api.stub). The make file makefile.plugin is configured to automatically convert these 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 'description'.
The plugin facility is not supported for each platform yet. Specifically, it is only supported on platforms that support the elf binary format. (loading DLLs is platform-dependent).
This chapter assumes the reader is comfortable programming in c++.
In> DllLoad("./libopengl.so"); Out> True; |
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"}); |
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"); |
By default the struct will be deleted from memory with a normal call to free(...). This can be overriden 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*") |