Files
mi8-platina-linux/docs/BUILDING.md
T
shenlei 4f3fe1f94b
Offline project checks / check (push) Canceled after 0s
Fix candidate build metadata and runtime safeguards
Repair kernel patch formatting and refresh kernel/camera package revisions and checksums. Integrate battery guard into generated images, correct charging controls and emergency shutdown handling, and reject invalid camera authentication configuration.

Extend recipe validation and regression coverage, and update build and installation documentation. Kernel, camera and image compilation remain pending on the build server.
2026-11-09 10:49:22 +09:00

7.2 KiB

Building Platina Linux

This is a source-only development port. Integration 0.8.1, signed camera userspace 0.7.1-r31 and the existing r9-boot/r11-sensor runtime combination were checked on one Tianma Mi 8 Lite. The public kernel recipe is 7.2.12-r13, a development candidate, not the exact tested boot/modules combination. A combined r13 kernel and a new full 0.8.1 installation image are not hardware qualified. The last full base image was built/audited for 0.3.1. Camera packages are separate; see CAMERA.md.

Build host

Use Linux, Python 3.11+, Git, Make, a POSIX shell and sudo. The build creates pmbootstrap chroots and needs Internet access, substantial disk space and time. It uses two jobs at nice level 10. No host services or phones are restarted.

On Debian/Ubuntu, typical host tools are:

sudo apt install git g++ python3 make sudo openssh-client e2fsprogs util-linux kmod mtools fastboot
# Required for the versioned boot/shutdown screens included by make images.
sudo apt install python3-pil fonts-dejavu-core

make doctor reports missing core tools without installing them. Kernel compilers and package dependencies are installed inside the build chroots by pmbootstrap. Python's standard library is enough for the basic offline test suite; the image runtime integration tests and full image builder also need Pillow and DejaVu Sans. Camera conversion/crop tests compile small native C++ programs with g++.

Personal build inputs

mkdir -p config
cp /PATH/TO/YOUR/ADMINISTRATOR-KEY.pub config/admin-builder.pub

Use a dedicated key if appropriate. Only its public half enters the image. The user account is server, with passwordless sudo for administration. Password and root SSH login are disabled. Keep the private key outside this repository.

Firmware is not distributed here. From a legally obtained matching stock ROM, extract images/NON-HLOS.bin without running any ROM scripts, and obtain the matching a512_zap.elf GPU firmware from your own vendor firmware. The pinned reference is the Mi 8 Lite global stock firmware V12.0.3.0.QDTMIXM; other inputs are rejected if their hashes differ.

The recipe expects three local inputs: a512_zap.elf, firmware-xiaomi-platina-bdwlan.tar.gz and firmware-xiaomi-platina-modem.tar.gz. The helper reads the FAT firmware image with mtools, creates deterministic archives and checks all three against the recipe before writing them:

python3 scripts/prepare-firmware.py \
  --modem-image /PATH/TO/NON-HLOS.bin \
  --gpu-firmware /PATH/TO/a512_zap.elf

The output is config/firmware/, which is ignored by Git. Missing matching firmware is a build prerequisite; this repository does not silently substitute another phone's calibration, modem firmware or administrator key.

Prepare and compile

make check
./scripts/project prepare --profile candidate --fetch
make kernel PROFILE=candidate
make images OUTPUT=candidate-local
make verify DIR=artifacts/candidate-local
make audit DIR=artifacts/candidate-local

Preparation pins pmbootstrap, pmaports and its channel table from project/sources.lock.json. It creates a new managed checkout and refuses to overwrite one. After changing a versioned recipe, run make sync before rebuilding. Checksum checks parse APKBUILD as text rather than executing its shell on the host.

The image contains the public key and proprietary firmware you provided. It is therefore your local installation image, not automatically a public artifact. The builder stops pmbootstrap mounts before copying/hashing filesystem images. Source revisions are pinned, but external Alpine repositories/toolchain packages are not fully frozen; bit-for-bit reproducible full builds are not promised.

Integrated runtime and initramfs audit

make images builds the versioned boot logo and Power off screen, installs the Python display/shutdown helpers and headless hook, and enables the OpenRC Power + Volume Up service with the verified three-second policy. The image audit checks file hashes, decoded frames, permissions and service links without touching the display or invoking shutdown. No experimental PMIC module is included.

The USB current helper and NetworkManager dispatcher are also included. They are inert without a separately supplied /etc/platina/usb-power.json policy; no host identity or increased-current allowance is cloned from the development phone. Wi-Fi credentials and monitoring credentials also remain per-installation inputs.

New images also install and enable platina-battery-guard. It requests charging between 50% and 65%, pauses charging at 45°C until the battery cools to 42°C, and requests orderly shutdown at 5% while discharging. An active thermal cutoff stays latched if a temperature read fails. Emergency shutdown uses init directly and keeps retrying if shutdown fails; it does not depend on the display helper.

Charging control requires a writable charging_enabled switch or a charge_behaviour interface supporting auto and inhibit-charge. The guard never changes current_max or charge_control_limit_max. If neither switch is available it logs Charging control unavailable; the charge/temperature policy then cannot be enforced, while low-battery shutdown remains active. Qualify the actual switch and charge/discharge behavior on the phone before relying on it.

The mkinitfs version used by this port can copy full-rootfs module indexes into an initramfs containing only some modules. The builder automatically regenerates indexes for the modules actually included in the exported boot image. The final boot.img and initramfs are hashed only after this correction. The unmodified pmbootstrap export links are intermediate files, not the accepted output bundle.

Use boot.img and xiaomi-platina.img from the same final candidate-local bundle. For manually exported older images, scripts/scope-initramfs-modules.py remains available. The correction preserves the kernel, DTB and rootfs command line.

Exported files include boot.img, xiaomi-platina.img, initramfs, kernel and DTB. Keep the manifest and corresponding APKs for your own rollback records.

Separate display asset bundles

make splash
python3 scripts/prepare-display-frame.py your-image.png --output artifacts/custom-frame

The original logo is preserved; the integration version is added during rendering. These commands create separate local bundles for review or an explicitly planned existing-installation update. A fresh make images already includes both release screens. See display setup and shutdown behavior.

Camera packages

After preparing the candidate environment, build the isolated Mesa and camera packages locally with scripts/build-camera-userspace.py; see the complete camera guide. The camera package pins libcamera 0.7.1-r32 and the active control/GPU patches. Inactive DMA, LUT and other rejected experiment patches are not part of this source release. No camera credentials, host-specific deployment helpers or prebuilt APKs are included. make images currently integrates the base display/shutdown runtime, not the separately installed camera packages. Do not describe such an image as a fully tested 0.8.1 camera installation.