git.wit.org/jcarr/packr@v1.10.8/README.md (about)

     1  # packr
     2  
     3  [![GoDoc](https://godoc.org/github.com/gobuffalo/packr?status.svg)](https://godoc.org/github.com/gobuffalo/packr)
     4  
     5  Packr is a simple solution for bundling static assets inside of Go binaries. Most importantly it does it in a way that is friendly to developers while they are developing.
     6  
     7  ## Intro Video
     8  
     9  To get an idea of the what and why of packr, please enjoy this short video: [https://vimeo.com/219863271](https://vimeo.com/219863271).
    10  
    11  ## Installation
    12  
    13  ```text
    14  $ go get -u github.com/gobuffalo/packr/...
    15  ```
    16  
    17  ## Usage
    18  
    19  ### In Code
    20  
    21  The first step in using Packr is to create a new box. A box represents a folder on disk. Once you have a box you can get `string` or `[]byte` representations of the file.
    22  
    23  ```go
    24  // set up a new box by giving it a (relative) path to a folder on disk:
    25  box := packr.NewBox("./templates")
    26  
    27  // Get the string representation of a file:
    28  html := box.String("index.html")
    29  
    30  // Get the string representation of a file, or an error if it doesn't exist:
    31  html, err := box.MustString("index.html")
    32  
    33  // Get the []byte representation of a file:
    34  html := box.Bytes("index.html")
    35  
    36  // Get the []byte representation of a file, or an error if it doesn't exist:
    37  html, err := box.MustBytes("index.html")
    38  ```
    39  
    40  ### What is a Box?
    41  
    42  A box represents a folder, and any sub-folders, on disk that you want to have access to in your binary. When compiling a binary using the `packr` CLI the contents of the folder will be converted into Go files that can be compiled inside of a "standard" go binary. Inside of the compiled binary the files will be read from memory. When working locally the files will be read directly off of disk. This is a seamless switch that doesn't require any special attention on your part.
    43  
    44  #### Example
    45  
    46  Assume the follow directory structure:
    47  
    48  ```
    49  ├── main.go
    50  └── templates
    51      ├── admin
    52      │   └── index.html
    53      └── index.html
    54  ```
    55  
    56  The following program will read the `./templates/admin/index.html` file and print it out.
    57  
    58  ```go
    59  package main
    60  
    61  import (
    62  	"fmt"
    63  
    64  	"github.com/gobuffalo/packr"
    65  )
    66  
    67  func main() {
    68  	box := packr.NewBox("./templates")
    69  
    70  	s := box.String("admin/index.html")
    71  	fmt.Println(s)
    72  }
    73  ```
    74  
    75  ### Development Made Easy
    76  
    77  In order to get static files into a Go binary, those files must first be converted to Go code. To do that, Packr, ships with a few tools to help build binaries. See below.
    78  
    79  During development, however, it is painful to have to keep running a tool to compile those files.
    80  
    81  Packr uses the following resolution rules when looking for a file:
    82  
    83  1. Look for the file in-memory (inside a Go binary)
    84  1. Look for the file on disk (during development)
    85  
    86  Because Packr knows how to fall through to the file system, developers don't need to worry about constantly compiling their static files into a binary. They can work unimpeded.
    87  
    88  Packr takes file resolution a step further. When declaring a new box you use a relative path, `./templates`. When Packr recieves this call it calculates out the absolute path to that directory. By doing this it means you can be guaranteed that Packr can find your files correctly, even if you're not running in the directory that the box was created in. This helps with the problem of testing, where Go changes the `pwd` for each package, making relative paths difficult to work with. This is not a problem when using Packr.
    89  
    90  ---
    91  
    92  ## Usage with HTTP
    93  
    94  A box implements the [`http.FileSystem`](https://golang.org/pkg/net/http/#FileSystemhttps://golang.org/pkg/net/http/#FileSystem) interface, meaning it can be used to serve static files.
    95  
    96  ```go
    97  package main
    98  
    99  import (
   100  	"net/http"
   101  
   102  	"github.com/gobuffalo/packr"
   103  )
   104  
   105  func main() {
   106  	box := packr.NewBox("./templates")
   107  
   108  	http.Handle("/", http.FileServer(box))
   109  	http.ListenAndServe(":3000", nil)
   110  }
   111  ```
   112  
   113  ---
   114  
   115  ## Building a Binary (the easy way)
   116  
   117  When it comes time to build, or install, your Go binary, simply use `packr build` or `packr install` just as you would `go build` or `go install`. All flags for the `go` tool are supported and everything works the way you expect, the only difference is your static assets are now bundled in the generated binary. If you want more control over how this happens, looking at the following section on building binaries (the hard way).
   118  
   119  ### Building a Binary (the hard way)
   120  
   121  Before you build your Go binary, run the `packr` command first. It will look for all the boxes in your code and then generate `.go` files that pack the static files into bytes that can be bundled into the Go binary.
   122  
   123  ```
   124  $ packr
   125  --> packing foo/foo-packr.go
   126  --> packing example-packr.go
   127  ```
   128  
   129  Then run your `go build command` like normal.
   130  
   131  *NOTE*: It is not recommended to check-in these generated `-packr.go` files. They can be large, and can easily become out of date if not careful. It is recommended that you always run `packr clean` after running the `packr` tool.
   132  
   133  #### Cleaning Up
   134  
   135  When you're done it is recommended that you run the `packr clean` command. This will remove all of the generated files that Packr created for you.
   136  
   137  ```
   138  $ packr clean
   139  ----> cleaning up example-packr.go
   140  ----> cleaning up foo/foo-packr.go
   141  ```
   142  
   143  Why do you want to do this? Packr first looks to the information stored in these generated files, if the information isn't there it looks to disk. This makes it easy to work with in development.