# x-kernel-builder-image

**Repository Path**: openkylin/x-kernel-builder-image

## Basic Information

- **Project Name**: x-kernel-builder-image
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-27
- **Last Updated**: 2026-08-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# X-Kernel builder image

Reproducible CI image sources for X-Kernel. Phase 1 produces an amd64 release
candidate without embedding Jenkins-agent caches or project build output.
Phase 2 adds a native arm64 image while preserving the same CI command
contract.

## Build

```bash
./build.sh
```

The default result is:

```text
yeanwang/x-kernel-builder:v2.0.0-rc.4-amd64
```

Build the native arm64 variant on an arm64 Docker host with:

```bash
PLATFORM=linux/arm64 ./build.sh
```

The arm64 image uses Debian's native `musl-gcc` for the native
`aarch64-linux-musl-gcc` command. This avoids duplicate CRT startup objects
when Rust links the self-contained `aarch64-unknown-linux-musl` target. The
checksum-pinned Zig 0.16.0 ARM64 release continues to provide the x86_64 and
riscv64 Linux-musl cross-compiler commands. The amd64 image retains the Phase
1 musl.cc toolchains.

All upstream archives and container bases are pinned in `versions.env` and
`checksums/`.

## Published release candidate

The combined tag selects the native image for the Docker host architecture:

```bash
docker pull \
  yeanwang/x-kernel-builder:v2.0.0-rc.4@sha256:7773cf86f9cc84638a8e83d11c6e04a111c98fe36a9d5a823379bc46ce13b660
```

The same release candidate is also available through the explicit
architecture-specific tags. The combined OCI index contains only native
`linux/amd64` and `linux/arm64` manifests.

## Jenkins Agent identity contract

The runtime image is intentionally non-root. It runs as `jenkins` with numeric
UID/GID `1000:1000` and supplementary device GID `36`. Jenkins Agent hosts must
use the same IDs. `/dev/kvm` and `/dev/vhost-vsock` must be owned by group 36
with mode `0660`, and Pipeline containers should expose those devices
explicitly rather than use `--privileged`.

Docker's default seccomp profile rejects `socket(AF_VSOCK, ...)` even when
`/dev/vhost-vsock` is present and writable. X-Kernel runtime-test containers
therefore disable only the seccomp filter while retaining the non-root user,
Docker's dropped capability set, explicit device allowlist, and
`no-new-privileges`. This is independent of distribution-specific seccomp
files; an older Kylin `containers-common` profile was rejected because it also
blocks `clone3`, preventing Git from creating its DNS worker thread.

An Agent receives the Jenkins label `container-vsock` only after this exact
container-side probe succeeds:

```bash
docker run --rm \
  --security-opt seccomp=unconfined \
  --security-opt no-new-privileges=true \
  --device=/dev/vhost-vsock \
  --group-add 36 \
  yeanwang/x-kernel-builder:v2.0.0-rc.4@sha256:7773cf86f9cc84638a8e83d11c6e04a111c98fe36a9d5a823379bc46ce13b660 \
  python3 -c 'import socket; print(socket.socket(socket.AF_VSOCK, socket.SOCK_STREAM))'
```

Do not substitute `--privileged` or label a host merely because the device
node exists. The host must also load `vhost_vsock` at boot, for example through
`/etc/modules-load.d/xkernel-vsock.conf`.

The image pre-owns all writable cache and build mount points. A newly created
Docker volume therefore inherits the correct ownership without Pipeline
`chown`/`chmod` repair steps. Installed Cargo tools remain immutable under
`/usr/local/cargo`; mutable Cargo state is isolated under
`/xkernel-cache/cargo`.

`v2.0.0-rc.2` introduced this runtime identity contract. `v2.0.0-rc.3`
added the missing immutable `cargo-fmt -> rustup` proxy required by
`cargo +<toolchain> fmt`. `v2.0.0-rc.4` adds an immutable Cargo source
template which replaces crates.io with rsproxy. A fresh Cargo named volume
inherits `/xkernel-cache/cargo/config.toml` automatically while downloaded
registry and Git data remain mutable in that volume. The two native rc.4
images are thin, network-independent derivatives of the checksum-pinned
multi-arch rc.3 digest:

Dependency downloads remain demand-driven in the parallel build stages; the
Jenkins Setup stage does not serialize an eager `cargo fetch --locked`.

```bash
./build-runtime-contract.sh
PLATFORM=linux/arm64 ./build-runtime-contract.sh
```

This build preserves the verified QEMU/GDB/toolchain bytes. The full
`Dockerfile` contains the same proxy, Cargo source and runtime contract for
subsequent complete image rebuilds.

An existing non-empty Cargo volume created by rc.2 or rc.3 does not receive
Docker's initial copy-up again. Migrate it once on each Agent host:

```bash
docker run --rm \
  --mount type=volume,src=xkernel-cargo-home-v2,dst=/xkernel-cache/cargo \
  --entrypoint bash \
  yeanwang/x-kernel-builder:v2.0.0-rc.4@sha256:7773cf86f9cc84638a8e83d11c6e04a111c98fe36a9d5a823379bc46ce13b660 \
  -euo pipefail -c '
    install -m 0644 /usr/local/share/xkernel/cargo-config.toml \
      /xkernel-cache/cargo/config.toml.rc4
    mv -f /xkernel-cache/cargo/config.toml.rc4 \
      /xkernel-cache/cargo/config.toml
  '
```

This is configuration seeding, not ownership repair, and is safe to repeat.

## Verify

```bash
./scripts/verify-image.sh
./tests/smoke-qemu-gdb.sh
./tests/smoke-runtime-volumes.sh
XKERNEL_SOURCE=/home/yean/code/x-kernel ./tests/build-xkernel.sh
```

The X-Kernel check uses the required project workflow: copy a platform
`defconfig` to `.config`, run `make defconfig`, then use the Makefile's
`clippy` and `build` targets. For diagnosis only, `RUN_CLIPPY=0` can isolate a
plain build failure; the acceptance gate always uses the default value.

See `docs/phase-1.md` for the image/host boundary and amd64 acceptance gate.
See `docs/phase-2.md` for native arm64 construction and its acceptance result.