Skip to content
The simple and easy way to embed static files into Go binaries.
Go Makefile Other
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
builder dep deit (#212) Jun 24, 2019
example packr with http.FileServer serves files as case-sensitive fixes #102 (#… Oct 31, 2018
fixtures packr with http.FileServer serves files as case-sensitive fixes #102 (#… Oct 31, 2018
packr remove withstack and fix windows (#187) Apr 4, 2019
v2 Revert "box.Open: Do not call file.NewFileR when IsDir true, fix #198 ( Jul 8, 2019
.codeclimate.yml Initial Commit Mar 15, 2017
.gitignore v2.0.0 (#94) Nov 14, 2018
.gometalinter.json v2.0.0 (#94) Nov 14, 2018
.goreleaser.yml generated goreleaser Nov 14, 2018
.goreleaser.yml.plush updated goreleaser Nov 14, 2018
LICENSE.txt Initial Commit Mar 15, 2017
Makefile version bump: v1.21.0 Nov 14, 2018
README.md Fix link to http.FileSystem (#174) Mar 16, 2019
SHOULDERS.md version bump: v1.30.0 Jun 24, 2019
azure-pipelines.yml error if not in GOPATH and modules aren't on (#184) Mar 30, 2019
azure-tests.yml install Feb 24, 2019
box.go dep deit (#212) Jun 24, 2019
box_test.go v2.0.0 (#94) Nov 14, 2018
env.go moved all virtual file stuff to packd Oct 27, 2018
file.go this backports some changes from the version of v1 in v2 to make the … Oct 27, 2018
go.mod dep diet Jun 24, 2019
go.sum version bump: v1.30.1 Jun 24, 2019
http_box_test.go reverted the http case insensitive fix for the time being Nov 3, 2018
packr.go reverts lower case issue Nov 3, 2018
packr_test.go packr with http.FileServer serves files as case-sensitive fixes #102 (#… Oct 31, 2018
version.go version bump: v1.30.1 Jun 24, 2019
walk.go remove withstack and fix windows (#187) Apr 4, 2019
walk_test.go Adds a new WalkPrefix function (#79) Aug 8, 2018

README.md

packr (v1)

GoDoc

Packr has been updated to v2! Please read the ./v2/README.md file for more details.


Packr is a simple solution for bundling static assets inside of Go binaries. Most importantly it does it in a way that is friendly to developers while they are developing.

Intro Video

To get an idea of the what and why of packr, please enjoy this short video: https://vimeo.com/219863271.

Installation

To install Packr utility

$ go get -u github.com/gobuffalo/packr/packr

To get the dependency

$ go get -u github.com/gobuffalo/packr

Usage

In Code

The first step in using Packr is to create a new box. A box represents a folder on disk. Once you have a box you can get string or []byte representations of the file.

// set up a new box by giving it a (relative) path to a folder on disk:
box := packr.NewBox("./templates")

// Get the string representation of a file, or an error if it doesn't exist:
html, err := box.FindString("index.html")

// Get the []byte representation of a file, or an error if it doesn't exist:
html, err := box.FindBytes("index.html")

What is a Box?

A box represents a folder, and any sub-folders, on disk that you want to have access to in your binary. When compiling a binary using the packr CLI the contents of the folder will be converted into Go files that can be compiled inside of a "standard" go binary. Inside of the compiled binary the files will be read from memory. When working locally the files will be read directly off of disk. This is a seamless switch that doesn't require any special attention on your part.

Example

Assume the follow directory structure:

├── main.go
└── templates
    ├── admin
    │   └── index.html
    └── index.html

The following program will read the ./templates/admin/index.html file and print it out.

package main

import (
  "fmt"

  "github.com/gobuffalo/packr"
)

func main() {
  box := packr.NewBox("./templates")

  s, err := box.FindString("admin/index.html")
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(s)
}

Development Made Easy

In order to get static files into a Go binary, those files must first be converted to Go code. To do that, Packr, ships with a few tools to help build binaries. See below.

During development, however, it is painful to have to keep running a tool to compile those files.

Packr uses the following resolution rules when looking for a file:

  1. Look for the file in-memory (inside a Go binary)
  2. Look for the file on disk (during development)

Because Packr knows how to fall through to the file system, developers don't need to worry about constantly compiling their static files into a binary. They can work unimpeded.

Packr takes file resolution a step further. When declaring a new box you use a relative path, ./templates. When Packr receives this call it calculates out the absolute path to that directory. By doing this it means you can be guaranteed that Packr can find your files correctly, even if you're not running in the directory that the box was created in. This helps with the problem of testing, where Go changes the pwd for each package, making relative paths difficult to work with. This is not a problem when using Packr.


Usage with HTTP

A box implements the http.FileSystem interface, meaning it can be used to serve static files.

package main

import (
  "net/http"

  "github.com/gobuffalo/packr"
)

func main() {
  box := packr.NewBox("./templates")

  http.Handle("/", http.FileServer(box))
  http.ListenAndServe(":3000", nil)
}

Building a Binary (the easy way)

When it comes time to build, or install, your Go binary, simply use packr build or packr install just as you would go build or go install. All flags for the go tool are supported and everything works the way you expect, the only difference is your static assets are now bundled in the generated binary. If you want more control over how this happens, looking at the following section on building binaries (the hard way).

Building a Binary (the hard way)

Before you build your Go binary, run the packr command first. It will look for all the boxes in your code and then generate .go files that pack the static files into bytes that can be bundled into the Go binary.

$ packr

Then run your go build command like normal.

NOTE: It is not recommended to check-in these generated -packr.go files. They can be large, and can easily become out of date if not careful. It is recommended that you always run packr clean after running the packr tool.

Cleaning Up

When you're done it is recommended that you run the packr clean command. This will remove all of the generated files that Packr created for you.

$ packr clean

Why do you want to do this? Packr first looks to the information stored in these generated files, if the information isn't there it looks to disk. This makes it easy to work with in development.


Building/Moving a portable release

When it comes to building multiple releases you typically want that release to be built in a specific directory.

For example: ./releases

However, because passing a .go file requires absolute paths, we must compile the release in the appropriate absolute path.

GOOS=linux GOARCH=amd64 packr build

Now your project_name binary will be built at the root of your project dir. Great!

All that is left to do is to move that binary to your release dir:

Linux/macOS/Windows (bash)

mv ./project_name ./releases

Windows (cmd):

move ./project_name ./releases

Powershell:

Move-Item -Path .\project_name -Destination .\releases\

If you target for Windows when building don't forget that it's project_name.exe

Now you can make multiple releases and all of your needed static files will be available!

Summing it up:

Example Script for building to 3 common targets:

GOOS=darwin GOARCH=amd64 packr build && mv ./project_name ./releases/darwin-project_name \
  && GOOS=linux GOARCH=amd64 packr build && mv ./project_name ./releases/linux-project_name \
  && GOOS=windows GOARCH=386 packr build && mv ./project_name.exe ./releases/project_name.exe \
  && packr clean

Debugging

The packr command passes all arguments down to the underlying go command, this includes the -v flag to print out go build information. Packr looks for the -v flag, and will turn on its own verbose logging. This is very useful for trying to understand what the packr command is doing when it is run.

You can’t perform that action at this time.