Skip to main content

Module windows_builder

zlayer_builder

Module windows_builder 

Source
Expand description

Native WCOW (Windows Container On Windows) image builder.

Parses a Dockerfile/ZImagefile, pulls the Windows base image via the registry client, materialises the foreign-layer base via the Windows unpacker, and prepares a layer chain that subsequent Phase 4 tasks extend:

  • 4.A: Dockerfile parse + base image pull + foreign-layer materialisation. Non-FROM instructions are routed through WindowsBuilder::execute_instruction.

  • 4.B (this task): RUN execution via a transient HCS compute system attached to the working layer chain, with a Chocolatey translation hook for Linux package-manager invocations.

  • 4.C (this task): COPY / ADD writes into the working layer chain as a new RO layer per instruction (the per-instruction commit model), and config-only instructions (WORKDIR / ENV / ENTRYPOINT / CMD / USER / EXPOSE / VOLUME / LABEL / SHELL / STOPSIGNAL / HEALTHCHECK / ONBUILD) accumulate into a typed OciImageConfig carried on the BuildSkeleton for task 4.D to serialise.

    Layer-commit model: COPY and ADD each produce ONE new RO layer on Windows. The alternative “combined scratch” model (let COPY/ADD write into the same scratch the next RUN sees) is simpler at build time but produces irregular layer chains where a single RO layer conflates user-visible operations; per-instruction commits keep the layer chain 1:1 with Dockerfile instructions, which makes the emitted OCI manifest (4.D) cleanly auditable and downstream tooling like docker history / zlayer inspect produce sensible output. Off-Windows the model is moot — COPY/ADD still validate sources and mutate the working tree under working_layer_chain_dir/<scratch>/ so unit tests on Linux CI exercise the path-traversal and tar-extract logic without touching HCS.

  • 4.D: OCI image manifest emission with os: "windows" + os.version from the resolved base manifest; preserves foreign-layer urls[].

  • 4.E: Push via the existing zlayer-registry push path.

§Architectural template

Modelled after [crate::sandbox_builder::SandboxImageBuilder] — the macOS Seatbelt builder — which is the project’s reference for a native (non- buildah) Dockerfile-driven image builder. The key shared pattern: reuse the existing Dockerfile parser (crate::dockerfile::Dockerfile), delegate base-image materialisation to a platform-specific helper, and iterate over Instruction variants to drive the layer chain.

§Relationship to [crate::backend::hcs::HcsBackend]

HcsBackend is the existing Windows-only build backend wired into the BuildBackend trait. WindowsBuilder is intentionally a parallel, more granular API that exposes the build pipeline in skeleton form so Phase 4 follow-up tasks (4.C–4.E) can extend it incrementally without disturbing the working HcsBackend. Once Phase 4 lands, HcsBackend can be retargeted onto WindowsBuilder if desired; for now they co-exist.

§Cross-platform compilation

The data types (WindowsBuilder, WindowsBuildConfig, BuildContext, BuildSkeleton, LayerRef, WindowsLayerEntry, BaseImageManifest) compile on every host so unit tests run on the CI Linux runners. The actual base-layer materialisation in WindowsBuilder::build_skeleton and the HCS-driven RUN execution in WindowsBuilder::execute_instruction are gated on target_os = "windows"; on other hosts they return BuildError::NotSupported. Phase 4 follow-up tasks preserve this gating discipline.

Structs§

BaseImageManifest
Resolved manifest information for the pulled base image.
BuildContext
Inputs to a single build.
BuildSkeleton
Output of WindowsBuilder::build_skeleton — the parsed Dockerfile plus the materialised base layer chain plus the resolved base manifest.
BuiltImage
Final emitted artifact for one image: the OCI manifest blob, the image config blob, and the descriptor list for every layer the manifest references.
EmittedLayer
Locally-produced layer blob staged on disk for push (task 4.E).
ExecutedInstruction
One executed Dockerfile instruction recorded in BuildSkeleton::instruction_log.
LayerRef
One base-image layer reference threaded into BuildSkeleton.
OciHealthcheck
OCI healthcheck shape used by OciImageConfig.
OciImageConfig
OCI image config accumulated during instruction execution.
RegistryPushTarget
Real PushTarget backed by zlayer_registry::ImagePuller.
WindowsBuildConfig
Configuration for the Windows builder.
WindowsBuilder
Native WCOW image builder.
WindowsLayerEntry
On-disk reference to one materialised parent layer.

Traits§

PushTarget
Abstraction over the wire-side push operations the WCOW builder needs.