README.rst

Embed Files in Go Package

Embed Files in Go Package.

Table of Contents

• Features
• How It Works
• Install
• Usage
• UNLICENSE
• References

Features

• Embedded files are read-only.
• Can be used in front-end code via GopherJS, or local Go program.
• Can be included in your Go package, or put in a separate package.
• With limit of max single file size. (only for plain-text files)
• Support embedding symbolic links (only GenerateGoPackage method)

How It Works

The files to be embedded in Go code will be encoded in base64 format. The (name, content) of the files will be put in the (key, value) pairs of Go built-in map structure, and ReadFile method, which has the same usage as ioutil.ReadFile, is implemented for read-only access. Because base64 encoding is used, the size of the files will increase 33%.

Install

$ go get -u github.com/siongui/goef

Usage

Assume we have following directory structure:

testdir/
├── hello.txt
└── subdir/
    └── hello2.txt

We want to embed the files in testdir/ to our code, i.e., embed hello.txt and subdir/hello2.txt in our code, and the name of our package is mypkg. You can embed the files as follows:

package main

import (
      "github.com/siongui/goef"
)

func main() {
      err := goef.GenerateGoPackage("mypkg", "testdir/", "data.go")
      if err != nil {
              panic(err)
      }
}

The above code will generate data.go in current directory, which contains the files directly in the code. You can read embedded files with the following method:

func ReadFile(filename string) ([]byte, error)

which has the same usage as ioutil.ReadFile in Go standard library. You can read hello.txt as follows:

b, err := ReadFile("hello.txt")
if err != nil {
      // handle error here
}

And read subdir/hello2.txt as follows:

b, err := ReadFile("subdir/hello2.txt")
if err != nil {
      // handle error here
}

Note that for files in sub-directory, you also have to include the path of sub-dir in the filename.

GenerateGoPackage method supports embedding symbolic links. When the symlink are read, the content of the file where the symlink points to will be returned.

If the file does not exit, os.ErrNotExist error will be returned.

You can also put the generated data.go in a separate package, import and read embedded files in the same way.

If your files are plain texts, you can use GenerateGoPackagePlainText instead of GenerateGoPackage. It is the same except that the file content is stored in plain text instead of base64 format and no symlinks embedding, and the size will not increase 33% because of base64 encoding.

GenerateGoPackagePlainTextWithMaxFileSize is the same as GenerateGoPackagePlainText except the output file size cannot be over the given max limit. This is useful for deploy your code on cloud services such as Google App Engine because they usually limit the max size of a single file.

For more details, see test files buildpkg_test.go and import_test.go.

UNLICENSE

Released in public domain. See UNLICENSE.

References

[1]

GitHub - UnnoTed/fileb0x: simple customizable tool to embed files in go GitHub - jteeuwen/go-bindata: A small utility which generates Go code from any file. Useful for embedding binary data in a Go program. GitHub - elazarl/go-bindata-assetfs: Serves embedded files from `jteeuwen/go-bindata` with `net/http` GitHub - GeertJohan/go.rice: go.rice is a Go package that makes working with resources such as html,js,css,images,templates, etc very easy. GitHub - shurcooL/vfsgen: Takes an input http.FileSystem (likely at go generate time) and generates Go code that statically implements it. GitHub - tv42/becky: Go asset embedding for use with `go generate` GitHub - rakyll/statik: Embed static files into a Go executable GitHub - mjibson/esc: A simple file embedder for Go GitHub - bouk/staticfiles: staticfiles compiles a directory of files into an embeddable .go file GitHub - flazz/togo: convert any file to Go source GitHub - inconshreveable/go-update: Build self-updating Golang programs GitHub - aprice/embed: Static content embedding for Golang GitHub - gobuffalo/packr: The simple and easy way to embed static files into Go binaries.

[2]	Is including assets (with a tool like go-bindata) an anti-pattern? : golang How to build Go plugin with data inside : golang golang - compile static files in app? : golang embed: Yet Another Static Content Embedder for Go : golang Embed libraries into exe : golang

[3]	Embed Data in Front-end Go Code

[4]	[Q&A] //go:embed draft design : golang [Q&A] io/fs draft design : golang