assets

README

assets

Go resource embedding library which doesn't require go generate at all.

Overview

Resource Embedding in Go is cumbersome especially when it involves custom commands and go generate. assets is another resource embedding library which doesn't require any of them. It extracts a zip file bundled with your binary and provides a file path to the contents.

Features

• no custom commands
• no go generate
• only requires cat and zip when go build
• uses local files when go run or go test
• easily extendable interface

Getting Started

Prerequisites

We assume you have a Go project and a directory named assets for resources in the project root. This directory name can be easily configured but for the sake of explanation we call the directory assets.

$ tree .
.
├── Makefile
├── assets
│   └── templates
│       └── hello.tmpl
└── main.go

2 directories, 3 files

Install

First go get the library.

$ go get github.com/ichiban/assets

Then import it.

import "github.com/ichiban/assets"

Usage

In Go files, we can get the locator which points to assets directory by calling assets.New(). Note that we'll need to close it in the end.

	l, err := assets.New()
	if err != nil {
		log.Fatalf("assets.New() failed: %v", err)
	}
	defer l.Close()
	
	log.Printf("assets: %s", l.Path)

When we build it and bundle with a resource zip file, the locator will point to the contents of the zip file which is extracted into a temporary directory.

Build

To start with, we need to build the binary as usual.

$ mkdir -p bin 
$ go build -o bin/hello

Then, zip resources into a zip file. We need to enter assets directory to make a proper zip file.

$ mkdir -p zip
$ cd assets
$ zip -r ../zip/assets.zip .
  adding: templates/ (stored 0%)
  adding: templates/hello.tmpl (stored 0%)
$ cd ..

A proper zip file looks like this:

$ unzip -l zip/assets.zip 
Archive:  zip/assets.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
        0  11-05-2018 22:31   templates/
       14  11-05-2018 21:31   templates/hello.tmpl
---------                     -------
       14                     2 files

Finally, we can bundle resources by cat the binary and the zip file. Prepending an executable makes the zip offset values off by the size of the executable. We can fix the offsets by zip -A (zip --adjust-sfx).

$ cat bin/hello zip/assets.zip > bin/hello-bundled
$ zip -A bin/hello-bundled 
Zip entry offsets appear off by 3345496 bytes - correcting...
$ chmod +x bin/hello-bundled

Interestingly, the bundled binary is an executable and also a zip file.

$ unzip -l bin/hello-bundled 
Archive:  bin/hello-bundled
  Length      Date    Time    Name
---------  ---------- -----   ----
        0  11-05-2018 22:31   templates/
       14  11-05-2018 21:31   templates/hello.tmpl
---------                     -------
       14                     2 files

$ bin/hello-bundled 
2018/11/30 16:22:13 assets: /var/folders/xt/6z9sk1dx1d734ltxxst16_h00000gn/T/hello-bundled882816570
Hello, World!

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Acknowledgments

This project is inspired by Zgok.

Documentation

Overview

Package assets provides an environment-agnostic means of locating resources such as stylesheets, scripts, images, and templates.

Index

• Variables
• type Locator
  • func New(strategies ...Strategy) (*Locator, error)
• type Strategy
  • func Env(key string) Strategy
  • func Src(dirName string) Strategy
  • func Unzip() Strategy

Variables

var DefaultStrategies = []Strategy{Env("ASSETS"), Unzip(), Src("assets")}

DefaultStrategies are a recommended sequence of strategies.

Types

type Locator

type Locator struct {
	io.Closer
	Path string
}

Locator holds the path to the root directory of resources. Caller must close the locator when it's not needed anymore. After it had closed, accessing resources under the path is undefined.

func New

func New(strategies ...Strategy) (*Locator, error)

New creates an instance of locator. It tries the given strategies from left to right until one strategy succeeds at locating resources. When no strategies couldn't locate resources, it returns non-nil error. If no strategies are given, it uses DefaultStrategies.

type Strategy

type Strategy interface {
	io.Closer
	Path() (string, error)
}

Strategy represents a means to locate resources.

func Env

func Env(key string) Strategy

Env locates resources by environment variable. If the environment variable identified by the key has non-empty string value, it uses the value as the root path to resources. Otherwise, it fails.

func Src

func Src(dirName string) Strategy

Src locates resources by path of the caller of assets.New. Let's assume assets.New is called in /foo/bar/baz.go and dirName is assets, it first tries /foo/bar/assets, then /foo/assets, then /assets. If one of them exists, it returns it. Otherwise, it fails.

func Unzip

func Unzip() Strategy

Unzip locates resources by unzipping the executable. If it detects an appended zip file in the executable binary, it extracts resources in a temporary directory and returns the path. Otherwise, it fails.