Skip to content

Latest commit

 

History

History
122 lines (91 loc) · 4.12 KB

plugins.rst

File metadata and controls

122 lines (91 loc) · 4.12 KB
Raw

Plugins

Overview

A {Singularity} plugin is a package that can be dynamically loaded by the {Singularity} runtime, augmenting {Singularity} with experimental, non-standard and/or vendor-specific functionality. Currently, plugins are able to add commands and flags to {Singularity}. In the future, plugins will also be able to interface with more complex subsystems of the {Singularity} runtime.

Using Plugins

The list command prints the currently installed plugins.

$ singularity plugin list
There are no plugins installed.

Plugins are packaged and distributed as binaries encoded with the versatile Singularity Image Format (SIF). However, plugin authors may also distribute the source code of their plugins. A plugin can be compiled from its source code with the compile command. A sample plugin test-plugin is included with the {Singularity} source code.

$ singularity plugin compile examples/plugins/test-plugin/

Upon successful compilation, a SIF file will appear in the directory of the plugin's source code.

$ ls examples/plugins/test-plugin/ | grep sif
test-plugin.sif

Note

Currently, all plugins must be compiled from the {Singularity} source code tree.

Also, the plugins mechanism for the Go language that {Singularity} is written in is quite restrictive - it requires extremely close version matching of packages used in a plugin to the ones used in the program the plugin is built for. Additionally {Singularity} is using build time config to get the source tree location for singularity plugin compile so that you don't need to export environment variables etc, and there isn't mismatch between package path information that Go uses. This means that at present you must:

  • Build plugins using the exact same version of the source code, in the same location, as was used to build the {Singularity} executable.
  • Use the exact same version of Go that was used to build the executable when compiling a plugin for it.

Every plugin encapsulates various information such as the plugin's author, the plugin's version, etc. To view this information about a plugin, use the inspect command.

$ singularity plugin inspect examples/plugins/test-plugin/test-plugin.sif
Name: sylabs.io/test-plugin
Description: This is a short test plugin for {Singularity}
Author: Michael Bauer
Version: 0.0.1

To install a plugin, use the install command. This operation requires root privilege.

$ sudo singularity plugin install examples/plugins/test-plugin/test-plugin.sif
$ singularity plugin list
ENABLED  NAME
    yes  sylabs.io/test-plugin

After successful installation, the plugin will automatically be enabled. Any plugin can be disabled with the disable command and re-enabled with the enable command. Both of these operations require root privilege.

$ sudo singularity plugin disable sylabs.io/test-plugin
$ singularity plugin list
ENABLED  NAME
     no  sylabs.io/test-plugin
$ sudo singularity plugin enable sylabs.io/test-plugin
$ singularity plugin list
ENABLED  NAME
    yes  sylabs.io/test-plugin

Finally, to uninstall a plugin, use the uninstall command. This operation requires root privilege.

$ sudo singularity plugin uninstall sylabs.io/test-plugin
Uninstalled plugin "sylabs.io/test-plugin".
$ singularity plugin list
There are no plugins installed.

Writing a Plugin

Developers interested in writing {Singularity} plugins can get started by reading the Go documentation for the plugin package. Furthermore, reading through the source code for the example plugins will prove valuable. More detailed plugin development documentation is in the works and will be released at a future date.