跳至主要内容

建置範例自訂映像

本教學會建立已簽署的 Modalix 映像,包含小型應用程式、設定檔與自動啟動服務。PIB 已內附完整範例,不必複製儲存庫或在電腦上安裝建置工具。CI 也會在 x86 與 ARM64 測試相同映像規格。

1. 安裝並檢查 PIB​

安裝 sima-cli,並啟動使用 Linux 引擎的 Docker,然後執行:

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

若目前終端機找不到 pib,請開啟新的終端機。Bash 或 Zsh 也可立即更新 PATH:

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

PIB 使用原生 x86 或 ARM64 容器,並在 x86 自動設定 ARM64 模擬器。本 minimal 映像範例需要允許特權 Docker 容器,且專案位置與 Docker 儲存空間各有至少 10 GiB 可用容量。

Windows 安裝使用原生啟動器與 Linux 容器模式的 Docker。Windows 安裝程式單元測試已通過,但 Docker Desktop/WSL2 的完整映像建立仍未完成驗證。下列命令使用 Bash 引號語法。

2. 將範例複製到專案​

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

您會自訂下列檔案:

檔案用途
image.yaml映像類型、版本、套件、覆蓋層、掛鉤與簽署設定
package-root/usr/bin/pib-example-app範例 Debian 套件安裝的應用程式
package-root/DEBIAN/control套件名稱、版本與架構
overlay/etc/pib-example.conf複製到映像的應用程式設定
overlay/etc/systemd/system/pib-example.service服務定義
hooks/enable-example.sh啟用服務並寫入建置標記

若要開啟容器內的 Linux 殼層:

pib shell

專案會掛載於 /workspace。執行 exit 返回電腦。其餘命令都在電腦上的專案目錄執行,每個 pib 命令都會自動啟動容器。

3. 建立開發簽署身分​

pib keys init --cn 'My Company Development'

這會建立 CA、SWU 簽署憑證與私密金鑰,以及自訂 Debian 套件的簽署身分。完成後將 keys/ca.key 移至專案外的安全位置。更新既有開發板時請維持相同 CA。正式出貨映像應使用組織的正式簽署流程。

4. 封裝並簽署應用程式​

在 PIB 中建置套件,然後簽署並驗證:

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

範例是殼層指令碼,因此使用架構 all。編譯的 Modalix 應用程式通常須透過 SDK 為 arm64 建置。PIB 接受 ARM64 或架構無關套件,不會交叉編譯應用程式原始碼。

5. 檢查映像規格​

範例包含以下自訂設定:

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

套件清單使用 Debian 套件名稱,而不是 .deb 檔案名稱。可用編輯器修改 overlay/etc/pib-example.conf,嘗試自己的設定。掛鉤會在套件安裝後啟用範例服務。

映像版本必須是容器的平台版本加上建置編號,例如 3.0.0.1。下一個映像請增加最後的數字。開發板會套用禁止降級原則。

6. 建置、簽署並驗證映像​

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

第一個命令會建立新根檔案系統、安裝應用程式、套用覆蓋層與掛鉤、產生部署成品,並簽署及驗證 SWU。第二個命令示範使用專案預設 CA 與相鄰建置資訊清單的獨立驗證。

7. 尋找輸出​

開啟專案的 out/ 目錄:

輸出使用方法
*.swu執行中開發板的已簽署軟體更新
*.img.gz初始佈建或復原的完整磁碟映像
*.manifest.json已安裝套件版本、來源與建置識別資訊
*.cdx.json軟體物料清單
SHA256SUMS成品校驗碼

SWU 與完整磁碟映像是不同部署格式。SWU 安裝與初始 CA 信任設定請遵循開發板更新參考。完整磁碟映像請使用 Modalix 佈建程序。正式環境使用前,先在開發板驗證映像。

8. 用自己的應用程式取代範例​

使用 SDK 建置 ARM64 Debian 套件,放入 custom-debs/,並將套件名稱加入 image.yaml。修改設定、服務與掛鉤,再次執行套件簽署與映像產生。SDK、PIB 與 DevKit 的角色請參閱 SDK 架構指南。

加速重複建置​

PIB 使用 pigz 執行 gzip 相容的平行壓縮。若要在建置間重複使用已驗證的套件下載:

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

每次建置仍會檢查儲存庫簽章與套件雜湊。暖快取不會重用根檔案系統,也不會略過套件安裝、掛鉤、簽署或驗證。