bundle

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] [-tags build_constraints] <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 -pkg option is given, bundle uses that name. Otherwise, the name of the destination package is used. Build constraints for the generated file can be specified using the -tags option.

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 including a "!nethttpomithttp2" build constraint:

cd $GOROOT/src/net/http
bundle -o h2_bundle.go -prefix http2 -tags '!nethttpomithttp2' golang.org/x/net/http2

Update the http2 bundle in net/http:

go generate net/http

Update all bundles in the standard library:

go generate -run bundle std

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).