github.com/bayrepo/bayzr@v0.0.0-20240308125417-466ee1dfea8d/go-bindata/src/README.md (about) 1 ## bindata 2 3 This package converts any file into managable Go source code. Useful for 4 embedding binary data into a go program. The file data is optionally gzip 5 compressed before being converted to a raw byte slice. 6 7 It comes with a command line tool in the `go-bindata` sub directory. 8 This tool offers a set of command line options, used to customize the 9 output being generated. 10 11 12 ### Installation 13 14 To install the library and command line program, use the following: 15 16 go get -u github.com/jteeuwen/go-bindata/... 17 18 19 ### Usage 20 21 Conversion is done on one or more sets of files. They are all embedded in a new 22 Go source file, along with a table of contents and an `Asset` function, 23 which allows quick access to the asset, based on its name. 24 25 The simplest invocation generates a `bindata.go` file in the current 26 working directory. It includes all assets from the `data` directory. 27 28 $ go-bindata data/ 29 30 To include all input sub-directories recursively, use the elipsis postfix 31 as defined for Go import paths. Otherwise it will only consider assets in the 32 input directory itself. 33 34 $ go-bindata data/... 35 36 To specify the name of the output file being generated, we use the following: 37 38 $ go-bindata -o myfile.go data/ 39 40 Multiple input directories can be specified if necessary. 41 42 $ go-bindata dir1/... /path/to/dir2/... dir3 43 44 45 The following paragraphs detail some of the command line options which can be 46 supplied to `go-bindata`. Refer to the `testdata/out` directory for various 47 output examples from the assets in `testdata/in`. Each example uses different 48 command line options. 49 50 To ignore files, pass in regexes using -ignore, for example: 51 52 $ go-bindata -ignore=\\.gitignore data/... 53 54 ### Accessing an asset 55 56 To access asset data, we use the `Asset(string) ([]byte, error)` function which 57 is included in the generated output. 58 59 data, err := Asset("pub/style/foo.css") 60 if err != nil { 61 // Asset was not found. 62 } 63 64 // use asset data 65 66 67 ### Debug vs Release builds 68 69 When invoking the program with the `-debug` flag, the generated code does 70 not actually include the asset data. Instead, it generates function stubs 71 which load the data from the original file on disk. The asset API remains 72 identical between debug and release builds, so your code will not have to 73 change. 74 75 This is useful during development when you expect the assets to change often. 76 The host application using these assets uses the same API in both cases and 77 will not have to care where the actual data comes from. 78 79 An example is a Go webserver with some embedded, static web content like 80 HTML, JS and CSS files. While developing it, you do not want to rebuild the 81 whole server and restart it every time you make a change to a bit of 82 javascript. You just want to build and launch the server once. Then just press 83 refresh in the browser to see those changes. Embedding the assets with the 84 `debug` flag allows you to do just that. When you are finished developing and 85 ready for deployment, just re-invoke `go-bindata` without the `-debug` flag. 86 It will now embed the latest version of the assets. 87 88 89 ### Lower memory footprint 90 91 Using the `-nomemcopy` flag, will alter the way the output file is generated. 92 It will employ a hack that allows us to read the file data directly from 93 the compiled program's `.rodata` section. This ensures that when we call 94 call our generated function, we omit unnecessary memcopies. 95 96 The downside of this, is that it requires dependencies on the `reflect` and 97 `unsafe` packages. These may be restricted on platforms like AppEngine and 98 thus prevent you from using this mode. 99 100 Another disadvantage is that the byte slice we create, is strictly read-only. 101 For most use-cases this is not a problem, but if you ever try to alter the 102 returned byte slice, a runtime panic is thrown. Use this mode only on target 103 platforms where memory constraints are an issue. 104 105 The default behaviour is to use the old code generation method. This 106 prevents the two previously mentioned issues, but will employ at least one 107 extra memcopy and thus increase memory requirements. 108 109 For instance, consider the following two examples: 110 111 This would be the default mode, using an extra memcopy but gives a safe 112 implementation without dependencies on `reflect` and `unsafe`: 113 114 ```go 115 func myfile() []byte { 116 return []byte{0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a} 117 } 118 ``` 119 120 Here is the same functionality, but uses the `.rodata` hack. 121 The byte slice returned from this example can not be written to without 122 generating a runtime error. 123 124 ```go 125 var _myfile = "\x89\x50\x4e\x47\x0d\x0a\x1a" 126 127 func myfile() []byte { 128 var empty [0]byte 129 sx := (*reflect.StringHeader)(unsafe.Pointer(&_myfile)) 130 b := empty[:] 131 bx := (*reflect.SliceHeader)(unsafe.Pointer(&b)) 132 bx.Data = sx.Data 133 bx.Len = len(_myfile) 134 bx.Cap = bx.Len 135 return b 136 } 137 ``` 138 139 140 ### Optional compression 141 142 When the `-nocompress` flag is given, the supplied resource is *not* GZIP 143 compressed before being turned into Go code. The data should still be accessed 144 through a function call, so nothing changes in the usage of the generated file. 145 146 This feature is useful if you do not care for compression, or the supplied 147 resource is already compressed. Doing it again would not add any value and may 148 even increase the size of the data. 149 150 The default behaviour of the program is to use compression. 151 152 153 ### Path prefix stripping 154 155 The keys used in the `_bindata` map, are the same as the input file name 156 passed to `go-bindata`. This includes the path. In most cases, this is not 157 desireable, as it puts potentially sensitive information in your code base. 158 For this purpose, the tool supplies another command line flag `-prefix`. 159 This accepts a portion of a path name, which should be stripped off from 160 the map keys and function names. 161 162 For example, running without the `-prefix` flag, we get: 163 164 $ go-bindata /path/to/templates/ 165 166 _bindata["/path/to/templates/foo.html"] = path_to_templates_foo_html 167 168 Running with the `-prefix` flag, we get: 169 170 $ go-bindata -prefix "/path/to/" /path/to/templates/ 171 172 _bindata["templates/foo.html"] = templates_foo_html 173 174 175 ### Build tags 176 177 With the optional `-tags` flag, you can specify any go build tags that 178 must be fulfilled for the output file to be included in a build. This 179 is useful when including binary data in multiple formats, where the desired 180 format is specified at build time with the appropriate tags. 181 182 The tags are appended to a `// +build` line in the beginning of the output file 183 and must follow the build tags syntax specified by the go tool. 184 185 ### Related projects 186 187 [go-bindata-assetfs](https://github.com/elazarl/go-bindata-assetfs#readme) - 188 implements `http.FileSystem` interface. Allows you to serve assets with `net/http`. 189