Simple Virtual Machine - Plugin generator(1)

NAME
svm_plugin - generates plugin code or generates a plugin code canevas for the Simple Virtual Machine.

SYNOPSIS
svm_plugin [-i input_file] [-o output_file] [-c] [-l] [-d directory] [-u diff_tool] [-q] [-g] [-f] [-h] [-v]

DESCRIPTION
This commands produces a shell script generating a SVM plugin source directory. The generated script can be used to automate a Simple Virtual Machine plugin creation.

This generator can:
 - either produce a complete plugin directory from a description file (useful for reasonable plugins needing maintenance),
 - or produce a generic code canevas to complete by hand from a plugin configuration string (useful for big plugins needing full code customisation). The second flavor is also recommended for beginners in plugin creation, as the producted code will drive the implementation.

The generated code can be produced in:
  - C,
  - C++.

The generated plugin provides:
  - a simple Makefile for local build and local testing,
  - a full Autotools suite for wide build and distribution.

OPTIONS

-i input_file
    By default, the svm_plugin command reads its input on the standard input. This option overrides this by specifying a file. The extension .svm_plugin can be used for such files. Please refer to svm_plugins(7) for more details.

-o output_file
    By default, the svm_plugin command writes its output on the standard output. This option overrides this by specifying a file. The output text is a shell script (See sh(1) for more details) producing the plugin canevas when executed. When this option is set, the resulting file is set executable to the current user.

-l  By default, the svm_plugin command generates a build suite for Autotools with an empty license file. This option removes this empty license file. Autotools then provides a default one.

-p  By default, the script simply patches the generated files. This option saves the generated files before patching them and produces a script to update inline patches.

-d directory
    By default, the script generates the plugin files in a directory named svmplugin<plugin name>. This option changes the directory name.

-q  By default, the svm_plugin command advertises process stages on the standard error. This option suppresses this output. Only errors will be displayed.

-f  Force generation in description mode without update mode by removing previous generated directory. This option is exclusive with options -g and -u.

-h  Displays the command help message.

-v  Displays the Simple Virtual Machine plugin generator license and version.

FULL DESCRIPTION MODE
In this mode, the code generator will produce a ready to compile plugin from a description file. The syntax of this file decorates the regular plugin configuration string by adding sections with text pasted to the files during the plugin generation.

The elements in the files have a common syntax:

Comment
    A comment starts with a sharp on a line until the end of the line.

Object
    An object follows the syntax of one line of the plugin configuration string and can be followed by a text and several sections.

String
    A textual value can be specified between double-quotes on a single line:
    "A text on a single line, with \"double-quotes\" inside."

Block
    A multi-line text can be specified from %{ at the end of a line until the next %} at the beginning of a line:
    %{
    A text
    on several lines
    with %} not at the beginning of a line.
    %}
    An empty multi-line string can be written:
    %{}
    %{ }
    %{%}
    %{ %}
    %{
    %}
    The block delimiters can be replaced by ${ and $}, or by :{ and :} when needed.

Section
    A section starts with a header line made of an identifier used as key, potentially followed by another identifier used as option, and ending by a colon. The content of the section follows its header, like this:
    section:
    %{
    text
    %}
    section option: "text"
    section: "text"
    %{
    text
    %}
    The content of each section depends on the session key.

Anonymous section
    An anonymous section can be attached to an object by writting the section after the object line. An anonymous section has no header:
    OBJECT
    %{
    anonymous section
    %}

  The header part
The header of the file contains only one object:
PLUGIN <name>
followed by these sections, in any order:

author : <string>
    Specifies first name and last name of the author of the plugin.

changelog : <string> OR <block>
    Specifies the change log of the plugin.

checks : <block>
    Specifies which checks has to be performed before compilation in configure.ac using the m4 syntax.

code : <block>
    Specifies the code of the plugin containing the declarations of struct, classes and functions all the functions expect the configuration one can access.

comment <identifier> : <string> <string> <string>
    Specifies how to insert a comment in a file.

    The identifier is the file type.

    The first string is the opening line of the comment. The second string is the prefix on each comment line. The last string is the closing line of the comment.

    The file types source (for C/C++ files), shell (for bash scripts), make (for makefile and automake files), conf (for autoconf files) and svm (for tests) are automatically defined, but can be overridden.

    This section can be present several times.

compile : <string>
    Specifies extra compiler line command options.

date : <string>
    Specifies the creation date of the plugin. The date format shall follow the ISO standard: YYYY-MM-DD.

description : <block>
    Specifies the full description of the plugin in the manual page.

example : <string> <block>
    Specifies an example of plugin usage in the manual page. The string contains a title for the example, and the block contains the text of the example. This section can be present several times.

file [ <identifier> ] : <string> <block>
    Specifies a new file to integrate to the plugin. The name of the file relative to the source directory of the plugin is specified in the string, and its content in the block.

    When an identifier is added, the short licence is added to the top of the file using the identifier as file type comment scheme.

    This section can be present several times.

finalisation : <block>
    Specifies the code to execute when the plugin is destroyed.

includes : <block>
    Specifies the code to include headers, before any function.

initialisation : <block>
    Specifies the code to execute when the plugin is created.

lang : <string>
    Specifies the language of the plugin. The content of the value is used in the -std option of the compiler, the C++ compiler is used when the value contains the string "++". If the value is "C", the C compiler with default standard is used. If the value is "C++", the C++ compiler is used with C++14 standard.

license : <string> OR <block>
    Specifies the license of the plugin. When not specified, the GPLv3 is used.

link : <string>
    Specifies extra linker line command options.

maintainer : <string>
    Specifies first name, last name and email of the maintainer of the plugin.

news : <block>
    Specifies NEWS file.

patch : <string> <block>
    Specifies a patch to apply on a generated file. The name of the file relative to the source directory of the plugin is specified in the string, and the patch content in the block. This section can be present several times.

readme : <block>
    Specifies README file.

seealso : <block>
    Specifies extra See Also in the manual page.

shell : <block>
    Specifies shell commands to apply on the generated plugin. The commands are run in the source directory of the plugin in debug mode. These commands can be use to alter the generated files.

startup : <block>
    Specifies the code to execute after the boot phase, between schedulers start and application processes start.

synopsis : <block>
    Specifies a short description of the plugin in the manual page.

test : <string> [ <block> ] <block>
    Specifies a new test to integrate to the plugin. The name of the test define a SVM file in the test directory. This file name can contain only letters, digits and underscores. The content of the file is half generated, half given in the block. The generated part contains the sheebang to the Simple Virtual Machine, the LOG directive and the plugin include. When two blocks are specified, the first block shall contain the options and arguments to be passed to the tested plugin. This block can not contain carriage returns.

    This section can be present several times.

test : initialisation <block>
    Specifies a test initialisation shell script.

    This script can be used to setup the test environment. In this script, the SVM binaries corresponding to the plugin machine should be called using the respective shell variables: $svm, $svm_plugin and $svm_config.

test : finalisation <block>
    Specifies a test finalisation shell script.

    This script can be used to clean the test environment. In this script, the SVM binaries corresponding to the plugin machine should be called using the respective shell variables: $svm, $svm_plugin and $svm_config.

title : <string>
    Specifies a title for the manual page and the default usage.

usage : <string> OR <block>
    Specifies in short the license. When not specified, use the GPLv3 usage.

version : <string>
    Specifies the version of the plugin.

Each section is present at most once unless specified and has a default value when not present.

  The dependencies part
This part of the file is optional. When present, it shall start with the USE keyword on a line. After this keyword, the dependency objects can be specified like in the plugin configuration string. Each dependency object can be followed by the optional section:

help : <string> OR <block>
    Contains the help text describing why this dependency is present in the plugin manual page.

  The definitions part
The definition part starts with the DEFINE keyword, followed by the list of objects defined in the plugin like in the plugin configuration string. In each section generating a function below, the void* svm references the Simple Virtual Machine pointer. Each category of object uses different sections:

Types

    Anonymous section (Mandatory)
        Specifies the content of the C/C++ struct of the type. The generated C++ type is type_<name> and the generated C type is type_<name>_t.

    delete [ object OR default ] : <block> (Mandatory)
        Specifies the destructor of the type.
         - No option: no generated code, the object is referenced by the void* handler ,
         - object: generates type conversion code, the object is referenced by the type_<name>* object ,
         - default: generates code for trivial destruction of the object. The type_<name>* object can be used to modify the value before deletion.

    copy [ object OR default ] : <block> (Optional)
        Specifies the copy constructor of the type.
         - No option: no generated code, the object is referenced by the const void* handler ,
         - object: generates type conversion code, the object is referenced by the const type_<name>* object ,
         - default: generates code for trivial copy of the object. The const type_<name>* object and type_<name>* copy can be used to modify the copy.

    compare [ object OR default ] : <block> (Optional)
        Specifies the compare operator of the type.
         - No option: no generated code, the objects are referenced by the const void* handler_left and const void* handler_right ,
         - object: generates type conversion code, the objects are referenced by the const type_<name>* object_left and const type_<name>* object_right ,
         - default: generates code for trivial equivalence comparison of the two objects. The const type_<name>* object_left and const type_<name>* object_right can be used to modify the comparison. The trivial equivalence comparison is fully performed only in C++.

    constant [ string OR default ] : <block> (Optional)
        Specifies the constant constructor of the type.
         - No option: no generated code, the value is referenced by the const SVM_String value ,
         - string: generates type conversion code, the object is referenced by the const std::string string (available only in C++),
         - default: generates code for trivial construction from a string of the object. The const std::string string (available only in C++) can be used to read the value and const type_<name>* object can be used to modify the object.

    print [ object OR default ] : <block> (Optional)
        Specifies the string conversion of the type.
         - No option: no generated code, the object is referenced by the const void* handler ,
         - object: generates type conversion code, the object is referenced by the const type_<name>* object ,
         - default: generates code for trivial conversion of the object. The const type_<name>* object and std::string/char* string can be used to access the object and modify the string. The trivial conversion is fully performed only in C++.

    help : <string> OR <block> (Optional)
        Specifies the help for this type in the manual page.

Instructions

    Anonymous section (Mandatory)
        Specifies the actions done by the instruction. The instruction parameters are accessible with the SVM_Size argc and SVM_Parameter[] argv variables. The C/C++ macros:
        ARGV_VALUE(index,type)
        ARGV_PLUGIN(index,plugin,name)
        ARGV_MARKER(index)
        ARGV_KEYWORD(index)
        NEW_VALUE(type,value)
        NEW_PLUGIN(plugin,name,value)
        NEW_STRING(raw_string)
        RAW_STRING(svm_string)
        NEW_BOOLEAN(raw_boolean)
        RAW_BOOLEAN(svm_boolean)
        NEW_NULL_VALUE(type)
        NEW_NULL_PLUGIN(plugin,name)
        ERROR_INTERNAL(irq,message)
        ERROR_EXTERNAL(plugin,name,message)
        CONST_PEP(plugin,name)
        CURRENT(object)
        RETURN
        VARIABLE_GLOBAL(variable)
        VARIABLE_LOCAL(variable)
        VARIABLE_DELETE(variable)
        can be used to shorten the code on basic parameters access and various common operations. When the instruction does not return a value, a C/C++ return statement is automatically added at the end of the code.

    help : <string> OR <block> (Optional)
        Specifies the help for this instruction in the manual page. When the instruction is flagged OVERRIDE, the help is not generated for this instruction.

Interruptions

    help : <string> OR <block> (Optional)
        Specifies the help for this interruption in the manual page.

Schedulers

    Anonymous section (Mandatory)
        Specifies the content of the scheduler struct. Specifies the content of the C/C++ struct of the structure. The generated C++ type is scheduler_<name> and the generated C type is scheduler_<name>_t.

    create [ default ] : <block> (Mandatory)
        Specifies the constructor of the scheduler struct.
         - No option: no generated code,
         - default: generates code for trivial construction of the object. The const scheduler_<name>* object can be used to initialise the object. The trivial construction is fully performed only in C++.

    delete [ object OR default ] : <block> (Mandatory)
        Specifies the destructor of the scheduler struct.
         - No option: no generated code, the object is referenced by the void* handler ,
         - object: generates type conversion code, the object is referenced by the scheduler_<name>* object ,
         - default: generates code for trivial destruction of the object. The scheduler_<name>* object can be used to modify the value before deletion.

    schedule [ object OR default ] : <block> (Mandatory)
        Specifies the scheduling function of the scheduler.
         - No option: no generated code, the scheduler structure is referenced by the void* handler ,
         - object: generates type conversion code, the scheduler structure is referenced by the scheduler_<name>* object ,
         - default: generates code for trivial scheduling (no operation). The scheduler structure is referenced by the scheduler_<name>* object.
        The process to schedule is referenced by the SVM_Process process , the process state is referenced by the SVM_Process_State state.

    notification [ object OR default ] : <block> (Optional)
        Specifies the notification function of the scheduler.
         - No option: no generated code, the scheduler structure is referenced by the void* handler ,
         - object: generates type conversion code, the scheduler structure is referenced by the scheduler_<name>* object ,
         - default: generates code for trivial notification (no operation). The scheduler structure is referenced by the scheduler_<name>* object.
        The notification type is referenced by the SVM_Notification_Type type , the timer is referenced by the unsigned long int parameter.

    attach [ object OR default ] : <block> (Mandatory)
        Specifies the attach function of the scheduler.
         - No option: no generated code, the scheduler structure is referenced by the void* handler ,
         - object: generates type conversion code, the scheduler structure is referenced by the scheduler_<name>* object ,
         - default: generates code for trivial attachment (no operation). The scheduler structure is referenced by the scheduler_<name>* object.
        The process to attach is referenced by the SVM_Process process , the parameter is referenced by the unsigned long int parameter.

    detach [ object OR default ] : <block> (Mandatory)
        Specifies the detach function of the scheduler.
         - No option: no generated code, the scheduler structure is referenced by the void* handler ,
         - object: generates type conversion code, the scheduler structure is referenced by the scheduler_<name>* object ,
         - default: generates code for trivial detachment (no operation). The scheduler structure is referenced by the scheduler_<name>* object.
        The process to detach is referenced by the SVM_Process process , the parameter is referenced by the unsigned long int parameter.

    print [ object OR default ] : <block> (Mandatory)
        Specifies the string conversion of the scheduler structure.
         - No option: no generated code, the object is referenced by the const void* handler ,
         - object: generates type conversion code, the object is referenced by the const scheduler_<name>* object ,
         - default: generates code for trivial conversion of the object. The const scheduler_<name>* object and std::string/char* string can be used to access the object and modify the string. The trivial conversion is fully performed only in C++.

    help : <string> OR <block> (Optional)
        Specifies the help for this scheduler in the manual page.

Sequencers

    Anonymous section (Mandatory)
        Specifies the content of the sequencer struct. Specifies the content of the C/C++ struct of the structure. The generated C++ type is sequencer_<name> and the generated C type is sequencer_<name>_t.

    create [ default ] : <block> (Mandatory)
        Specifies the constructor of the sequencer struct.
         - No option: no generated code,
         - default: generates code for trivial construction of the object. The const sequencer_<name>* object can be used to initialise the object. The trivial construction is fully performed only in C++.

    delete [ object OR default ] : <block> (Mandatory)
        Specifies the destructor of the sequencer struct.
         - No option: no generated code, the object is referenced by the void* handler ,
         - object: generates type conversion code, the object is referenced by the sequencer_<name>* object ,
         - default: generates code for trivial destruction of the object. The sequencer_<name>* object can be used to modify the value before deletion.

    current [ object OR default ] : <block> (Mandatory)
        Specifies the sequencing function of the sequencer.
         - No option: no generated code, the sequencer structure is referenced by the void* handler ,
         - object: generates type conversion code, the sequencer structure is referenced by the sequencer_<name>* object ,
         - default: generates code for trivial sequencing (no operation). The sequencer structure is referenced by the sequencer_<name>* object.

    attach [ object OR default ] : <block> (Mandatory)
        Specifies the attach function of the sequencer.
         - No option: no generated code, the sequencer structure is referenced by the void* handler ,
         - object: generates type conversion code, the sequencer structure is referenced by the sequencer_<name>* object ,
         - default: generates code for trivial attachment (no operation). The sequencer structure is referenced by the sequencer_<name>* object.
        The process to attach is referenced by the SVM_Process process , the parameters are referenced by the SVM_Size argc and SVM_Parameter[] argv.

    detach [ object OR default ] : <block> (Mandatory)
        Specifies the detach function of the sequencer.
         - No option: no generated code, the sequencer structure is referenced by the void* handler ,
         - object: generates type conversion code, the sequencer structure is referenced by the sequencer_<name>* object ,
         - default: generates code for trivial detachment (no operation). The sequencer structure is referenced by the sequencer_<name>* object.
        The process to attach is referenced by the SVM_Process process , the parameters are referenced by the SVM_Size argc and SVM_Parameter[] argv.

    print [ object OR default ] : <block> (Mandatory)
        Specifies the string conversion of the sequencer structure.
         - No option: no generated code, the object is referenced by the const void* handler ,
         - object: generates type conversion code, the object is referenced by the const sequencer_<name>* object ,
         - default: generates code for trivial conversion of the object. The const sequencer_<name>* object and std::string/char* string can be used to access the object and modify the string. The trivial conversion is fully performed only in C++.

    help : <string> OR <block> (Optional)
        Specifies the help for this sequencer in the manual page.

Structures

    Anonymous section (Mandatory)
        Specifies the content of the C/C++ struct of the structure. The generated C++ type is struct_<name> and the generated C type is struct_<name>_t.

    delete [ object OR default ] : <block> (Mandatory)
        Specifies the destructor of the structure.
         - No option: no generated code, the object is referenced by the void* handler ,
         - object: generates type conversion code, the object is referenced by the struct_<name>* object ,
         - default: generates code for trivial destruction of the object. The struct_<name>* object can be used to modify the value before deletion.

    copy [ object OR default ] : <block> (Optional)
        Specifies the copy constructor of the structure.
         - No option: no generated code, the object is referenced by the const void* handler ,
         - object: generates type conversion code, the object is referenced by the const struct_<name>* object ,
         - default: generates code for trivial copy of the object. The const struct_<name>* object and struct_<name>* copy can be used to modify the copy.

    help : <string> OR <block> (Optional)
        Specifies the help for this structure in the manual page.

Functions

    Anonymous section (Mandatory)
        Specifies the actions done by the function. The function parameters are accessible with the SVM_Size argc and SVM_Parameter[] argv variables. The C/C++ macros:
        ARGV_VALUE(index,type)
        ARGV_PLUGIN(index,plugin,name)
        ARGV_MARKER(index)
        ARGV_KEYWORD(index)
        ARGV_STRUCT(index,plugin,name)
        ARGV_VARIABLE(index)
        NEW_VALUE(type,value)
        NEW_PLUGIN(plugin,name,value)
        NEW_STRUCT(plugin,name,value)
        NEW_STRING(raw_string)
        RAW_STRING(svm_string)
        NEW_BOOLEAN(raw_boolean)
        RAW_BOOLEAN(svm_boolean)
        NEW_NULL_VALUE(type)
        NEW_NULL_PLUGIN(plugin,name)
        NEW_NULL_STRUCT(plugin,name)
        ERROR_INTERNAL(irq,message)
        ERROR_EXTERNAL(plugin,name,message)
        CONST_PEP(plugin,name)
        CURRENT(object)
        RETURN
        VARIABLE_GLOBAL(variable)
        VARIABLE_LOCAL(variable)
        VARIABLE_DELETE(variable)
        can be used to shorten the code on basic parameters access and various common operations. When the function does not return a value, a C/C++ return statement is automatically added at the end of the code.

    help : <string> OR <block> (Optional)
        Specifies the help for this instruction in the manual page.

Options

    help : <string> OR <block> (Optional)
        Specifies the help for this option in the manual page.

Arguments

    help : <string> OR <block> (Optional)
        Specifies the help for this argument in the manual page.

Arguments(s)

    help : <string> OR <block> (Optional)
        Specifies the help for this extra arguments array in the manual page.

C/C++ code inclusion
    It is also possible to insert C/C++ code between two Simple Virtual Machine objects, using the code directive:
    code:
    %{
    	// C/C++ code
    %}

    Unlike the code directive present in the plugin header, the code of this directive is inserted at the corresponding place in the generated objects sequence. This insertion allows C/C++ definitions using structures and functions created above the code directive by the plugin generator.

  Substitutions
In all sections related to help (help, synopsis, description, example), some specific macros can be specified to be replaced by deployment values:

===PLUGINLIB===
    This macro will be replaced by the file name of the plugin, with its full installation path. The base name used in this substitution is the generated by default one. Do not use this macro when you plan to use another name.

===PLUGINMACHINELIB===
    This macro will be replaced by the file name of the plugin, with its relative installation path. The base name used in this substitution is the generated by default one. Do not use this macro when you plan to use another name.

===PLUGINBINDIR===
    This macro will be replaced by the directory where binaries linked to the plugin will be installed.

===PLUGINDATADIR===
    This macro will be replaced by the directory where static data files linked to the plugin will be installed.

===PLUGININCLUDEDIR===
    This macro will be replaced by the directory where header files linked to the plugin will be installed.

===PLUGINLIBDIR===
    This macro will be replaced by the directory where the plugin itself and all related shared objects linked to the plugin will be installed.

===PLUGINCONTACT===
    This macro will be replaced by the contact email of the creator of the plugin.

===SVMBIN===
    This macro will be replaced by the file name of the Simple Virtual Machine binary, with its full installation path. The base name used in this substitution is the generated by default one. Do not use this macro when you plan to use another name.

===SVMBINDIR===
    This macro will be replaced by the directory where the Simple Virtual Machine binary linked to the plugin will be installed.

===SVMINCLUDEDIR===
    This macro will be replaced by the directory where the Simple Virtual Machine header files linked to the plugin will be installed.

===SVMINTERFACEDIR===
    This macro will be replaced by the directory where the Simple Virtual Machine interface library linked to the plugin will be installed.

  File example
PLUGIN exemple
lang: "C++"
title: "A minimal plugin example"
includes:
%{
#include <string>
%}
DEFINE
TYPE exemple.type
%{
	explicit type_type(const std::string& s)
	:_s(s) {}
	operator std::string () const { return _s; }
	private:
		std::string _s;
%}
delete default:
%{}
#copy default:
#%{}
print default:
%{}
help: "Base type of this plugin"
INSTRUCTION exemple.instruction STR -> exemple.type
%{
	auto s = ARGV_VALUE(0,string);
	type_type *t = new type_type(std::string(s.string,s.size));
	return NEW_PLUGIN(exemple,type,t);
%}
help: "Creates an instance of the base type of this plugin"

RETURN VALUES
The svm_plugin command returns 0 when the Simple Virtual Machine plugin generator shell script is created, and 1 otherwise.

If an option is invalid, the command returns 2.

SEE ALSO
svm(1) for general documentation on the Simple Virtual Machine, in particular with plugin objects usage and low-level C/C++ plugin interface.

AUTHOR
The Simple Virtual Machine is designed, implemented and maintained by Julien Bruguier <===EMAILCONTACT===>.

BUGS
In case of bug on the virtual machine or on a plugin delivered with it, please send an email to the address above. Other plugins can not be covered here, so please contact preferably the author of the plugin whenever possible.