mirror of
https://github.com/strongdm/comply
synced 2024-11-25 09:04:54 +00:00
130 lines
4.9 KiB
Go
130 lines
4.9 KiB
Go
// This work is subject to the CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
|
|
// license. Its contents can be found at:
|
|
// http://creativecommons.org/publicdomain/zero/1.0/
|
|
|
|
/*
|
|
bindata converts any file into managable Go source code. Useful for
|
|
embedding binary data into a go program. The file data is optionally gzip
|
|
compressed before being converted to a raw byte slice.
|
|
|
|
The following paragraphs cover some of the customization options
|
|
which can be specified in the Config struct, which must be passed into
|
|
the Translate() call.
|
|
|
|
|
|
Debug vs Release builds
|
|
|
|
When used with the `Debug` option, the generated code does not actually include
|
|
the asset data. Instead, it generates function stubs which load the data from
|
|
the original file on disk. The asset API remains identical between debug and
|
|
release builds, so your code will not have to change.
|
|
|
|
This is useful during development when you expect the assets to change often.
|
|
The host application using these assets uses the same API in both cases and
|
|
will not have to care where the actual data comes from.
|
|
|
|
An example is a Go webserver with some embedded, static web content like
|
|
HTML, JS and CSS files. While developing it, you do not want to rebuild the
|
|
whole server and restart it every time you make a change to a bit of
|
|
javascript. You just want to build and launch the server once. Then just press
|
|
refresh in the browser to see those changes. Embedding the assets with the
|
|
`debug` flag allows you to do just that. When you are finished developing and
|
|
ready for deployment, just re-invoke `go-bindata` without the `-debug` flag.
|
|
It will now embed the latest version of the assets.
|
|
|
|
|
|
Lower memory footprint
|
|
|
|
The `NoMemCopy` option will alter the way the output file is generated.
|
|
It will employ a hack that allows us to read the file data directly from
|
|
the compiled program's `.rodata` section. This ensures that when we call
|
|
call our generated function, we omit unnecessary memcopies.
|
|
|
|
The downside of this, is that it requires dependencies on the `reflect` and
|
|
`unsafe` packages. These may be restricted on platforms like AppEngine and
|
|
thus prevent you from using this mode.
|
|
|
|
Another disadvantage is that the byte slice we create, is strictly read-only.
|
|
For most use-cases this is not a problem, but if you ever try to alter the
|
|
returned byte slice, a runtime panic is thrown. Use this mode only on target
|
|
platforms where memory constraints are an issue.
|
|
|
|
The default behaviour is to use the old code generation method. This
|
|
prevents the two previously mentioned issues, but will employ at least one
|
|
extra memcopy and thus increase memory requirements.
|
|
|
|
For instance, consider the following two examples:
|
|
|
|
This would be the default mode, using an extra memcopy but gives a safe
|
|
implementation without dependencies on `reflect` and `unsafe`:
|
|
|
|
func myfile() []byte {
|
|
return []byte{0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a}
|
|
}
|
|
|
|
Here is the same functionality, but uses the `.rodata` hack.
|
|
The byte slice returned from this example can not be written to without
|
|
generating a runtime error.
|
|
|
|
var _myfile = "\x89\x50\x4e\x47\x0d\x0a\x1a"
|
|
|
|
func myfile() []byte {
|
|
var empty [0]byte
|
|
sx := (*reflect.StringHeader)(unsafe.Pointer(&_myfile))
|
|
b := empty[:]
|
|
bx := (*reflect.SliceHeader)(unsafe.Pointer(&b))
|
|
bx.Data = sx.Data
|
|
bx.Len = len(_myfile)
|
|
bx.Cap = bx.Len
|
|
return b
|
|
}
|
|
|
|
|
|
Optional compression
|
|
|
|
The NoCompress option indicates that the supplied assets are *not* GZIP
|
|
compressed before being turned into Go code. The data should still be accessed
|
|
through a function call, so nothing changes in the API.
|
|
|
|
This feature is useful if you do not care for compression, or the supplied
|
|
resource is already compressed. Doing it again would not add any value and may
|
|
even increase the size of the data.
|
|
|
|
The default behaviour of the program is to use compression.
|
|
|
|
|
|
Path prefix stripping
|
|
|
|
The keys used in the `_bindata` map are the same as the input file name
|
|
passed to `go-bindata`. This includes the path. In most cases, this is not
|
|
desireable, as it puts potentially sensitive information in your code base.
|
|
For this purpose, the tool supplies another command line flag `-prefix`.
|
|
This accepts a portion of a path name, which should be stripped off from
|
|
the map keys and function names.
|
|
|
|
For example, running without the `-prefix` flag, we get:
|
|
|
|
$ go-bindata /path/to/templates/
|
|
|
|
_bindata["/path/to/templates/foo.html"] = path_to_templates_foo_html
|
|
|
|
Running with the `-prefix` flag, we get:
|
|
|
|
$ go-bindata -prefix "/path/to/" /path/to/templates/
|
|
|
|
_bindata["templates/foo.html"] = templates_foo_html
|
|
|
|
|
|
Build tags
|
|
|
|
With the optional Tags field, you can specify any go build tags that
|
|
must be fulfilled for the output file to be included in a build. This
|
|
is useful when including binary data in multiple formats, where the desired
|
|
format is specified at build time with the appropriate tags.
|
|
|
|
The tags are appended to a `// +build` line in the beginning of the output file
|
|
and must follow the build tags syntax specified by the go tool.
|
|
|
|
*/
|
|
package bindata
|