Documentation

Index

• Constants
• type ActionFlagAdder
• type BoolFlagHook
• type CommandAdder
• type Config
• type FlagCallbackFn
• type HookRegistration
• type Initializer
• type Manifest
• type Plugin
• type RootFlagAdder
• type StringFlagHook

Constants

const DefaultConfigSymbol = "DefaultConfig"

DefaultConfigSymbol is the name of a variable that a plugin can optionally define which stores the plugins config type initialized with default values. This variable will be used when installing a plugin to initialize its config file to the appropriate default values. If empty, default Go initialization values will be used.

type Config struct {
        FeatureEnabled bool
}

var DefaultConfig = &Config{true}

const PluginSymbol = "Plugin"

PluginSymbol is the name of a variable of type plugin.Plugin which all plugin implementations MUST define.

Variables

This section is empty.

Functions

This section is empty.

Types

type ActionFlagAdder

type ActionFlagAdder interface {
	ActionFlagAdd() []*pflag.Flag
}

ActionFlagAdder is the interface for a plugin which wishes to add a flag to the action command group (run, exec, shell, instance)

type BoolFlagHook

type BoolFlagHook struct {
	Flag     pflag.Flag
	Callback FlagCallbackFn
}

BoolFlagHook provides plugins the ability to add a bool flag to the action command group. A flag of this type does not take arguments.

type CommandAdder

type CommandAdder interface {
	CommandAdd() []*cobra.Command
}

CommandAdder allows a plugin to add new command(s) to the singularity binary

type Config

type Config interface{}

Config is an empty interface which can optionally store plugin-specific configuration files. This can contain any fields, as long as they are able to be Marshaled/Unmarshaled into/from YAML format. Optionally this interface can implement the yaml.Marshaler and yaml.Unmarshaler interfaces for custom parsing behavior. For ease of use, Config should generally be assigned to a pointer to a concrete type stored inside the plugin's Initializer implementation.

For an example of this design pattern and others, see the example plugins included with Singularity.

type FlagCallbackFn

type FlagCallbackFn func(*pflag.Flag, *singularity.EngineConfig)

FlagCallbackFn is the callback function type for flag hooks. It takes two arguments:

*pflag.Flag:

A pointer to a pflag.Flag object. This object is guaranteed to have been
added to the action FlagSet, and will contain the value the flag was
set to if it was set.

*singularity.EngineConfig:

A pointer to the EngineConfig object which allows the plugin to make
modifications to the runtime parameters of the container

This function is guaranteed to be called after the flag has been parsed by pflag, and before the starter binary is executed.

type HookRegistration

type HookRegistration interface {
	RegisterStringFlag(StringFlagHook) error
	RegisterBoolFlag(BoolFlagHook) error
}

HookRegistration exposes functions to a plugin during Init() which allow the plugin to register its plugin hooks.

type Initializer

type Initializer interface {
	Initialize(HookRegistration)
}

Initializer is an interface which stores the object of a plugin's implementation. The Initialize method allows the plugin to register its functions with the Runtime to be called later

type Manifest

type Manifest struct {
	// Name is, by convention, a fully-qualified domain name which uniquely identifies a plugin.
	// This convention is not enforced, but rather is best practice.
	//
	// Good Names:
	//     - sylabs.io/test-plugin
	//     - github.com/user/repo
	//
	// Bad Names:
	//     - test-plugin
	Name string `json:"name"`
	// Author of the plugin
	Author string `json:"author"`
	// Version describes the SemVer of the plugin
	Version string `json:"version"`
	// Description describes the plugin
	Description string `json:"description"`
}

Manifest is the plugin manifest, stored as a data object in the plugin SIF

type Plugin

type Plugin struct {
	Manifest
	Config
	Initializer
}

Plugin is the "meta-type" which encompasses the plugins implementation struct (PluginType interface), and a type (potentially more to be added) which is defined in the syplugin package (Manifest). The plugin implementation must have an exported symbol named "Plugin" of type syplugin.Plugin.

An example of how this will look from a plugins main package:

type myPluginImplementation struct {...}

func (pl myPluginImplementation) Init() {
        // Do some initialization work!
}

var Plugin = syplugin.Plugin{
        syplugin.Manifest{
                "MyPlugin",
                "Michael Bauer",
                "v0.0.1",
                "This is a test plugin",
        },
        myPluginImplementation{...},
}

In addition, type Plugin also exposes useful helper methods to a plugin

type RootFlagAdder

type RootFlagAdder interface {
	RootFlagAdd() []*pflag.Flag
}

RootFlagAdder is the interface for a plugin which wishes to add a flag to the root singularity command

type StringFlagHook

type StringFlagHook struct {
	Flag     pflag.Flag
	Callback FlagCallbackFn
}

StringFlagHook provides plugins the ability to add a string flag to the action command group. A flag of this type takes one argument as a string. The string value which the flag is set to can be then converted to other types, such as int.