Plugins common interface

From PBS

Jump to: navigation, search

This page explains what plugins must implement, whatever the plugin type is.

A plugin is made out of 2 or more files correctly placed in PBS file system. Once the files are put correctly, it is needed to restart PBS for the plugins to be taken into account.

Contents

[edit] Description

First, each plugin begins with a description file, stored in the directory storing plugins of the desired type. Its name should be PluginName.desc.rb

The description file has to give some metadata about the plugin in a specific method:

module PBS

  module PluginType

    module Description

      class PluginName

        # Give the description of this plugin
        #
        # Return:
        # * map<Symbol,Object>: Information on the plugin: the following symbols can be provided:
        # ** :title (_String_): Name of the plugin
        # ** :description (_String_): Quick description
        # ** :bitmapName (_String_): Sub-path to the icon (from the Graphics/ directory)
        # ** :gemsDependencies (map<String,String>): List of require names to satisfy, with their corresponding gem install command
        # ** :libsDependencies (map<String,String>): List of library names to satisfy, with their corresponding URL to download from
        # ** :enabled (_Boolean_): Is this plugin enabled ?
        def pluginInfo
          return {
            # ...
          }
        end

      end

    end

  end

end

Please note the following important points:

  • The module hierarchy has to be respected.
  • The module name which has to be the Plugin type, that is the sub-directory name of the Plugins/ directory where the plugin is located (i.e. Types, Imports, Integration...)
  • The class name which has to be the Plugin name, that is the name of the plugin file (without extension).

The return value of the pluginInfo can be easily set following the notation:

:Symbol => Value

When you want to specify several symbols, separate them with ',' character. You can separate with new lines for your convenience.

For example:

return {
  :title => 'Shell Command',
  :description => 'Command line to be executed by a local shell',
  :bitmapName => 'Run.png'
}

[edit] Plugin file

Once the plugin description file is created, the real plugin file is stored just next to its description file, with .rb extension (i.e. PluginName.rb).

This file has to declare a class for the plugin:

module PBS

  module PluginType

    class PluginName

      # ...
 
    end

  end

end

Please note the following important points:

  • The module hierarchy has to be respected.
  • The module name which has to be the Plugin type, that is the sub-directory name of the Plugins/ directory where the plugin is located (i.e. Types, Imports, Integration...)
  • The class name which has to be the Plugin name, that is the name of the plugin file (without extension).

Then the content of the plugin class depends on each plugin type. Please refer to the following links for each plugin type:

Don't hesitate to see the already existing plugins to get it right.

[edit] Dependencies

In the description file, it is possible to specify dependencies (both libraries and gems).

For example:

:gemsDependencies => {
  'sqlite3' => 'sqlite3-ruby --version 1.2.3'
},
:libsDependencies => {
  'sqlite3.dll' => 'http://www.sqlite.org/sqlitedll-3_6_15.zip'
}

[edit] Gems dependencies

It is needed to specify a Gem dependency if your plugin uses a require myrubylib where myrubylib is taken from a Gem to be installed.

In this case, you have to declare a Gem dependency in the plugin description file. For example, if myrubylib is taken from the Gem myGem, you have to specify

:gemsDependencies => {
  'myrubylib' => 'myGem'
}

This will tell PBS to first test if require myrubylib works in the environment of the user, and if it fails, executes gem install myGem at PBS startup time.

[edit] Libraries dependencies

There is exactly the same behaviour for libraries as there is for gems: when a plugin needs to have a specific dynamic library (.dll on Windows, .so on Unix...), the plugin declares it as a library dependency, and gives the location where this library can be downloaded.

For example, if mydll.dll is needed and can be downloaded from http://www.myurl.com/mydll.dll, the plugin description file should specify the following:

:libsDependencies => {
  'mydll.dll' => 'http://www.myurl.com/mydll.dll'
}

Please note that it is possible to specify zip files in the downloadable URLs.

[edit] Shipping dependencies along with the plugin

It is also possible to ship dependencies directly with PBS installation, therefore ensuring it will work without any library/gem download and installation step.

This is the purpose of the ext/ directory in a Release.

For each platform supported by PBS, there is a ext/PlatformName/ directory, containing the following directories:

  • libs/: This directory contains sub-directories storing dynamic libraries. For example, copying mydll.dll in libs/MyDLL/mydll.dll will make PBS load mydll.dll at startup.
  • gems/: This directory contains gems installed directly by PBS. You can install yourself Gems inside, by specifying -i option.

    For example:

    gem install MyGem -i PBSPath/ext/PlatformName/gems
    
  • Any other directory is directly looked for ruby libraries: the required ruby library can be put either in a sub-directory or in a lib/ sub-directory.

    For example:

    PBSPath/ext/PlatformName/MyRubyLib/myrubylib.rb
    

    or

    PBSPath/ext/PlatformName/MyRubyLib/lib/myrubylib.rb
    

Using these methods, you should be able to ship your plugin's dependencies to your users.

Personal tools