Skip to content

Packaging

./fplinux package turns an existing release build into an archive for one registered phone and PC operating system. Users follow Standalone archive.

Build the phone once, then package the hosts you need:

PC
./fplinux setup nokia-ta1618
./fplinux build nokia-ta1618 --without-device-data
./fplinux package nokia-ta1618
./fplinux setup nokia-ta1618 --host windows
./fplinux package nokia-ta1618 --host windows

The default host is Linux x86-64. RAM archives can also be packaged for Windows 10 or 11 x64 through --host windows, including Xiaomi Qin 1s+:

PC
./fplinux setup xiaomi-qin-1s-plus
./fplinux build xiaomi-qin-1s-plus --without-device-data
./fplinux package xiaomi-qin-1s-plus
./fplinux setup xiaomi-qin-1s-plus --host windows
./fplinux package xiaomi-qin-1s-plus --host windows

USB loading and SSH from Windows have not been verified with Qin 1s+.

Packaging reads the current release build without rebuilding it. It rejects stale source context, changed built files and unsupported hosts. Debug remains a build option; package accepts release builds only. Host tools and corresponding sources are prepared from the saved local inputs. Select the archive host with setup to acquire its originals; setup does not create the ZIP. See Dependency snapshots to restore saved inputs.

The runnable ZIP includes the RAM image, phone loaders, the selected host’s Python and OpenSSH, one launcher, README.txt, licenses, the build manifest and SHA256SUMS. It also includes the extraction tools needed by the selected phone. Optional APKs, the offline site, prepared phone data, private keys and session logs are excluded. RAM images receive personal phone data at launch, so publishing one does not publish the contents of your personal store.

Names use FPLinux-<target>-<linux|windows>-x64-<release_id>.zip. The same twelve-character build ID appears in every phone and host archive made from the same public source context and in Settings → About → Build. A clean checkout uses the first twelve characters of its Git commit. Changed public sources get a content-based ID. A matching -sources.zip accompanies a locally packaged runtime. --output-directory PATH selects the destination; the default is out/releases/ inside the working data directory. An existing name with different bytes is an error.

The archive owner uses Run.sh or Run.cmd for preparation, loading and reconnecting. Phones with required runtime data reuse compatible inputs from the personal store, reading the phone again only when needed. Packaging and a native launcher check without a phone do not establish USB loading or hardware operation. The phone pages give the current feature and power limits.

Linux exports for an external root filesystem retain the selected profile, its system image, optional APKs, host-installed Python/OpenSSH and offline documentation:

PC
./fplinux build nokia-ta1618 --profile microsd-uboot
(cd site && npm run build:offline)
./fplinux package nokia-ta1618 --boot microsd

The filename includes the normalized profile, for example FPLinux-nokia-ta1618-microsd-uboot-linux-x64-<release_id>.zip. --boot microsd and --profile microsd-uboot select the same context. This export can contain prepared personal data selected by the build; keep it private. It is excluded from the public RAM release matrix. See microSD system card for card preparation and safe shutdown.

Install the pinned site tools as described in Contributing before creating the offline documentation. Regenerate it after changing its inputs. The export carries it under docs/; the phone image does not include it.

The workflow in .github/workflows/packages.yml prepares one inputs-only dependency snapshot for the exact event commit and shares that artifact with the check, target-build and documentation jobs. Every target is built once, then packaged sequentially for its supported hosts. ./fplinux ci matrix reports the current eight targets and sixteen runtime selections. Later setup steps use --offline with the restored originals; build and package always use local inputs. The documentation job selects setup --site --offline to install only its site tools.

A complete Release contains the sixteen runnable ZIPs, one common source ZIP, dependency transport parts of at most 1 GiB, their FPLinux-<release_id>-inputs.sha256 index, DEPENDENCIES.json, RELEASE.json and the outer SHA256SUMS. Each runtime README names the final common source ZIP. DISTRIBUTION.json inside that source ZIP binds each target, host and kernel identity to its final runtime hash. Shared source paths are stored once; variable host and target build material remains under selections/<target>/<host>/.

To combine existing runtime/source pairs with the prepared input transport:

PC
./fplinux ci assemble --input-dir packages --inputs-dir inputs --output-dir distribution
./fplinux inspect distribution distribution

Inspection checks the complete matrix, final manifest records, file modes, internal and outer checksums, source identity, runtime/source pairing and dependency transport. Native smoke jobs start and reopen every final runtime under ordinary Linux and Windows accounts without a phone. These checks cover launcher and storage initialization; USB driver installation and loading a real phone remain separate checks.

Publication runs only for a canonical main push after the required check, build, assembly and native smoke jobs succeed. A manual workflow run checks the assets without publishing. The publisher uploads a private draft, verifies every remote asset’s name, size and digest, then publishes an ordinary Release. A retry verifies an existing published set or uploads only missing matching draft assets. Release notes compare the current commit with the last actually published Release.

Follow Prepare an exact commit before pushing for the explicit clean-install command and local hook setup. The release pipeline independently acquires one complete input set for its event commit; publication depends on the resulting checks and final assets.

PC
./fplinux inspect source
./fplinux inspect bundle nokia-ta1618
./fplinux inspect bundle nokia-ta1618 --current-source
./fplinux inspect archive "$(./fplinux data-path)/out/releases/FPLinux-nokia-ta1618-….zip"
./fplinux inspect apk path/to/package.apk
  • source shows the current public source snapshot and release identity without building.
  • bundle lists the selected build’s identity, files, sizes and SHA-256 hashes and checks them against its build manifest. Add --current-source to compare source, target workspace, environment receipt and signing identity separately. The receipt comparison does not probe installed environment content. Use --without-device-data or --phone-data PATH when the build used that selection. A stale bundle remains inspectable without the comparison.
  • archive checks a runtime or corresponding-sources ZIP against its complete SHA256SUMS and manifest records. Source inspection also checks the source identity and selected build material. This establishes internal consistency, not authenticity or phone operation.
  • distribution checks the complete release directory, including its runtime/source/input association.
  • apk shows a package’s metadata and file list. It does not install the package, run its scripts or verify its signature.

These inspections need neither the build environment nor a phone.

inspect footprint measures the current build without rebuilding it. Save a report before and after a source change and rebuild, then compare them:

PC
./fplinux inspect footprint nokia-ta1618 --json > before.json
# change the source and rebuild
./fplinux inspect footprint nokia-ta1618 --json > after.json
./fplinux inspect footprint-diff before.json after.json

The report lists boot files, the kernel, compressed and unpacked root filesystem, optional APKs and host debug files separately. These layers overlap, so their sum is not a meaningful total. A package’s size counts the files it owns, not its dependencies, installed disk usage or RAM use. The diff also reports whether root filesystem content is identical; a smaller compressed image alone does not establish lower userspace or memory use.