pkger

Documentation

Overview

Package pkger provides a task for the "github.com/markbates/pkger/cmd/pkger" Go module command. "pkger" is a tool for embedding static files into Go binaries.

See https://pkg.go.dev/github.com/markbates/pkger for more details about "pkger". The source code of "goimports" is available at https://github.com/markbates/pkger.

Official "Static Assets Embedding"

Please note that the "pkger" project might be superseded and discontinued due to the official Go toolchain support for embedding static assets (files) that will most probably be released with Go version 1.16.

Please see https://go.googlesource.com/proposal/+/master/design/draft-embed.md and https://github.com/markbates/pkger/issues/114 for more details.

"Monorepo" Workaround

"pkger" tries to mimic the Go standard library and the way how the Go toolchain handles modules, but is therefore also affected by its problems and edge cases. When the "pkger" command is used from the root of a Go module repository, the directory where the "go.mod" file is located, and there is no valid Go source file, the command will fail because it internally uses the same logic like the "list" command of the Go toolchain ("go list"). Therefore a "dummy" Go source file may need to be created as a workaround. This is mostly only required for repositories that use a "monorepo" layout where one or more "main" packages are placed in a subdirectory relative to the root directory, e.g. "apps" or "cmd". For repositories where the root directory already has a Go package, that does not contain any build constraints/tags, or uses a "library" layout, a "dummy" file is probably not needed.

Please see https://github.com/markbates/pkger/issues/109 and https://github.com/markbates/pkger/issues/121 for more details.

Index

• Constants
• type Option
  • func WithEnv(env map[string]string) Option
  • func WithExtraArgs(extraArgs ...string) Option
  • func WithIncludes(includes ...string) Option
  • func WithModulePath(path string) Option
  • func WithModuleVersion(version *semver.Version) Option
• type Options
  • func NewOptions(opts ...Option) (*Options, error)
• type Task
  • func New(w wand.Wand, ac app.Config, opts ...Option) (*Task, error)
  • func (t *Task) BuildParams() []string
  • func (t *Task) Env() map[string]string
  • func (t *Task) ID() *project.GoModuleID
  • func (t *Task) Kind() task.Kind
  • func (t *Task) Options() task.Options

Constants

const (
	// DefaultGoModulePath is the default module import path.
	DefaultGoModulePath = "github.com/markbates/pkger/cmd/pkger"

	// DefaultGoModuleVersion is the default module version.
	DefaultGoModuleVersion = "v0.17.1"

	// MonorepoWorkaroundDummyFileContent is the file content for MonorepoWorkaroundDummyFileName.
	MonorepoWorkaroundDummyFileContent = `// Code generated by wand. DELETE THIS FILE IF NOT REMOVED AUTOMATICALLY.

package main`

	// MonorepoWorkaroundDummyFileName is the filename for the "dummy" workaround file.
	MonorepoWorkaroundDummyFileName = "wand_task_pkger_dummy_workaround"

	// TaskName is the name of the task.
	TaskName = "pkger"
)

Types

type Option

type Option func(*Options)

Option is a task option.

func WithEnv

func WithEnv(env map[string]string) Option

WithEnv sets the task specific environment.

func WithExtraArgs

func WithExtraArgs(extraArgs ...string) Option

WithExtraArgs sets additional arguments to pass to the command.

func WithIncludes

func WithIncludes(includes ...string) Option

WithIncludes adds the relative paths of files and directories that should be included. By default the paths will be detected by pkger itself when used within any of the packages of the target Go module.

func WithModulePath

func WithModulePath(path string) Option

WithModulePath sets the module import path. Defaults to DefaultGoModulePath.

func WithModuleVersion

func WithModuleVersion(version *semver.Version) Option

WithModuleVersion sets the module version. Defaults to DefaultGoModuleVersion.

type Options

type Options struct {
	// contains filtered or unexported fields
}

Options are task options.

func NewOptions

func NewOptions(opts ...Option) (*Options, error)

NewOptions creates new task options.

type Task

type Task struct {
	// contains filtered or unexported fields
}

Task is a task for the "github.com/markbates/pkger/cmd/pkger" Go module command. "pkger" is a tool for embedding static files into Go binaries.

See https://pkg.go.dev/github.com/markbates/pkger for more details about "pkger". The source code of "goimports" is available at https://github.com/markbates/pkger.

Official "Static Assets Embedding"

Please note that the "pkger" project might be superseded and discontinued due to the official Go toolchain support for embedding static assets (files) that will most probably be released with Go version 1.16.

Please see https://go.googlesource.com/proposal/+/master/design/draft-embed.md and https://github.com/markbates/pkger/issues/114 for more details.

"Monorepo" Workaround

"pkger" tries to mimic the Go standard library and the way how the Go toolchain handles modules, but is therefore also affected by its problems and edge cases. When the "pkger" command is used from the root of a Go module repository, the directory where the "go.mod" file is located, and there is no valid Go source file, the command will fail because it internally uses the same logic like the "list" command of the Go toolchain ("go list"). Therefore a "dummy" Go source file may need to be created as a workaround. This is mostly only required for repositories that use a "monorepo" layout where one or more "main" packages are placed in a subdirectory relative to the root directory, e.g. "apps" or "cmd". For repositories where the root directory already has a Go package, that does not contain any build constraints/tags, or uses a "library" layout, a "dummy" file is probably not needed.

Please see https://github.com/markbates/pkger/issues/109 and https://github.com/markbates/pkger/issues/121 for more details.

func New

func New(w wand.Wand, ac app.Config, opts ...Option) (*Task, error)

New creates a new task for the "github.com/markbates/pkger/cmd/pkger" Go module command.

func (*Task) BuildParams

func (t *Task) BuildParams() []string

BuildParams builds the parameters.

func (*Task) Env

func (t *Task) Env() map[string]string

Env returns the task specific environment.

func (*Task) ID

func (t *Task) ID() *project.GoModuleID

ID returns the identifier of the Go module.

func (*Task) Kind

func (t *Task) Kind() task.Kind

Kind returns the task kind.

func (*Task) Options

func (t *Task) Options() task.Options

Options returns the task options.