pack CLI

pack is a CLI tool designed to facilitate the use of Cloud Native Buildpacks. It serves three primary user groups:

• App Developers: Use buildpacks to convert source code into runnable container images.
• Buildpack Authors: Develop and package buildpacks for distribution.
• Operators: Package buildpacks for distribution and maintain applications.

pack is a CLI implementation of the Platform Interface Specification for Cloud Native Buildpacks.

The project provides several make commands to run different test suites. Test output is typically streamed to the terminal and also saved to files in the out/ directory.

• Unit and Integration tests: make unit (outputs to out/unit)
• Acceptance tests: make acceptance (outputs to out/acceptance)
• All tests: make test
• Full acceptance suite: make acceptance-all (includes cross-compatibility testing for n-1 pack and lifecycle versions)

Use the following commands to maintain the codebase and ensure compliance before submitting a Pull Request:

• Format code: make format
• Tidy dependencies and codebase: make tidy
• Verify formatting and quality: make verify
• Run pre-PR checks: make prepare-for-pr

Use make build to compile the pack binary. The resulting binary will be placed in the out/ directory.

You can customize the build using the following environment variables:

To develop on pack, ensure you have the following prerequisites installed:

macOS

• Git (built-in)
• Go (brew install go)
• Docker
• Make (xcode-select --install)

Windows

• Git (choco install git -y and git config --global core.autocrlf false)
• Go (choco install golang -y)
• Docker
• Make (choco install cygwin make -y and add C:\tools\cygwin\bin to your PATH)

Note for Windows users: Some tests require permission to create symlinks. Ensure your user account has the necessary permissions to create symlinks on Windows.

To test changes to the release workflows (build, delivery-docker, benchmark) on a fork, you must:

1. Add Secrets to your fork:
   • DOCKER_PASSWORD and DOCKER_USERNAME (if not using ghcr.io)
   • DEPLOY_KEY (SSH private key for release-merge workflow)
2. Configure Repository Settings:
   • Enable the Issues feature.
   • Create labels: status/triage and type/bug.
   • Create a branch named gh-pages for benchmark reports.
3. Update the fork: Use the provided script to update source code and disable workflows that shouldn't run on the fork: ./tools/test-fork.sh <registry repo name>

You can provide environment variables for the build process using either the --env flag or the --env-file flag.

• --env: Accepts VAR=VALUE or just VAR. If only VAR is provided, the value is taken from the current shell environment. This flag can be used multiple times and overrides values in --env-file.
• --env-file: Accepts a file containing one variable per line in the form VAR=VALUE or VAR.

Note: These variables are available during the build process but are NOT available at image runtime.

The --flatten flag allows you to flatten a buildpack package into a single layer.

Warning: Flattening a buildpack package could break the distribution specification. Use this with caution. This feature is currently considered experimental.

You can exclude specific buildpacks from the flattening process using the --flatten-exclude flag with the format <buildpack-id>@<buildpack-version>.

If you find a builder you like from the suggested list, you can set it as your default builder using the pack config default-builder command. This avoids having to specify the --builder flag in every subsequent command.

Usage: pack config default-builder <builder-image>

When packaging an extension, you can specify target platforms using the --target flag. This allows you to build for multiple architectures or specific distribution versions.

If no target is specified, Pack will use the platform defined in the extension's configuration. You can also define targets within the buildpack.toml file.

If you encounter an error indicating an experimental feature is being used, you can enable experimental features globally by updating your configuration. Run the following command:

pack config experimental true

This will add experimental = true to your default configuration file.

When packaging a buildpack, you can specify target platforms using the --target flag or by defining [[targets]] in your package.toml (for composite buildpacks) or buildpack.toml (for single buildpacks). This allows you to build for specific operating systems, architectures, variants, or distribution versions.

Target Format Examples:

• OS/Arch: linux/amd64
• OS/Arch/Variant: linux/arm/v6
• With Distribution: linux/arm/v6:ubuntu@14.04

CLI Usage:

# Build for multiple architectures
pack buildpack package my-buildpack --target "linux/amd64" --target "linux/arm64"

# Build for a specific distribution version
pack buildpack package my-buildpack --target "linux/arm/v6:ubuntu@14.04"