bundledotgo

Documentation

Overview

Bundle creates a single-source-file version of a source package suitable for inclusion in a particular target package.

Usage:

bundle [-o file] [-dst path] [-pkg name] [-prefix p] [-import old=new] <src>

The src argument specifies the import path of the package to bundle. The bundling of a directory of source files into a single source file necessarily imposes a number of constraints. The package being bundled must not use cgo; must not use conditional file compilation, whether with build tags or system-specific file names like code_amd64.go; must not depend on any special comments, which may not be preserved; must not use any assembly sources; must not use renaming imports; and must not use reflection-based APIs that depend on the specific names of types or struct fields.

By default, bundle writes the bundled code to standard output. If the -o argument is given, bundle writes to the named file and also includes a “//go:generate” comment giving the exact command line used, for regenerating the file with “go generate.”

Bundle customizes its output for inclusion in a particular package, the destination package. By default bundle assumes the destination is the package in the current directory, but the destination package can be specified explicitly using the -dst option, which takes an import path as its argument. If the source package imports the destination package, bundle will remove those imports and rewrite any references to use direct references to the corresponding symbols. Bundle also must write a package declaration in the output and must choose a name to use in that declaration. If the -package option is given, bundle uses that name. Otherwise, if the -dst option is given, bundle uses the last element of the destination import path. Otherwise, by default bundle uses the package name found in the package sources in the current directory.

To avoid collisions, bundle inserts a prefix at the beginning of every package-level const, func, type, and var identifier in src's code, updating references accordingly. The default prefix is the package name of the source package followed by an underscore. The -prefix option specifies an alternate prefix.

Occasionally it is necessary to rewrite imports during the bundling process. The -import option, which may be repeated, specifies that an import of "old" should be rewritten to import "new" instead.

Example

Bundle archive/zip for inclusion in cmd/dist:

cd $GOROOT/src/cmd/dist
bundle -o zip.go archive/zip

Bundle golang.org/x/net/http2 for inclusion in net/http, prefixing all identifiers by "http2" instead of "http2_", and rewriting the import "golang.org/x/net/http2/hpack" to "internal/golang.org/x/net/http2/hpack":

cd $GOROOT/src/net/http
bundle -o h2_bundle.go \
	-prefix http2 \
	-import golang.org/x/net/http2/hpack=internal/golang.org/x/net/http2/hpack \
	golang.org/x/net/http2

Two ways to update the http2 bundle:

go generate net/http

cd $GOROOT/src/net/http
go generate

Update both bundles, restricting “go generate” to running bundle commands:

go generate -run bundle cmd/dist net/http

Notes

Bugs

• bundle may generate incorrect code due to shadowing between identifiers and imported package names.

  The generated code will either fail to compile or (unlikely) compile successfully but have different behavior than the original package. The risk of this happening is higher when the original package has renamed imports (they're typically renamed in order to resolve a shadow inside that particular .go file).