pgo

README

pgo (Flexible crossplatform golang plugin manager)

This library is compatible with Go 1.17+

Please refer to CHANGELOG.md if you encounter breaking changes.

• Motivation
• Usage
• Contribution
• License

Motivation

The goal of this library is to simplify build and management GoLang plugins.

Go plugin comes with the following constrains,

• go version, os and cpu architecture match
• go.mod dependencies have to be the same
• once plugins is loaded can not be reloaded or unloaded

Since GoLang plugins rely on shared libraries in order to address the os,cpu architecture match, with this project you can build ahead of time the same plugin for various platform and go version, the build plugin uses the following naming: NAME_GO_VERSION_GOOS_GOARCH.so

This project allow you to rebuild the same plugin source and reload it as long there is available memory, note that previous loaded plugins stay in memory.

Each plugin is stamped by SCN time based sequence change number which allows to load only the newest version of the plugin.

Time based sequence change number allows application build/design with "initial SCN version", that can be supplemented with plugin above that version.

Usage

Building plugin

To build plugin:

package pgo_test

import (
	"github.com/viant/pgo"
	"log"
)
//Example_Build build plugin example
func Example_Build() {
	options := &pgo.Options{
		SourceURL:  "internal/builder/testdata/my.zip",
		DestURL:    "~/plugin/",
		Os:         "linux",
		Arch:       "amd64",
		Version:    "1.17.6",
		Name:       "main",
		WithLogger: true,
	}
	err := pgo.Build(options)
	if err != nil {
		log.Fatalln(err)
	}
}

Load plugins

package example

import (
	"github.com/viant/pgo/build"
	"github.com/viant/pgo/manager"
	"path"
	"time"
	"context"
    "fmt"
)
func Example_Open() {
	
	var buildTime time.Time
	var initScn = build.NewSequenceChangeNumber(buildTime)
	srv := manager.New(initScn)
	runtime := build.NewRuntime()
	pluginName := runtime.PluginName("main.so")
	basePluginPath := "/var/some_path"
	goPlugin, err := srv.Open(context.Background(), path.Join(basePluginPath, pluginName))
	if manager.IsPluginOutdated(err) {
		//plugin not needed, already the newest version is loaded or initial SCN is more recent
	}
	if goPlugin != nil {
		xx, err := goPlugin.Lookup("someSymbol")
		fmt.Printf("%T(%v) %v\n", xx, xx, err)
	}
}

Contributing to pgo

pgo is an open source project and contributors are welcome!

See TODO list

Credits and Acknowledgements

Library Author: Adrian Witas, Kamil Larysz

Documentation

Index

• func Build(option *Options, opts ...build.Option) error
• type Options
  • func (o *Options) Init()
  • func (o *Options) Validate() error

Functions

func Build

func Build(option *Options, opts ...build.Option) error

Build builds plugin

Types

type Options

type Options struct {
	SourceURL    []string          `short:"s" long:"src" description:"plugin source project location"  `
	DestURL      string            `short:"d" long:"dest" description:"plugin dest location"  `
	Name         string            `short:"n" long:"name" description:"plugin name, default main"  `
	Arch         string            `short:"a" long:"arch" description:"amd64|arm64"  `
	Os           string            `short:"o" long:"os" description:"linux|darwin"  `
	Version      string            `short:"v" long:"ver" description:"go version"  `
	ModPath      string            `short:"m" long:"modpath" description:"go mod path"  `
	MainPath     string            `short:"p" long:"mainpath" description:"main path in project"  `
	BuildArgs    []string          `short:"b" long:"barg" description:"build args" `
	LdFlags      string            `short:"f" long:"f" description:"ldflags" `
	Env          map[string]string `short:"e" long:"env" description:"env variables" `
	BuildMode    string            `short:"b" long:"bmode" description:"build mode" choice:"exec" choice:"plugin" `
	UseContainer bool              `short:"N" long:"container" description:"use container to ensure consistency" `
	Compression  string            `short:"c" long:"compression" description:"compression codec" choice:"gzip"  `
	WithLogger   bool              `short:"l" long:"log" description:"with debug logger" `
	GoPath       string            `short:"p" long:"gopath" description:"go path" `
	GoRoot       string            `short:"r" long:"goroot" description:"go root" `
}

Options options

func (*Options) Init

func (o *Options) Init()

Init initialises option

func (*Options) Validate

func (o *Options) Validate() error

Validate check if option are valid