Embed Files in Go Package

Embed Files in Go Package.

Table of Contents

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