Creating Turbulence modules
- How Turbulence modules works
- Creating a module from the scratch (dirty way)
- Using tbc-mod-gen to create the module (recommended)
Turbulence, from a minimal point of view is a listener application built on top of Vortex Library, which reads a configuration file to start at some selected ports, etc, and then load all modules installed.
These modules could implement new BEEP profiles or features that extend Turbulence internal function (not necessarily a new BEEP profile). This is because module structure is really simple.
Turbulence core is really small. The rest of features are added as modules. For example, Turbulence SASL support is a module which is configurable to use a particular user database and, with the help of some tools (tbc-sasl-conf), you can manage users that can connect to Turbulence.
In fact, Turbulence doesn't known anything about SASL. The SASL module is implemented to install and configure the SASL profile provided by Vortex, and using Profile Path (a Turbulence core feature), the security provisioning is met.
The Turbulence module anatomy is fairly simple. It contains three handlers:
- Init: A handler called by Turbulence to start the module. Here the developer must place all calls required to install/configure a profile, init global variables, etc.
- Close: Called by Turbulence to stop a module. Here the developer must stop and dealloc all resources used by its module.
- Reconf: Called by Turbulence when a HUP signal is received. This is a notification that the module should reload its configuration files and start to behave as they propose.
As you can observe, a Turbulence module structure is simple and not enforced to anything.
Maybe the easiest way to start writing a Turbulence Module is to take a look into mod-test source code. This module doesn't do anything but is maintained across releases to contain all handlers required and a brief help. You can use it as an official reference. A module is at minimum composed by the following tree files:
Makefile.am: optional automake file used to build the module: [TXT]
mod-test.xml.in: xml module pointer, a file that is installed at the Turbulence modules dir to load the module.: [TXT]
Now if your intention is to built a BEEP profile then you should do all calls to install it and its associated handlers using the vortex profiles API at the Init handler.
This tool allows to create a XML template that is used to produce the module output. Here is an example:
First we create a xml empty module template:
>> mkdir template >> cd template >> tbc-mod-gen --template --enable-autoconf --out-dir . I: producing a template definition at the location provided I: creating file: ./template.xml I: template created: OK
Now you should rename the file template.xml to something more appropriate and edit the template content, changing the module name and its description. Do not change the content of init, close and reconf nodes for now:
<?xml version='1.0' standalone='yes' ?> <mod-def> <name>mod-template</name> <description>Place here a generic module description</description> <source-code> <!-- init method, called once the module is loaded --> <init> /* Place here your mod init code. This will be called once turbulence decides to include the module. */ return true; </init> <!-- close method, called once the module is going to be stopped --> <close> /* Place here the code required to stop and dealloc resources used by your module */ </close> <!-- reconf method, called once it is received a 'reconfiguration signal' --> <reconf> /* Place here all your optional reconf code if the HUP signal is received */ </reconf> </source-code> </mod-def>
Now, do the following to compile the content and produce a module that is compatible with the Turbulence interface, and it is full ready to be compiled and installed:
>> tbc-mod-gen --compile template.xml --out-dir . --enable-autoconf I: creating file: ./mod_template.c I: creating file: ./Makefile.am I: found autoconf support files request.. I: creating file: ./autogen.sh I: making executable: ./autogen.sh I: creating file: ./configure.ac I: creating file: ./gen-code I: making executable: ./gen-code I: mod_template created!
Now take a look into the files created, specially mod_template.c. Once you are ready, type the following to build the module:
>> ./autogen.sh >> make >> make install
If you are new to autotools, you have to now that the first command (autogen.sh) is only execute once. Next times you can run ./configure which have the same effect and run faster. The autogen.sh command is executed to bootstrap the project, adding all missing files.
Now you are ready to complete the module with your particular code. For that, you'll have to use the Turbulence API and specially the Vortex API. See document section for more details.