Last updated: 2026-02-28

genpack CLI Reference

Overview

genpack is the main command of the genpack toolchain. It reads genpack.json5 (or genpack.json) in the current directory and executes processing according to the subcommand.

genpack [global options] <subcommand>

Global Options

Options common to all subcommands.

--overlay-override

Overrides the genpack-overlay repository (normally auto-fetched from GitHub) with a local directory. Used when developing genpack-overlay itself.

--independent-binpkgs

By default, a shared binary package cache at ~/.cache/genpack/{arch}/binpkgs/ is used, but specifying this option uses an independent cache per artifact. Use this to avoid interference between artifacts with significantly different USE flags.

Subcommands

build

Executes the full build pipeline (lower → upper → pack).

genpack build

This is the default behavior when the subcommand is omitted. Executes the following 3 phases in order:

1. Lower layer build: Compile packages with stage3 + Portage
2. Upper layer build: Extract and customize runtime files
3. Pack: SquashFS compression

On first run, automatically generates .gitignore and .vscode/settings.json if they don't exist.

lower

Builds the lower layer (build environment).

genpack lower

Processing flow:

1. Create work/{arch}/ directory
2. Download Gentoo stage3 tarball (with caching)
3. Download Portage snapshot (with caching)
4. Create ext4 filesystem image (lower.img)
5. Extract stage3 and Portage
6. Sync genpack-overlay
7. Configure Portage profile
8. Apply settings from genpack.json5 (USE flags, keywords, licenses, masks)
9. Resolve circular dependencies (if circulardep_breaker exists)
10. Emerge all packages
11. Rebuild kernel modules
12. Cleanup with depclean and eclean
13. Generate file list for upper layer (lower.files)

Whether rebuilding the lower layer is needed is determined by timestamps of genpack.json5 and Portage-related subdirectories (savedconfig/, patches/, kernel/, env/, overlay/).

upper

Builds the upper layer (runtime environment).

genpack upper

Prerequisite: lower execution must be completed.

Processing flow:

1. Create ext4 image for upper layer (upper.img)
2. Copy files listed in lower.files from lower layer
3. Execute package scripts
4. Create groups and users
5. Copy contents of files/ directory to root
6. Execute build scripts in files/build.d/
7. Execute setup_commands
8. Enable systemd services

pack

Generate SquashFS image from upper layer.

genpack pack

Prerequisite: Both lower and upper execution must be completed.

Processing:

1. Compress upper layer to SquashFS
2. Exclude build.d/, log files, and temporary files
3. Generate EFI superfloppy image if EFI files exist

Output files:

Compression methods details:

bash

Opens an interactive debug shell or runs a specified command in the lower layer.

genpack bash [command...]

When no command is given, launches a bash shell inside a systemd-nspawn container, allowing direct manipulation and inspection of lower layer filesystem. Used for verifying package installation status and debugging.

When a command is given, it is executed non-interactively inside the lower layer's nspawn container. The process exits with an error if the command fails.

upper-bash

Opens interactive debug shell overlaid on upper layer.

genpack upper-bash

Prerequisite: upper execution must be completed.

Used to inspect and debug the contents of the final image.

archive

Creates a distribution archive of artifact definition.

genpack archive

Generates genpack-{name}.tar.gz containing genpack.json5 and all subdirectories (files/, savedconfig/, patches/, kernel/, env/, overlay/).

Work Directory Structure

genpack places build artifacts and cache under the work/ directory.

Cache

Download Cache

stage3 and Portage snapshots are cached under work/. Validated by HTTP headers (Last-Modified, ETag, Content-Length), and not re-downloaded if unchanged.

Binary Package Cache

By default, binary packages are stored in ~/.cache/genpack/{arch}/binpkgs/ as a shared cache. Compiled packages can be reused across different artifacts of the same architecture.

When --independent-binpkgs is specified, an independent cache per artifact is used instead of this shared cache.

genpack-overlay Cache

The genpack-overlay git repository is cached in ~/.cache/genpack/overlay/.

Environment Variables

genpack itself does not reference any environment variables, but the following environment variables are set within the container during the build process:

Default Values

Typical Usage

# Full build
genpack build

# Full build (xz compression)
genpack --compression xz build

# Build with variant specified
genpack --variant cuda build

# Step-by-step build
genpack lower
genpack upper
genpack pack

# Debug (lower layer shell)
genpack bash

# Run a command in the lower layer
genpack bash emerge --info

# Debug (upper layer shell)
genpack upper-bash

# Debug (verbose logs)
genpack --debug build

# Build with local genpack-overlay version
genpack --overlay-override ~/projects/genpack-overlay build

# Create archive
genpack archive