Skip to content

Dependency snapshots

A dependency snapshot keeps the pinned external inputs and build environment outside the checkout’s disposable build cache. It belongs with the matching source checkout; it does not contain the source itself or a built phone image.

sources.lock.toml owns direct source, tool, font, runtime and loader originals. Environment, platform, host and package declarations select those records by source ID. Native npm locks and Alpine package locks retain their dependency graphs and exact package checksums. A snapshot collects the inputs selected by all supported targets, profiles and build types, including debug tools and Linux, Windows and site dependencies.

Use ./fplinux inspect inputs, ./fplinux inspect inputs nokia-ta1618 --host windows, ./fplinux inspect inputs --site or ./fplinux inspect inputs --all to check locally stored originals without downloading or installing anything. The command reports counts and lists missing or mismatched inputs, then exits with status 1 if any selected original is unavailable. Target selection covers every supported profile and build type. Environment and site-tooling status only report local receipts and files; they do not execute or verify the installed tools.

Use the matching source revision and the twelve-character build ID shown in the release name, runtime ZIP filename or the phone’s Settings → About → Build row. Replace <release-id> below with that ID:

PC
./fplinux dependencies restore --release <release-id>
./fplinux setup nokia-ta1618 --offline
./fplinux doctor

Each public Release contains its complete inputs-only snapshot, split into transport parts, alongside the runtime ZIPs and corresponding sources. Restoration downloads those public assets without private credentials, checks their association with this source checkout, verifies the transport and stored originals, then restores the declared cache files. It selects the explicit build ID; there is no latest selection.

The setup example selects nokia-ta1618; replace it with your target. Use the setup selection for a Windows archive, site tools or the complete checkout. Setup installs tools and prepares dependencies; it does not build images or archives.

The snapshot preserves the build inputs, not the host operating system. Use a Linux x86-64 host with Python 3.14, Git, GNU tar, Zstandard and coreutils, plus the user namespaces and subordinate-ID tools described in Build FPLinux. An incompatible source checkout is rejected. Prepared device data and private package-signing keys remain separate local inputs.

Prepare the build environment with Build FPLinux, then choose a folder outside the working data directory on a disk with enough free space. Replace /path/to/fplinux-inputs in the examples below with that folder’s path. Use the same path to verify or restore the snapshot:

PC
./fplinux dependencies create "/path/to/fplinux-inputs"
./fplinux dependencies verify "/path/to/fplinux-inputs"

create selects the external inputs declared by the checkout’s locks, package recipes and build environment configuration. It checks each download against its declared checksum and any declared size, stores shared bytes once and archives the prepared build root filesystem. Missing inputs are downloaded at their exact declared versions; the command does not choose replacements.

To require locally stored inputs, add --offline. Repeat --from PATH to look for original downloads in additional local files or directories; only bytes that match a declared checksum are accepted. Replace /path/to/downloads with the folder containing your saved downloads:

PC
./fplinux dependencies create "/path/to/fplinux-inputs" --offline --from "/path/to/downloads"

Offline creation requires every declared archive to be available locally. The command reports missing exact inputs instead of querying a package registry for replacement versions.

The directory’s manifest.json records the selected inputs, original URLs, checksums, sizes and environment state. Each directory holds one input set and its saved build environment. Repeating create with the same inputs and environment verifies and reuses the saved archive. A changed input set or build environment requires another directory; a conflict leaves the saved manifest intact.

PC
./fplinux dependencies verify "/path/to/fplinux-inputs"

Verification checks the stored bytes and their agreement with this checkout’s current external declarations. Comments, mapping-key order and unrelated driver edits do not change the input set; meaningful sequence order does. A successful verification establishes stored-input integrity. It does not show that a phone build can complete offline or produces identical output bytes.

PC
./fplinux dependencies restore "/path/to/fplinux-inputs"
./fplinux doctor

Restoration verifies the complete snapshot before writing its declared cache destinations and requires the current external declarations to match. Restoring the saved environment also requires its exact preparation recipe. Its root filesystem archive preserves file bytes, links, logical numeric owners and permission bits; these are checked before the environment becomes available. Timestamps, extended attributes and hardlink relationships are outside that comparison.

An existing cache file with different bytes is reported and retained for inspection before input restoration writes any files. The snapshot restores the host environment and external inputs, not compiled APKs, phone root filesystems, kernels or successful build results. Build the selected phone afterwards:

PC
./fplinux build nokia-ta1618

Add --inputs-only when creating a snapshot to omit the environment archive:

PC
./fplinux dependencies create "/path/to/fplinux-inputs" --inputs-only

To recreate the environment from those originals, restore only the inputs and request an offline setup:

PC
./fplinux dependencies restore "/path/to/fplinux-inputs" --inputs-only
./fplinux setup --offline --force

The selected inputs include npm registry archives declared by the root and site/package-lock.json, including locked optional platform packages. The site uses the exact Node.js and npm versions declared by the root package, with a separate Linux x86-64 glibc Node.js original. Site registry archives are restored under downloads/site/npm/ inside the selected working data directory.

After restoring inputs, ./fplinux setup --site --offline installs the pinned site runtime and runs npm ci offline using those originals. To acquire and install only site inputs directly, use ./fplinux setup --site. Neither selection prepares Alpine or builds the offline site. Follow Preview this site to select that runtime and run the site tools.

Export an inputs-only snapshot into a new folder. Replace /path/to/fplinux-inputs-parts with the destination you want to create:

PC
./fplinux dependencies export "/path/to/fplinux-inputs" "/path/to/fplinux-inputs-parts"

The transport is a streaming tar.zst split into parts of at most 1 GiB. Part names use FPLinux-<release-id>-inputs.tar.zst.part-00000 and increasing part numbers. FPLinux-<release-id>-inputs.sha256 lists their checksums; DEPENDENCIES.json binds that index and snapshot to the source release. Keep these files together. The complete Release’s separate SHA256SUMS covers its final assets, including this transport index and metadata.

Import checks the source association, index and every listed part before extracting the normal snapshot. Use the folder containing the exported parts as the first path and a new folder for the restored snapshot as the second:

PC
./fplinux dependencies import "/path/to/fplinux-inputs-parts" "/path/to/imported-inputs"
./fplinux dependencies verify "/path/to/imported-inputs"
./fplinux dependencies restore "/path/to/imported-inputs" --inputs-only
./fplinux setup --offline --force

Transport preserves the normal snapshot manifest and referenced objects. It does not include an environment archive.

Clean preparation downloads the entire declared input set from its original URLs and installs a fresh environment in a new checkout. Run it separately only when you intend to perform that full online operation; restoring saved inputs is a different workflow. It needs a new directory outside the working cache and at least 10 GiB of free space. Replace /path/to/fplinux-preflight with the directory you want to create:

PC
./fplinux ci preflight --commit <full-commit-sha> --directory "/path/to/fplinux-preflight"

Use the complete lowercase commit SHA, not a branch name or short ID. The command installs from the newly acquired originals, runs doctor, verifies the saved snapshot and records completion for that commit. It does not prepare uncommitted changes for a future push.

Install the local pre-push and commit-message hooks with git config core.hooksPath .githooks. The pre-push hook only checks that the actual incoming main commit has a completed preparation. It does not download inputs or install an environment. A new commit needs its own preparation. Git’s --no-verify can bypass a local hook; the publication workflow separately requires its checks and complete release assets.