Version: v0.3.0 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Oct 1, 2015 License: BSD-2-Clause, MIT Imports: 18 Imported by: 0



Wercker Godoc

go.rice is a Go package that makes working with resources such as html,js,css,images and templates very easy. During development go.rice will load required files directly from disk. Upon deployment it is easy to add all resource files to a executable using the rice tool, without changing the source code for your package. go.rice provides several methods to add resources to a binary.

What does it do?

The first thing go.rice does is finding the correct absolute path for your resource files. Say you are executing go binary in your home directory, but your html-files are located in $GOPATH/src/yourApplication/html-files. go.rice will lookup the correct path for that directory (relative to the location of yourApplication). The only thing you have to do is include the resources using rice.FindBox("html-files").

This only works when the source is available to the machine executing the binary. Which is always the case when the binary was installed with go get or go install. It might occur that you wish to simply provide a binary, without source. The rice tool analyses source code and finds call's to rice.FindBox(..) and adds the required directories to the executable binary. There are several methods to add these resources. You can 'embed' by generating go source code, or append the resource to the executable as zip file. In both cases go.rice will detect the embedded or appended resources and load those, instead of looking up files from disk.


Use go get for the package and go install for the tool.

go get github.com/GeertJohan/go.rice
go get github.com/GeertJohan/go.rice/rice

Package usage

Import the package: import "github.com/GeertJohan/go.rice"

Serving a static content folder over HTTP with a rice Box

http.Handle("/", http.FileServer(rice.MustFindBox("http-files").HTTPBox()))
http.ListenAndServe(":8080", nil)

Service a static content folder over HTTP at a non-root location

box := rice.MustFindBox("cssfiles")
cssFileServer := http.StripPrefix("/css/", http.FileServer(box.HTTPBox()))
http.Handle("/css/", cssFileServer)
http.ListenAndServe(":8080", nil)

Note the trailing slash in /css/ in both the call to http.StripPrefix and http.Handle.

Loading a template

// find a rice.Box
templateBox, err := rice.FindBox("example-templates")
if err != nil {
// get file contents as string
templateString, err := templateBox.String("message.tmpl")
if err != nil {
// parse and execute the template
tmplMessage, err := template.New("message").Parse(templateString)
if err != nil {
tmplMessage.Execute(os.Stdout, map[string]string{"Message": "Hello, world!"})

Never call FindBox() or MustFindBox() from an init() function, as the boxes might have not been loaded at that time.

Tool usage

The rice tool lets you add the resources to a binary executable so the files are not loaded from the filesystem anymore. This creates a 'standalone' executable. There are several ways to add the resources to a binary, each has pro's and con's but all will work without requiring changes to the way you load the resources.


Embed resources by generating Go source code

This method must be executed before building. It generates Go source files that are compiled by the go compiler into the binary.

The downside with this option is that the generated go source files can become very large, which will slow down compilation and require lots of memory to compile.

Execute the following commands:

rice embed-go
go build

A Note on Symbolic Links: embed-go uses the os.Walk function from the standard library. The os.Walk function does not follow symbolic links. So, when creating a box, be aware that any symbolic links inside your box's directory will not be followed. However, if the box itself is a symbolic link, its actual location will be resolved first and then walked. In summary, if your box location is a symbolic link, it will be followed but none of the symbolic links in the box will be followed.


Embed resources by generating a coff .syso file and some .go source code

** This method is experimental and should not be used for production systems just yet **

This method must be executed before building. It generates a COFF .syso file and Go source file that are compiled by the go compiler into the binary.

Execute the following commands:

rice embed-syso
go build

Append resources to executable as zip file

This method changes an allready built executable. It appends the resources as zip file to the binary. It makes compilation a lot faster and can be used with large resource files.

Downsides for appending are that it requires zip to be installed and does not provide a working Seek method.

Run the following commands to create a standalone executable.

go build -o example
rice append --exec example

Note: requires zip command to be installed

On windows, install zip from http://gnuwin32.sourceforge.net/packages/zip.htm or cygwin/msys toolsets.

Help information

Run rice -h for information about all options.

You can run the -h option for each sub-command, e.g. rice append -h.

Order of precedence

When opening a new box, the rice package tries to locate the resources in the following order:

  • embedded in generated go source
  • appended as zip
  • 'live' from filesystem


This project is licensed under a Simplified BSD license. Please read the LICENSE file.

TODO & Development

This package is not completed yet. Though it already provides working embedding, some important featuers are still missing.

  • implement Readdir() correctly on virtualDir
  • in-code TODO's
  • find boxes in imported packages

Less important stuff:

  • idea, os/arch dependent embeds. rice checks if embedding file has _os_arch or build flags. If box is not requested by file without buildflags, then the buildflags are applied to the embed file.

Package documentation

You will find package documentation at godoc.org/github.com/GeertJohan/go.rice.




View Source
const (
	LocateFS       = LocateMethod(iota) // Locate on the filesystem.
	LocateAppended                      // Locate boxes appended to the executable.
	LocateEmbedded                      // Locate embedded boxes.


View Source
var Debug = false

Debug can be set to true to enable debugging.

View Source
var ErrNotImplemented = errors.New("not implemented yet")

Error indicating some function is not implemented yet (but available to satisfy an interface)


This section is empty.


type Box

type Box struct {
	// contains filtered or unexported fields

Box abstracts a directory for resources/files. It can either load files from disk, or from embedded code (when `rice --embed` was ran).

func FindBox

func FindBox(name string) (*Box, error)

FindBox returns a Box instance for given name. When the given name is a relative path, it's base path will be the calling pkg/cmd's source root. When the given name is absolute, it's absolute. derp. Make sure the path doesn't contain any sensitive information as it might be placed into generated go source (embedded).

func MustFindBox

func MustFindBox(name string) *Box

MustFindBox returns a Box instance for given name, like FindBox does. It does not return an error, instead it panics when an error occurs.

func (*Box) Bytes

func (b *Box) Bytes(name string) ([]byte, error)

Bytes returns the content of the file with given name as []byte.

func (*Box) HTTPBox

func (b *Box) HTTPBox() *HTTPBox

HTTPBox creates a new HTTPBox from an existing Box

func (*Box) IsAppended

func (b *Box) IsAppended() bool

IsAppended indicates wether this box was appended to the application

func (*Box) IsEmbedded

func (b *Box) IsEmbedded() bool

IsEmbedded indicates wether this box was embedded into the application

func (*Box) MustBytes

func (b *Box) MustBytes(name string) []byte

MustBytes returns the content of the file with given name as []byte. panic's on error.

func (*Box) MustString

func (b *Box) MustString(name string) string

MustString returns the content of the file with given name as string. panic's on error.

func (*Box) Name

func (b *Box) Name() string

Name returns the name of the box

func (*Box) Open

func (b *Box) Open(name string) (*File, error)

Open opens a File from the box If there is an error, it will be of type *os.PathError.

func (*Box) String

func (b *Box) String(name string) (string, error)

String returns the content of the file with given name as string.

func (*Box) Time

func (b *Box) Time() time.Time

Time returns how actual the box is. When the box is embedded, it's value is saved in the embedding code. When the box is live, this methods returns time.Now()

func (*Box) Walk

func (b *Box) Walk(path string, walkFn filepath.WalkFunc) error

Walk is like filepath.Walk() Visit http://golang.org/pkg/path/filepath/#Walk for more information

type Config

type Config struct {
	// LocateOrder defines the priority order that boxes are searched for. By
	// default, the package global FindBox searches for embedded boxes first,
	// then appended boxes, and then finally boxes on the filesystem.  That
	// search order may be customized by provided the ordered list here. Leaving
	// out a particular method will omit that from the search space. For
	// example, []LocateMethod{LocateEmbedded, LocateAppended} will never search
	// the filesystem for boxes.
	LocateOrder []LocateMethod

Config allows customizing the box lookup behavior.

func (*Config) FindBox

func (c *Config) FindBox(boxName string) (*Box, error)

FindBox searches for boxes using the LocateOrder of the config.

type File

type File struct {
	// contains filtered or unexported fields

File implements the io.Reader, io.Seeker, io.Closer and http.File interfaces

func (*File) Close

func (f *File) Close() error

Close is like (*os.File).Close() Visit http://golang.org/pkg/os/#File.Close for more information

func (*File) Read

func (f *File) Read(bts []byte) (int, error)

Read is like (*os.File).Read() Visit http://golang.org/pkg/os/#File.Read for more information

func (*File) Readdir

func (f *File) Readdir(count int) ([]os.FileInfo, error)

Readdir is like (*os.File).Readdir() Visit http://golang.org/pkg/os/#File.Readdir for more information

func (*File) Seek

func (f *File) Seek(offset int64, whence int) (int64, error)

Seek is like (*os.File).Seek() Visit http://golang.org/pkg/os/#File.Seek for more information

func (*File) Stat

func (f *File) Stat() (os.FileInfo, error)

Stat is like (*os.File).Stat() Visit http://golang.org/pkg/os/#File.Stat for more information

type HTTPBox

type HTTPBox struct {

HTTPBox implements http.FileSystem which allows the use of Box with a http.FileServer.

e.g.: http.Handle("/", http.FileServer(rice.MustFindBox("http-files").HTTPBox()))

func (*HTTPBox) Open

func (hb *HTTPBox) Open(name string) (http.File, error)

Open returns a File using the http.File interface

type LocateMethod

type LocateMethod int

LocateMethod defines how a box is located.

type SortByModified

type SortByModified []os.FileInfo

SortByModified allows an array of os.FileInfo objects to be easily sorted by modified date using sort.Sort(SortByModified(array))

func (SortByModified) Len

func (f SortByModified) Len() int

func (SortByModified) Less

func (f SortByModified) Less(i, j int) bool

func (SortByModified) Swap

func (f SortByModified) Swap(i, j int)

type SortByName

type SortByName []os.FileInfo

SortByName allows an array of os.FileInfo objects to be easily sorted by filename using sort.Sort(SortByName(array))

func (SortByName) Len

func (f SortByName) Len() int

func (SortByName) Less

func (f SortByName) Less(i, j int) bool

func (SortByName) Swap

func (f SortByName) Swap(i, j int)


Path Synopsis
Package embedded defines embedded data types that are shared between the go.rice package and generated code.
Package embedded defines embedded data types that are shared between the go.rice package and generated code.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL