1vfsgen
2======
3
4[](https://pkg.go.dev/github.com/shurcooL/vfsgen)
5
6Package vfsgen takes an http.FileSystem (likely at `go generate` time) and
7generates Go code that statically implements the provided http.FileSystem.
8
9Features:
10
11- Efficient generated code without unneccessary overhead.
12
13- Uses gzip compression internally (selectively, only for files that compress well).
14
15- Enables direct access to internal gzip compressed bytes via an optional interface.
16
17- Outputs `gofmt`ed Go code.
18
19Installation
20------------
21
22```sh
23go get github.com/shurcooL/vfsgen
24```
25
26Usage
27-----
28
29Package `vfsgen` is a Go code generator library. It has a `Generate` function that takes an input filesystem (as a [`http.FileSystem`](https://godoc.org/net/http#FileSystem) type), and generates a Go code file that statically implements the contents of the input filesystem.
30
31For example, we can use [`http.Dir`](https://godoc.org/net/http#Dir) as a `http.FileSystem` implementation that uses the contents of the `/path/to/assets` directory:
32
33```Go
34var fs http.FileSystem = http.Dir("/path/to/assets")
35```
36
37Now, when you execute the following code:
38
39```Go
40err := vfsgen.Generate(fs, vfsgen.Options{})
41if err != nil {
42 log.Fatalln(err)
43}
44```
45
46An assets_vfsdata.go file will be generated in the current directory:
47
48```Go
49// Code generated by vfsgen; DO NOT EDIT.
50
51package main
52
53import ...
54
55// assets statically implements the virtual filesystem provided to vfsgen.Generate.
56var assets http.FileSystem = ...
57```
58
59Then, in your program, you can use `assets` as any other [`http.FileSystem`](https://godoc.org/net/http#FileSystem), for example:
60
61```Go
62file, err := assets.Open("/some/file.txt")
63if err != nil {
64 return err
65}
66defer file.Close()
67```
68
69```Go
70http.Handle("/assets/", http.FileServer(assets))
71```
72
73`vfsgen` can be more useful when combined with build tags and go generate directives. This is described below.
74
75### `go generate` Usage
76
77vfsgen is great to use with go generate directives. The code invoking `vfsgen.Generate` can go in an assets_generate.go file, which can then be invoked via "//go:generate go run assets_generate.go". The input virtual filesystem can read directly from disk, or it can be more involved.
78
79By using build tags, you can create a development mode where assets are loaded directly from disk via `http.Dir`, but then statically implemented for final releases.
80
81For example, suppose your source filesystem is defined in a package with import path "example.com/project/data" as:
82
83```Go
84//go:build dev
85
86package data
87
88import "net/http"
89
90// Assets contains project assets.
91var Assets http.FileSystem = http.Dir("assets")
92```
93
94When built with the "dev" build tag, accessing `data.Assets` will read from disk directly via `http.Dir`.
95
96A generate helper file assets_generate.go can be invoked via "//go:generate go run -tags=dev assets_generate.go" directive:
97
98```Go
99//go:build ignore
100
101package main
102
103import (
104 "log"
105
106 "example.com/project/data"
107 "github.com/shurcooL/vfsgen"
108)
109
110func main() {
111 err := vfsgen.Generate(data.Assets, vfsgen.Options{
112 PackageName: "data",
113 BuildTags: "!dev",
114 VariableName: "Assets",
115 })
116 if err != nil {
117 log.Fatalln(err)
118 }
119}
120```
121
122Note that "dev" build tag is used to access the source filesystem, and the output file will contain "!dev" build tag. That way, the statically implemented version will be used during normal builds and `go get`, when custom builds tags are not specified.
123
124### `vfsgendev` Usage
125
126`vfsgendev` is a binary that can be used to replace the need for the assets_generate.go file.
127
128Make sure it's installed and available in your PATH.
129
130```bash
131go get -u github.com/shurcooL/vfsgen/cmd/vfsgendev
132```
133
134Then the "//go:generate go run -tags=dev assets_generate.go" directive can be replaced with:
135
136```
137//go:generate vfsgendev -source="example.com/project/data".Assets
138```
139
140vfsgendev accesses the source variable using "dev" build tag, and generates an output file with "!dev" build tag.
141
142### Additional Embedded Information
143
144All compressed files implement [`httpgzip.GzipByter` interface](https://godoc.org/github.com/shurcooL/httpgzip#GzipByter) for efficient direct access to the internal compressed bytes:
145
146```Go
147// GzipByter is implemented by compressed files for
148// efficient direct access to the internal compressed bytes.
149type GzipByter interface {
150 // GzipBytes returns gzip compressed contents of the file.
151 GzipBytes() []byte
152}
153```
154
155Files that have been determined to not be worth gzip compressing (their compressed size is larger than original) implement [`httpgzip.NotWorthGzipCompressing` interface](https://godoc.org/github.com/shurcooL/httpgzip#NotWorthGzipCompressing):
156
157```Go
158// NotWorthGzipCompressing is implemented by files that were determined
159// not to be worth gzip compressing (the file size did not decrease as a result).
160type NotWorthGzipCompressing interface {
161 // NotWorthGzipCompressing is a noop. It's implemented in order to indicate
162 // the file is not worth gzip compressing.
163 NotWorthGzipCompressing()
164}
165```
166
167Comparison
168----------
169
170vfsgen aims to be conceptually simple to use. The [`http.FileSystem`](https://godoc.org/net/http#FileSystem) abstraction is central to vfsgen. It's used as both input for code generation, and as output in the generated code.
171
172That enables great flexibility through orthogonality, since helpers and wrappers can operate on `http.FileSystem` without knowing about vfsgen. If you want, you can perform pre-processing, minifying assets, merging folders, filtering out files and otherwise modifying input via generic `http.FileSystem` middleware.
173
174It avoids unneccessary overhead by merging what was previously done with two distinct packages into a single package.
175
176It strives to be the best in its class in terms of code quality and efficiency of generated code. However, if your use goals are different, there are other similar packages that may fit your needs better.
177
178### Alternatives
179
180- [`embed`](https://go.dev/pkg/embed) - Package embed provides access to files embedded in the running Go program.
181- [`go-bindata`](https://github.com/jteeuwen/go-bindata) - Reads from disk, generates Go code that provides access to data via a [custom API](https://github.com/jteeuwen/go-bindata#accessing-an-asset).
182- [`go-bindata-assetfs`](https://github.com/elazarl/go-bindata-assetfs) - Takes output of go-bindata and provides a wrapper that implements `http.FileSystem` interface (the same as what vfsgen outputs directly).
183- [`becky`](https://github.com/tv42/becky) - Embeds assets as string literals in Go source.
184- [`statik`](https://github.com/rakyll/statik) - Embeds a directory of static files to be accessed via `http.FileSystem` interface (sounds very similar to vfsgen); implementation sourced from [camlistore](https://camlistore.org).
185- [`go.rice`](https://github.com/GeertJohan/go.rice) - Makes working with resources such as HTML, JS, CSS, images and templates very easy.
186- [`esc`](https://github.com/mjibson/esc) - Embeds files into Go programs and provides `http.FileSystem` interfaces to them.
187- [`staticfiles`](https://github.com/bouk/staticfiles) - Allows you to embed a directory of files into your Go binary.
188- [`togo`](https://github.com/flazz/togo) - Generates a Go source file with a `[]byte` var containing the given file's contents.
189- [`fileb0x`](https://github.com/UnnoTed/fileb0x) - Simple customizable tool to embed files in Go.
190- [`embedfiles`](https://github.com/leighmcculloch/embedfiles) - Simple tool for embedding files in Go code as a map.
191- [`packr`](https://github.com/gobuffalo/packr) - Simple solution for bundling static assets inside of Go binaries.
192- [`rsrc`](https://github.com/akavel/rsrc) - Tool for embedding .ico & manifest resources in Go programs for Windows.
193
194Attribution
195-----------
196
197This package was originally based on the excellent work by [@jteeuwen](https://github.com/jteeuwen) on [`go-bindata`](https://github.com/jteeuwen/go-bindata) and [@elazarl](https://github.com/elazarl) on [`go-bindata-assetfs`](https://github.com/elazarl/go-bindata-assetfs).
198
199Directories
200-----------
201
202| Path | Synopsis |
203|------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
204| [cmd/vfsgendev](https://pkg.go.dev/github.com/shurcooL/vfsgen/cmd/vfsgendev) | vfsgendev is a convenience tool for using vfsgen in a common development configuration. |
205
206License
207-------
208
209- [MIT License](LICENSE)
View as plain text