Struct BuildOptions 

pub struct BuildOptions {

    pub dockerfile: Option<PathBuf>,
    pub zimagefile: Option<PathBuf>,
    pub runtime: Option<Runtime>,
    pub build_args: HashMap<String, String>,
    pub pipeline_vars: HashMap<String, String>,
    pub target: Option<String>,
    pub tags: Vec<String>,
    pub no_cache: bool,
    pub push: bool,
    pub registry_auth: Option<RegistryAuth>,
    pub squash: bool,
    pub format: Option<String>,
    pub layers: bool,
    pub cache_from: Option<String>,
    pub cache_to: Option<String>,
    pub cache_ttl: Option<Duration>,
    pub default_registry: Option<String>,
    pub default_cache_mounts: Vec<RunMount>,
    pub retries: u32,
    pub platform: Option<String>,
    pub target_os: Option<ImageOs>,
    pub platforms: Vec<String>,
    pub source_hash: Option<String>,
    pub pull: PullBaseMode,
    pub windows_ltsc: Option<String>,
    pub host_network: bool,
    pub backend_override: Option<BuilderBackendKind>,
}

Build options for customizing the image build process

Fields

dockerfile: Option<PathBuf>

Dockerfile path (default: Dockerfile in context)

zimagefile: Option<PathBuf>

ZImagefile path (alternative to Dockerfile)

runtime: Option<Runtime>

Use runtime template instead of Dockerfile

build_args: HashMap<String, String>

Build arguments (ARG values)

pipeline_vars: HashMap<String, String>

Pipeline variables (${VAR}) expanded into the ZImagefile body (base:, run:, …) before parsing. Used by the pipeline executor to parametrize a single ZImagefile set across e.g. Windows LTSC lines (--set LTSC=ltsc2025). Empty for direct (non-pipeline) builds. Only applied to ZImagefile bodies, never to Dockerfiles (whose ${ARG} syntax is parsed natively).

target: Option<String>

Target stage for multi-stage builds

tags: Vec<String>

Image tags to apply

no_cache: bool

Disable layer caching

push: bool

Push to registry after build

registry_auth: Option<RegistryAuth>

Registry auth (if pushing)

squash: bool

Squash all layers into one

format: Option<String>

Image format (oci or docker)

layers: bool

Enable buildah layer caching (–layers flag for buildah build). Default: true

Note: ZLayer uses manual container creation (buildah from, buildah run, buildah commit) rather than buildah build, so this flag is reserved for future use when/if we switch to buildah build (bud) command.

cache_from: Option<String>

Registry to pull cache from (–cache-from for buildah build).

Note: This would be used with buildah build --cache-from=<registry>. Currently ZLayer uses manual container creation, so this is reserved for future implementation or for switching to buildah build.

TODO: Implement remote cache support. This would require either:

1. Switching to buildah build command which supports –cache-from natively
2. Implementing custom layer caching with registry push/pull for intermediate layers

cache_to: Option<String>

Registry to push cache to (–cache-to for buildah build).

Note: This would be used with buildah build --cache-to=<registry>. Currently ZLayer uses manual container creation, so this is reserved for future implementation or for switching to buildah build.

TODO: Implement remote cache support. This would require either:

1. Switching to buildah build command which supports –cache-to natively
2. Implementing custom layer caching with registry push/pull for intermediate layers

cache_ttl: Option<Duration>

Maximum cache age (–cache-ttl for buildah build).

Note: This would be used with buildah build --cache-ttl=<duration>. Currently ZLayer uses manual container creation, so this is reserved for future implementation or for switching to buildah build.

TODO: Implement cache TTL support. This would require either:

1. Switching to buildah build command which supports –cache-ttl natively
2. Implementing custom cache expiration logic for our layer caching system

default_registry: Option<String>

Default OCI/WASM-compatible registry to check for images before falling back to Docker Hub qualification.

When set, the builder will probe this registry for short image names before qualifying them to docker.io. For example, if set to "git.example.com:5000" and the ZImagefile uses base: "myapp:latest", the builder will check git.example.com:5000/myapp:latest first.

default_cache_mounts: Vec<RunMount>

Default cache mounts injected into all RUN instructions. These are merged with any step-level cache mounts (deduped by target path).

retries: u32

Number of retries for failed RUN steps (0 = no retries, default)

platform: Option<String>

Target platform for the build (e.g., “linux/amd64”, “linux/arm64”). When set, buildah from pulls the platform-specific image variant.

target_os: Option<ImageOs>

Resolved target OS pin, mirrored from ImageBuilder::target_os right before the backend runs. None = darwin-native (the macOS Seatbelt sandbox provisions a Mac-native rootfs); Some(Linux)/Some(Windows) = an explicit cross-OS target. The macOS sandbox backend reads this to decide whether to provision a macOS-native toolchain for the base image — it must NOT do so for an explicit Linux target.

platforms: Vec<String>

Target platforms for a multi-arch build (e.g. ["linux/amd64", "linux/arm64"]). When more than one is set, build() builds each sequentially and assembles a manifest list. A single entry is treated like platform. Empty = single-arch build governed by platform.

source_hash: Option<String>

SHA-256 hash of the source Dockerfile/ZImagefile content.

When set, the sandbox builder can skip a rebuild if the cached image was produced from identical source content (content-based invalidation).

pull: PullBaseMode

How to handle base-image pulling during buildah from.

Default: PullBaseMode::Newer — only pull if the registry has a newer version. Set to PullBaseMode::Always for CI builds that must always refresh, or PullBaseMode::Never for offline builds.

windows_ltsc: Option<String>

Windows LTSC line to target for FROM image rewrites (e.g. "ltsc2022", "ltsc2025").

Only consumed by the Windows (HCS / WCOW) backend. When set, the builder rewrites generic Docker Hub references (ubuntu:24.04, golang:1.24, etc.) to the equivalent prebuilt Windows image via windows_image_resolver::rewrite_image_for_windows. None means the backend uses its built-in default (ltsc2022).

host_network: bool

Force --net=host on every buildah run for this build.

When true, the buildah backend asks [DockerfileTranslator] to emit --net=host on every translated RUN instruction, overriding any per-instruction network value. This mirrors Docker’s docker build --network=host flag and bypasses buildah’s CNI / netavark plumbing entirely — the container shares the host’s network namespace.

Default: false. Wired up from the top-level zlayer --host-network CLI flag (see bin/zlayer/src/cli.rs).

backend_override: Option<BuilderBackendKind>

Override the auto-detected build backend.

None means “use detect_backend()’s default for the host × target combination” (current behavior). Some(kind) forces that backend; if it’s unavailable for this host × target combination, the build fails with BuildError::NotSupported { operation: ... }.

Trait Implementations

impl Clone for BuildOptions

fn clone(&self) -> BuildOptions

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BuildOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for BuildOptions

fn default() -> Self

Returns the “default value” for a type.