implant is a simple utility which allows data to be embedded directly
in golang applications (implant is a synonym of embed).
The expected use-case is that you have a HTTP-server, or similar golang
application which you wish to distribute as a single binary but which
needs some template files, HTML files, or other media.
Rather than distributing your binary along with a collection of files you instead embed the file contents in your application, and extract/use them at run-time.
implant allows you to do this, by generating a file static.go which
contains the contents of a particular directory hierarchy. At run-time you
can list available files, and extract the contents of specific ones.
go v1.16 makes this tool obsolete, via the addition of the go embed syntax
for embedding resources inside generated binaries.
Further details can be found in the release-notes:
As a result of this update this repository has been marked read-only on 20/02/2021 and no further development work will be carried out.
There are two ways to install this project from source, which depend on the version of the go version you're using.
If you're using go before 1.11 then the following command should fetch/update the project and install it upon your system:
$ go get -u github.com/skx/implant
If you're using a more recent version of go (which is highly recommended), you need to clone to a directory which is not present upon your GOPATH:
git clone https://github.com/skx/implant
cd implant
go install
If you prefer you can fetch a binary release from our releases page.
Assuming that all the files you wish to embed are located within a single directory you would run:
$ implant -input data/ [-output static.go]
This would generate the file static.go which contains the contents
of each file located beneath the data/ directory.
Further options are available to change the package-name, increase
verbosity and disable the automatic formatting of the code via gofmt.
Please consult the output of implant -help for details.
The generated file contains two functions to help you access your embedded data:
getResource( path string ) ([]byte, error)- Return the content of a single embedded file.
getResources() []EmbeddedResource- Returns a list of all the embedded resources in the your binary.
- The returned structure contains the original name of the file, the size, and the contents in encoded form.
- It is assumed you'll use
getResourceto get the original data, rather than trying to decode & decompress manually.
Sample usage of retrieving the content of the file data/index.html would look like:
contents, err := getResource( "data/index.html" )
To save space the embedded file contents are compressed with gzip, however
this results in binary-data so the compressed bytes are encoded via
encoding/hex. The use of the hex-representation does mean that some of
the compression is effectively wasted, but it is a reasonable trade-off.
The application uses itself to embed the template file which is written
to static.go. In addition to that several of my small applications use
this library, for example:
- https://github.com/skx/dns-api-go
- https://github.com/skx/puppet-summary
- https://github.com/skx/purppura
You'll see in each case I've committed the generated static.go file to the repository, which means users who don't need to change any of the resources aren't forced to install the tool.
I suggest a similar approach in your own deployments.
The repository contains a number of test-cases, they can can be executed via:
$ go test ./...
ok github.com/skx/implant (cached)
ok github.com/skx/implant/finder (cached)
To receive coverage details:
$ go test -coverprofile=tmp.t ./... && go tool cover -html=tmp.t && rm ./tmp.t
This repository is configured to run tests upon every commit, and when pull-requests are created/updated. The testing is carried out via .github/run-tests.sh which is used by the github-action-tester action.
Releases are automated in a similar fashion via .github/build, and the github-action-publish-binaries action.