Scripts

Advanced Topic: Extending DESTool

There are multiple paths to extend DESTool by additional functions, either using C++ plug-ins or the scripting language in Lua.

• A Lua-script can be defined local to a DESTool project by the New Lua Script entry from the Insert Lua Code menu in the script-tab. This will insert an (empty) Lua script, which can be edited/inspected via its context menu. To execute the Lua script, either use the Evaluate entry from it's Edit menu, or run the DESTool script from the project browser. On execution, the DESTool error console (see Windows menu) will show debugging output generated with print() or faudes.Print().

  Lua scripts do not have signatures to pass parameters. However, you can access DESTool variables via the workspace field; see also DESTool variables. General information on Lua can be found on the Lua site. libFAUDES related functions are illustrated by the luafaudes tutorials.

• A Lua function can be defined local to a DESTool project by the New Lua Function entry from the Insert Operation menu in the script-tab. It is similar to a Lua script, except that a Lua function must be equipped with at least one signature to pass parameters. Lua functions register themself with the run-time-interface and can be accessed from DESTool scripts in the same way as built-in functions. On initialisation from within the project browser, Lua functions are also installed to DESTool's global Lua state, and can thus be accessed from other Lua functions, from Lua scripts and from the error console.

  For a DESTool project with a simple Lua function see the example Machines/BigBuffer.pro, which uses Lua to generate a buffer with configurable size.

• Lua-extension files (*.flx) package a set of Lua functions together with documentation and/or examples. To integrate a lua-extension with your DESTool installation, start DESTool with the command-line switch -x, i.e.,

  ~/destool$ ./bin/destool -x
  

  This will invoke the extension manager to import, delete, enable or disable individual lua-extensions. Examples for extensions are distributed with the libFAUDES luabindings plug-in.

• You can extend libFAUDES directly via the C++ API using its plug-in mechanism. The standard libFAUDES distribution provides an example plug-in and step-by-step introductions. After development of your plug-in, you can install your extended version of libFAUDES to DESTool by the command-line tool dstinstall:

  ~/destool$ ./bin/dstinstall -lib ../libfaudes_with_extra_plugin -dst ./
  

  Here, libfaudes_with_extra_plugin specifies the path of your extended version of libFAUDES and ./ is the path of the DESTool installation.

  Restrictions apply: you must base your extension on the same version of libFAUDES as the one of the original DESTool distribution (as shown by About); you must compile your customized libFAUDES as a shared object in 64-bit, and, for MS Windows environments with the same compiler as used for DESTool (which at the time of writing is MS Visual C++ 2015 with the compiler reporting version 19.00); you must at least include the plug-ins Simulator, Timed, IoDevice and LuaBindings from the standard distribution.

From experiences gathered so far, project embedded Lua scripts are the easiest way to extend DESTool, while libFAUDES C++ plug-ins can be quite involved. We are aware of the fact that the above documentation on DESTool extension is rather compressed and in some aspects incomplete. Please do not hesitate to contact us if you experience problems when integrating your extensions with DESTool.