README
¶
Fork
This is a heavily modified fork of the go.rice tool by GeertJohan. We found the rice tool's use of go source parsing excessive for our needs so we developed a smaller and simpler version that would be easy to maintain and still use the useful features go.rice provided. This version simply creates a tool that will import the paths listed as 'boxes' and append them to the executable.
boxedRice
boxedRice is a Go package that makes working with resources such as html,js,css,images and templates very easy. During development boxedRice will load required files directly from disk. Upon deployment it is easy to add all resource files to a executable using the boxedRice tool, without changing the source code for your package. boxedRice provides several methods to add resources to a binary.
What does it do?
The first thing boxedRice 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. boxedRice 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 boxedRice.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 boxedRice tool provides the append command to append items to the binary as a zip. boxedRice will detect the appended resources and load those, instead of looking up files from disk.
Installation
Use go get to install the package the boxedRice tool.
go get github.com/bypasslane/boxedRice
go get github.com/bypasslane/boxedRice/boxedRice
Package usage
Import the package: import "github.com/bypasslane/boxedRice"
Serving a static content folder over HTTP with a boxedRice Box
http.Handle("/", http.FileServer(boxedRice.MustFindBox("http-files").HTTPBox()))
http.ListenAndServe(":8080", nil)
Service a static content folder over HTTP at a non-root location
box := boxedRice.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 boxedRice.Box
templateBox, err := boxedRice.FindBox("example-templates")
if err != nil {
log.Fatal(err)
}
// get file contents as string
templateString, err := templateBox.String("message.tmpl")
if err != nil {
log.Fatal(err)
}
// parse and execute the template
tmplMessage, err := template.New("message").Parse(templateString)
if err != nil {
log.Fatal(err)
}
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 boxedRice 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.
append
Append resources to executable as zip file
This method changes an already 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
boxedRice append -b example/example-files --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 boxedRice -h for information about all options.
You can run the -h option for each sub-command, e.g. boxedRice append -h.
Order of precedence
When opening a new box, the boxedRice package tries to locate the resources in the following order:
- appended as zip
- 'live' from filesystem
License
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 appending, there are some refinements to be made. These are noted in code as TODO comments.
Package documentation
You will find package documentation at godoc.org/github.com/bypasslane/boxedRice.
Documentation
¶
Index ¶
- Constants
- Variables
- type Box
- func (b *Box) Bytes(name string) ([]byte, error)
- func (b *Box) HTTPBox() *HTTPBox
- func (b *Box) IsAppended() bool
- func (b *Box) MustBytes(name string) []byte
- func (b *Box) MustString(name string) string
- func (b *Box) Name() string
- func (b *Box) Open(name string) (*File, error)
- func (b *Box) String(name string) (string, error)
- func (b *Box) Time() time.Time
- func (b *Box) Walk(path string, walkFn filepath.WalkFunc) error
- type Config
- type File
- type HTTPBox
- type LocateMethod
- type SortByModified
- type SortByName
Constants ¶
const ( LocateFS = LocateMethod(iota) // Locate on the filesystem according to package path. LocateAppended // Locate boxes appended to the executable. LocateWorkingDirectory // Locate on the binary working directory )
Variables ¶
var Debug = false
Debug can be set to true to enable debugging.
Functions ¶
This section is empty.
Types ¶
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 appended files
func FindBox ¶
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 ¶
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) IsAppended ¶
IsAppended indicates weather this box was appended to the application
func (*Box) MustBytes ¶
MustBytes returns the content of the file with given name as []byte. panic's on error.
func (*Box) MustString ¶
MustString returns the content of the file with given name as string. panic's on error.
func (*Box) Open ¶
Open opens a File from the box If there is an error, it will be of type *os.PathError.
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) MustFindBox ¶
MustFindBox searches for boxes using the LocateOrder of the config, like FindBox does. It does not return an error, instead it panics when an error occurs.
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 ¶
Close is like (*os.File).Close() Visit http://golang.org/pkg/os/#File.Close for more information
func (*File) Read ¶
Read is like (*os.File).Read() Visit http://golang.org/pkg/os/#File.Read for more information
func (*File) Readdir ¶
Readdir is like (*os.File).Readdir() Visit http://golang.org/pkg/os/#File.Readdir for more information
func (*File) Seek ¶
Seek is like (*os.File).Seek() Visit http://golang.org/pkg/os/#File.Seek for more information
type HTTPBox ¶
type HTTPBox struct {
*Box
}
HTTPBox implements http.FileSystem which allows the use of Box with a http.FileServer.
e.g.: http.Handle("/", http.FileServer(boxedRice.MustFindBox("http-files").HTTPBox()))
type SortByModified ¶
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 ¶
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)
Source Files
Directories