DllLoad , StubApiCStart , StubApiCShortIntegerConstant , StubApiCInclude , StubApiCFunction , StubApiCRemark , StubApiCSetEnv , StubApiCFile , StubApiCStruct .

# The Yacas plugin structure

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++.

###

DllLoad

Internal function

##### Calling Sequence:

DllLoad(file)

##### Parameters:

file - file name of the plugin

##### Description:

DllLoad forces Yacas to load the dynamic link library (.so file under Linux). The full path to the DLL has to be specified, or the file needs to be in a path where dlopen can find it.

##### Examples:

    In> DllLoad("./libopengl.so");
    Out> True;

##### See Also:

###

StubApiCStart

Standard math library

##### Calling Sequence:

StubApiCStart()

##### Parameters:

##### Description:

To start up generating a c stub file for linking a c library with Yacas. A stub specification file needs to start with this function call, to reset the internal state of Yacas for emitting a stub c++ file.

##### See Also:

StubApiCShortIntegerConstant , StubApiCInclude , StubApiCFunction , StubApiCFile , StubApiCSetEnv .

###

StubApiCShortIntegerConstant

Standard math library

##### Calling Sequence:

StubApiCShortIntegerConstant(const,value)

##### Parameters:

const - string representing the global variable to be bound runtime
value - integer value the global should be bound to

##### Description:

define a constant 'const' to have value 'value'. The value should be short integer constant. This is useful for linking in defines and enumerated values into Yacas. If the library for instance has a define
#define FOO 10
Then
StubApiCShortIntegerConstant("FOO","FOO")
will bind the global variable FOO to the value for FOO defined in the library header file.

##### See Also:

StubApiCStart , StubApiCInclude , StubApiCFunction , StubApiCFile , StubApiCSetEnv .

###

StubApiCInclude

Standard math library

##### Calling Sequence:

StubApiCInclude(file)

##### Parameters:

file - file to include from the library the plugin is based on

##### Description:

Declare an include file (a header file for the library, for instance) The delimiters need to be specified too. So, for a standard library like the one needed for opengl, you need to specify
StubApiCInclude("<GL/gl.h>")
and for user include file: StubApiCInclude("\"GL/gl.h\"")

##### See Also:

StubApiCStart , StubApiCShortIntegerConstant , StubApiCFunction , StubApiCFile , StubApiCSetEnv .

###

StubApiCFunction

Standard math library

##### Calling Sequence:

StubApiCFunction(returntype,fname,args)
StubApiCFunction(returntype,fname,fname2,args)

##### Parameters:

returntype - return type of library function
fname - function of built-in function
fname2 - (optional) function name to be used from within Yacas
args - list of arguments to the function

##### Description:

This function declares a library function, along with its calling sequence. cstubgen will then generate the c++ code required to call this 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.

##### Examples:

To define the opengl function glVertex3d that accepts three doubles and returns void:

    StubApiCFunction("void","glVertex3d",{"double","double","double"});

##### See Also:

StubApiCStart , StubApiCShortIntegerConstant , StubApiCInclude , StubApiCFile , StubApiCSetEnv .

###

StubApiCRemark

Standard math library

##### Calling Sequence:

StubApiCRemark(string)

##### Parameters:

string - remark string to be added to the documentation

##### Description:

StubApiCRemark adds a piece of text to the stub documentation file that gets generated automatically. The documentation is put in a .description file while the input file is being processed, so adding a remark on a function just after a function declaration adds a remark on that function.

##### See Also:

StubApiCShortIntegerConstant , StubApiCInclude , StubApiCFunction , StubApiCSetEnv , StubApiCFile .

###

StubApiCSetEnv

Standard math library

##### Calling Sequence:

StubApiCSetEnv(func)

##### Parameters:

func - function to call to set the environment variable

##### Description:

This function forces the plugin to call the function func, with as argument LispEnvironment& aEnvironment. This lets the plugin store the environment class (which is needed for almost any thing to do with Yacas), somewhere in a global variable. aEnvironment can then be used from within a callback function in the plugin that doesn't take the extra argument by design.

There needs to ba a function in the plugin somewhere of the form

    static LispEnvironment* env = NULL;
    void GlutSetEnv(LispEnvironment& aEnv)
    {
        env = &aEnv;
    }

Then calling

    StubApiCSetEnv("GlutSetEnv");

will force the plugin to call GlutSetEnv at load time. All functions in the plugin will then have access to the Yacas environment.

##### See Also:

StubApiCStart , StubApiCShortIntegerConstant , StubApiCInclude , StubApiCFunction , StubApiCFile .

###

StubApiCFile

Standard math library

##### Calling Sequence:

StubApiCFile(basename)

##### Parameters:

basename - basename for the generation of the stub file

##### Description:

Generate the c++ stub file, "basename.cc", and a documentation file named "basename.description". The descriptions are automatically generated while adding functions and constants to the stub.

##### See Also:

StubApiCStart , StubApiCShortIntegerConstant , StubApiCInclude , StubApiCFunction , StubApiCSetEnv .

###

StubApiCStruct

Standard math library

##### Calling Sequence:

StubApiCStruct(name)
StubApiCStruct(name,freefunction)

##### Parameters:

name - name of structure
freefunction - function that can be called to clean up the object

##### Description:

StubApiCStruct declares a struct in a specific library. The name should be followed by an asterisk (clearly showing it is a pointer). After that, in the stub api definition, this type can be used as argument or return type to functions to the library.

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.

##### Examples:

in a library header file, define:

    typedef struct SomeStruct
    {
      int a;
      int b;
    } SomeStruct;

Then in the stub file you can declare this struct by calling:

    StubApiCStruct("SomeStruct*")

##### See Also:

, .