Parcello
Golang Resource Bundler
Overview
Parcello is a simple resource manager for Golang that allows embedding assets
like SQL, bash scripts and images. That allows easy release management by
deploying just a single binary rather than many files.
Roadmap
Note that we may introduce breaking changes until we reach v1.0.
- Rename the tool in order not to clash with parcel-bundler
- Support http.FileSystem
- Bundle resource as ZIP archive in the end of built Golang binary
-
Support embedded COFF resources(postponed until we accomplish a spike that works on all platforms)
Installation
GitHub
$ go get -u github.com/phogolabs/parcello
$ go install github.com/phogolabs/parcello/cmd/parcello
Homebrew (for Mac OS X)
$ brew tap phogolabs/tap
$ brew install parcello
Usage
You can use the parcello command line interface to bundle the desired resources
recursively:
$ parcello -r -d <resource_dir_source> -b <bundle_dir_destination>
However, the best way to use the tool is via go generate. In order to embed all
resource in particular directory, you should make it a package that has the
following comment:
// Package database contains the database artefacts of GOM as embedded resource
package database
//go:generate parcello -r
When you run:
$ go generate ./...
The tools will create a resource.go file that contains
all embedded resource in that directory and its
subdirectories as zip archive which is registered in
parcello.ResourceManager.
You can read the content in the following way:
// Import the package that includes 'resource.go'
import _ "database"
file, err := parcello.Open("your_sub_directory_name/your_file_name")
The parcello package provides an abstraction of
FileSystem
interface:
// FileSystem provides primitives to work with the underlying file system
type FileSystem interface {
// A FileSystem implements access to a collection of named files.
http.FileSystem
// Walk walks the file tree rooted at root, calling walkFn for each file or
// directory in the tree, including root.
Walk(dir string, fn filepath.WalkFunc) error
// OpenFile is the generalized open call; most users will use Open
OpenFile(name string, flag int, perm os.FileMode) (File, error)
}
That is implemented by the following:
- parcello.ResourceManager which provides an access to the bundled resources.
- parcello.Dir which provides an access to the underlying file system.
That allows easy replacement of the file system with the bundled resources and
vice versa.
If you want to work in dev mode, you should set the following environment
variables before you start your application:
$ export PARCELLO_DEV_ENABLED=1
$ # if the application resource directory is different than the current working directory
$ export PARCELLO_RESOURCE_DIR=./public
Note that downsides of this resource embedding approach are that your compile
time may increase significantly.
If you have such a issue, you can bundle the resource at the end of your binary
as zip archive. You can do this via parcello CLI:
$ go build your_binary
$ parcello -r -d <resource_dir_source> -b <path_to_your_binary> -t bundle
Command Line Interface
$ parcello -h
NAME:
parcello - Golang Resource Bundler and Embedder
USAGE:
parcello [global options]
VERSION:
0.8
COMMANDS:
help, h Shows a list of commands or help for one command
GLOBAL OPTIONS:
--bundle-path value, -b value path to the bundle directory or binary (default: ".")
--ignore value, -i value ignore file name
--include-docs include API documentation in generated source code
--quiet, -q disable logging
--recursive, -r embed or bundle the resources recursively
--resource-dir value, -d value path to directory (default: ".")
--resource-type value, -t value resource type. (supported: bundle, source-code) (default: "source-code")
--help, -h show help
--version, -v print the version
Example
You can check working example.
Contributing
We are open for any contributions. Just fork the
project.