pkger

README

Pkger

github.com/markbates/pkger is a tool for embedding static files into Go binaries. It will, hopefully, be a replacement for github.com/gobuffalo/packr/v2.

How it Works

Pkger is powered by the dark magic of Go Modules, so they're like, totally required.

With Go Modules pkger can resolve packages with accuracy. No more guessing and trying to figure out build paths, GOPATHS, etc... for this tired old lad.

With the module's path correctly resolved, it can serve as the "root" directory for that module, and all files in that module's directory are available.

Paths:

• Paths should use UNIX style paths: /cmd/pkger/main.go
• If unspecified the path's package is assumed to be the current module.
• Packages can specified in at the beginning of a path with a : seperator. github.com/markbates/pkger:/cmd/pkger/main.go
• There are no relative paths. All paths are absolute to the modules root.

"github.com/gobuffalo/buffalo:/go.mod" => $GOPATH/pkg/mod/github.com/gobuffalo/buffalo@v0.14.7/go.mod

Usage

Pkger's API is modeled on that of the os package in Go's standard library. This makes Pkger usage familiar to Go developers.

type Pkger interface {
  Parse(p string) (Path, error)
  Abs(p string) (string, error)
  AbsPath(Path) (string, error)
  Current() (here.Info, error)
  Info(p string) (here.Info, error)
  Create(name string) (File, error)
  MkdirAll(p string, perm os.FileMode) error
  Open(name string) (File, error)
  Stat(name string) (os.FileInfo, error)
  Walk(p string, wf filepath.WalkFunc) error
  Remove(name string) error
  RemoveAll(path string) error
}

type File interface {
  Close() error
  Abs() (string, error)
  Info() here.Info
  Name() string
  Open(name string) (http.File, error)
  Path() Path
  Read(p []byte) (int, error)
  Readdir(count int) ([]os.FileInfo, error)
  Seek(offset int64, whence int) (int64, error)
  Stat() (os.FileInfo, error)
  Write(b []byte) (int, error)
}

├── go.mod
├── go.sum
├── main.go
├── public
│   ├── images
│   │   ├── mark-small.png
│   │   ├── img1.png
│   │   ├── mark_250px.png
│   │   └── mark_400px.png
│   └── index.html

package main

import (
	"fmt"
	"log"
	"os"
	"text/tabwriter"
	"time"

	"github.com/markbates/pkger"
)

func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}

func run() error {
	w := tabwriter.NewWriter(os.Stdout, 0, 0, 0, ' ', tabwriter.Debug)
	defer w.Flush()

	return pkger.Walk("/public", func(path string, info os.FileInfo, err error) error {
		if err != nil {
			return err
		}

		fmt.Fprintf(w,
			"%s \t %d \t %s \t %s \t\n",
			info.Name(),
			info.Size(),
			info.Mode(),
			info.ModTime().Format(time.RFC3339),
		)

		return nil
	})

}

Output Without Packing

# compile the go binary as usual and run the app:
$ go build -v; ./app
/public                       | 128      | drwxr-xr-x | 2019-10-17T15:02:57-04:00 |
/public/images                | 192      | drwxr-xr-x | 2019-10-17T15:02:57-04:00 |
/public/images/mark-small.png | 649549   | -rw-r--r-- | 2019-10-17T15:02:56-04:00 |
/public/images/img1.png       | 50401191 | -rw-r--r-- | 2019-10-17T15:02:57-04:00 |
/public/images/mark_250px.png | 27718    | -rw-r--r-- | 2019-10-17T15:02:57-04:00 |
/public/images/mark_400px.png | 63543    | -rw-r--r-- | 2019-10-17T15:02:57-04:00 |
/public/index.html            | 257      | -rw-r--r-- | 2019-10-17T15:02:57-04:00 |

Output With Packing

# run the pkger cli to generate a pkged.go file:
$ pkger

# compile the go binary as usual and run the app:
$ go build -v; ./app
/                      | 128      | drwxr-xr-x | 2019-10-17T15:02:57-04:00 |
/images                | 192      | drwxr-xr-x | 2019-10-17T15:02:57-04:00 |
/images/mark-small.png | 649549   | -rw-r--r-- | 2019-10-17T15:02:56-04:00 |
/images/img1.png       | 50401191 | -rw-r--r-- | 2019-10-17T15:02:57-04:00 |
/images/mark_250px.png | 27718    | -rw-r--r-- | 2019-10-17T15:02:57-04:00 |
/images/mark_400px.png | 63543    | -rw-r--r-- | 2019-10-17T15:02:57-04:00 |
/index.html            | 257      | -rw-r--r-- | 2019-10-17T15:02:57-04:00 |

Documentation

Index

• Constants
• func Abs(p string) (string, error)
• func AbsPath(p here.Path) (string, error)
• func Apply(pkg pkging.Pkger, err error) error
• func Create(p string) (pkging.File, error)
• func Current() (here.Info, error)
• func Info(p string) (here.Info, error)
• func MkdirAll(p string, perm os.FileMode) error
• func Open(p string) (pkging.File, error)
• func Parse(p string) (here.Path, error)
• func Remove(name string) error
• func RemoveAll(name string) error
• func Stat(name string) (os.FileInfo, error)
• func Walk(p string, wf filepath.WalkFunc) error

Constants

const Version = "v0.3.2"

Version of pkger

Functions

func Abs

func Abs(p string) (string, error)

Abs returns an absolute representation of path. If the path is not absolute it will be joined with the current working directory to turn it into an absolute path. The absolute path name for a given file is not guaranteed to be unique. Abs calls Clean on the result.

func AbsPath

func AbsPath(p here.Path) (string, error)

AbsPath returns an absolute representation of here.Path. If the path is not absolute it will be joined with the current working directory to turn it into an absolute path. The absolute path name for a given file is not guaranteed to be unique. AbsPath calls Clean on the result.

func Apply

func Apply(pkg pkging.Pkger, err error) error

Apply will wrap the current implementation of pkger.Pkger with the new pkg. This allows for layering of pkging.Pkger implementations.

func Create

func Create(p string) (pkging.File, error)

Create creates the named file with mode 0666 (before umask) - It's actually 0644, truncating it if it already exists. If successful, methods on the returned File can be used for I/O; the associated file descriptor has mode O_RDWR.

func Current

func Current() (here.Info, error)

Current returns the here.Info representing the current Pkger implementation.

func Info

func Info(p string) (here.Info, error)

Info returns the here.Info of the here.Path

func MkdirAll

func MkdirAll(p string, perm os.FileMode) error

MkdirAll creates a directory named path, along with any necessary parents, and returns nil, or else returns an error. The permission bits perm (before umask) are used for all directories that MkdirAll creates. If path is already a directory, MkdirAll does nothing and returns nil.

func Open

func Open(p string) (pkging.File, error)

Open opens the named file for reading. If successful, methods on the returned file can be used for reading; the associated file descriptor has mode O_RDONLY.

func Parse

func Parse(p string) (here.Path, error)

Parse the string in here.Path format.

func Remove

func Remove(name string) error

Remove removes the named file or (empty) directory.

func RemoveAll

func RemoveAll(name string) error

RemoveAll removes path and any children it contains. It removes everything it can but returns the first error it encounters. If the path does not exist, RemoveAll returns nil (no error).

func Stat

func Stat(name string) (os.FileInfo, error)

Stat returns a FileInfo describing the named file.

func Walk

func Walk(p string, wf filepath.WalkFunc) error

Walk walks the file tree rooted at root, calling walkFn for each file or directory in the tree, including root. All errors that arise visiting files and directories are filtered by walkFn. The files are walked in lexical order, which makes the output deterministic but means that for very large directories Walk can be inefficient. Walk does not follow symbolic links. - That is from the standard library. I know. Their grammar teachers can not be happy with them right now.