Becky embeds assets as string literals in Go source.
OBSOLETE Becky has been made unnecessary by the embed
package in Go 1.16. It will not be developed further.
Use becky via tools.go
, see
https://github.com/golang/go/wiki/Modules#how-can-i-track-tool-dependencies-for-a-module
For example, in your project create tools.go
that has:
// +build tools
package tools
import (
_ "github.com/tv42/becky"
)
And then near where you use the asset, put
//go:generate go run github.com/tv42/becky index.html
and run
$ go generate
This will create new files, named *.gen.go
. You should add those
into your version control system, to ensure go get
works for others.
You can pass multiple asset files at once, or repeat the go:generate
line.
The generated files declare variables that now contain your assets.
Given the above index.html
, the variable will be named index
.
You can override the name with -var=NAME
, or skip it with -var=_
and use side effects in your wrapper function (discussed later).
The asset will be an value of type asset
(this code is
autogenerated, you don't need to type it in):
type asset struct {
Name string
Content string
...
}
Name has the original filename, as a hint for Content-Type
selection.
For most uses, an asset
value needs to be given application or file
type specific functionality. To make this easy, the asset value will
be passed to a function caller wrapper. You need to write these
wrapper functions.
The name of the default wrapper is the (final) extension of the asset
filename. For index.html
, that's html
. You can override the
wrapper with -wrap=NAME
.
In your application, you'd do something like
func html(a asset) http.Handler {
return a
}
or
func txt(a asset) string {
return a.Content
}
or
func tmpl(a asset) *template.Template {
return template.Must(template.New(a.Name).Parse(a.Content))
}
to smartly handle *.html
, *.txt
and *.tmpl
assets. Feel free
to pass the fields of asset
to a factory function or type that
matches what you need, or use the asset
, whatever suits your
project.
Type asset
implements http.Handler
, including ETag
cache
validation. It uses http.ServeContent
which will set Content-Type
from the file name or content, and handle Range
requests.
If repeated calls to go run github.com/tv42/becky
are too slow, you
can build it once and run from there:
//go:generate go build github.com/tv42/becky
//go:generate ./becky index.html
gc
, the Go compiler, can slow down with large source files. As e.g.
image assets can get big, this can start to slow down your builds. The
mechanism used for embedding has been chosen to be the most efficient
available.
Embedding a 10MB asset (creating a 28MB Go source file) takes <1 second to generate the code and about 1 second for every compilation.
You can minimize the number of times assets need to be compiled by putting them in a different package that updates less often than most of your source.
If you build your application with -tags dev
, asset.ServeHTTP
will
reload the asset from disk on every request, and not use the embedded
copy. This makes editing HTML, CSS and such more convenient.