Skip to main content

Build the sample custom image

This walkthrough creates a signed Modalix image containing a small application, a configuration file, and a service that starts automatically. The complete sample ships in PIB; you do not need to clone this repository or install build tools on your computer. The same image specification is tested on x86 and ARM64 in CI.

1. Install and check PIB​

Install sima-cli and start Docker with a Linux engine, then run:

sima-cli neat install sdk/pib
pib --version
pib doctor

If your current terminal cannot find pib, open a new terminal. In a Bash or Zsh terminal you can also refresh PATH immediately:

export PATH="$HOME/.local/bin:$PATH"

PIB uses a native x86 or ARM64 container. On x86, it automatically configures the ARM64 emulator. Allow privileged Docker containers and at least 10 GiB free in both your project location and Docker storage for this minimal-image example.

Windows installation uses a native launcher with Docker in Linux-container mode. Windows installer unit tests have passed; full Docker Desktop/WSL2 image creation is not yet qualified. The commands below use shell quoting accepted by Bash.

2. Copy the example into a project​

pib init my-custom-image --example custom-image
cd my-custom-image

The files you will customize are:

FilePurpose
image.yamlFlavor, image version, packages, overlay, hooks, and signing settings
package-root/usr/bin/pib-example-appApplication installed by the example Debian package
package-root/DEBIAN/controlPackage name, version, and architecture
overlay/etc/pib-example.confApplication configuration copied into the image
overlay/etc/systemd/system/pib-example.serviceService definition
hooks/enable-example.shEnables the service and writes a build marker

For a Linux shell inside the container, run:

pib shell

Your project is mounted at /workspace. Run exit to return to your computer. The remaining commands in this walkthrough run from the project directory on your computer; each pib command starts the container automatically.

3. Create your development signing identity​

pib keys init --cn 'My Company Development'

This creates a CA, an SWU signing certificate and private key, and the signing identity for your custom Debian packages. Move keys/ca.key to a secure location outside the project after setup. Keep the same CA when updating existing boards. Use your organization's production signing process for shipping images.

4. Package and sign the application​

Build the package inside PIB, then sign and verify it:

pib shell -c 'dpkg-deb --root-owner-group --build package-root custom-debs/pib-example-app_1.0.0_all.deb'
pib sign-debs
pib verify-debs

The application is a shell script, so the package uses architecture all. A compiled Modalix application must be built for arm64, normally using the SDK. PIB accepts ARM64 or architecture-independent packages; it does not cross-compile application source code.

5. Review the image specification​

The example includes these customization settings:

packages:
add: [pib-example-app]
remove: []
overlay: overlay
hooks: [hooks/enable-example.sh]

The package list uses the Debian package name, not the .deb filename. Change overlay/etc/pib-example.conf in your editor to try your own configuration. The hook enables the sample service after package installation.

The image version must match the container's platform release followed by a build number, for example 3.0.0.1. Increase the final number for your next image: boards enforce the image's no-downgrade policy.

6. Build, sign, and verify the image​

pib build --sign --supplier 'My Company'
pib verify

The first command assembles a new root filesystem, installs the application, applies your overlay and hook, creates the deployment artifacts, signs the SWU, and verifies it. The second command demonstrates standalone verification using the project's default CA and the adjacent build manifest.

7. Find the outputs​

Open the project's out/ directory:

OutputHow to use it
*.swuSigned software update for a running board
*.img.gzFull disk image for initial provisioning or recovery
*.manifest.jsonInstalled package versions, origins, and build identity
*.cdx.jsonSoftware bill of materials
SHA256SUMSArtifact checksums

An SWU and a full disk image are different deployment formats. Follow the board update reference for SWU installation and initial CA trust. Use the Modalix provisioning procedure for a full disk image. Qualify your image on a development board before production.

8. Replace the sample with your application​

Build your application as an ARM64 Debian package using the SDK, place it in custom-debs/, and list its package name in image.yaml. Update the configuration, service, and hook for your application, then repeat package signing and image generation. See the SDK architecture guide for the roles of the SDK, PIB, and the DevKit.

Faster repeat builds​

PIB uses pigz for parallel gzip-compatible compression. To reuse verified package downloads between builds:

export PIB_DEB_CACHE="$HOME/.cache/sima/pib-debs"
pib build --sign

Repository signatures and package hashes are checked on each build. A warm cache does not reuse a root filesystem or skip package installation, hooks, signing, or verification.