This reference documentation offers an in-depth description of the behavior and configuration options of the Paketo Go Buildpack. For explanations of how to use the buildpack for several common use-cases, see the Paketo Go Buildpack How To documentation.
The Go Paketo Buildpack supports several versions of Go. For more details on the specific versions supported in a given buildpack version, see the release notes.
The Paketo Go Buildpack is a composite buildpack designed to build applications written in Go.
With the Go CNB, there are three options for package management depending on your application:
Support for each of these package managers is mutually-exclusive. You can find specific information for each option below.
The buildpack will vendor dependencies using go modules if the app source
code contains a
go.mod file. During the build phase, the
buildpack checks to see
if the application requires any external modules and if it does, runs the
go mod vendor command for your app. The resulting
vendor directory will exist
in the app’s root directory and will contain all packages required for the build.
Dep is an alternative option to Go Modules for package management in Go apps. The buildpack will vendor dependencies using
dep if the app source code
Gopkg.toml file. (For more information about this file, see the
documentation. There may be an optional
Gopkg.lock file that outlines specific versions of the dependencies to be packaged. During its build
buildpack runs the
dep ensure command. The resulting
vendor directory will exist in
the app’s root directory and will contain all the packages required for the build.
The buildpack also supports both self-vendored apps and simpler apps that do not
require third-party packages. In this case there is no vendoring step, and the
go build command is run on the app source code as it is provided.
The buildpack runs
go build to compile Go source code into executables. By
default, it sets the flag
-buildmode=pie. If there is a
go.mod present in
the app’s root directory, it also builds with
mod=vendor. See the Go tool’s documentation for details about build configuration.
The Go CNB sets a few environment variables during the
phases of the app lifecycle. The sections below describe each environment
variable and its impact on your app.
GOPATH environment variable tells Go where to look for artifacts such as
source code and binaries. The Go CNB takes care of setting the
you, depending on your app and which package management option your app uses.
When using Go modules, the Go CNB sets the
GOPATH to a cached module layer in
the image so that between builds of the app, the dependencies don’t have to be
redownloaded. Essentially, the
GOPATH is being used to tell the
go mod vendor command where to look for dependencies. It’s worth noting that in this
GOPATH isn’t persisted beyond vendoring the dependencies and gets
overwritten by a subsequent buildpack.
When using the Dep tool, the Go CNB sets the
GOPATH to a temporary directory.
The app source code gets copied into the
GOPATH location so that the
dep ensure command knows where to look for the source code, as well as where to
vendor directory. The
vendor directory that is created is then
copied to the original source code directory. The
GOPATH in this case is used
dep ensure, but does not persist beyond that step.
go-build buildpack participates in the Go CNB in every case, regardless
of which package management option is used. The
GOPATH is set to a temporary
directory which includes the app source code and local sub-packages. The
GOPATH is utilized in running
go build to compile your app.
GOCACHE variable specifies where build outputs are stored for reuse in
subsequent builds. It gets set to a cached layer in the image by the
go-build buildpack, so that it is persisted between builds.
DEPCACHEDIR specifies where upstream dependency source code is stored for use
by the Dep tool. The
dep-ensure buildpack sets this variable to the path of a
cache layer in the app image.
|Paketo CA Certificates Buildpack||Optional||Installs custom CA certificates|
|Paketo Go Dist Buildpack||Required||Installs the Golang toolchain|
|Paketo Go Mod Vendor Buildpack||Optional||Installs app Go modules|
|Paketo Dep Buildpack||Optional||Installs
|Paketo Dep Ensure Buildpack||Optional||Uses
|Paketo Go Build Buildpack||Required||Compiles source code|
|Paketo Procfile Buildpack||Optional||Sets a user-specified start command|
|Paketo Environment Variables Buildpack||Optional||Sets user-specified launch-time environment variables|
|Paketo Image Labels Buildpack||Optional||Adds user-specified labels to app image metadata|
Last modified: January 20, 2022