Documentation

Index

Constants

View Source
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}
    
    View Source
    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.