Skip to content

Build FPLinux

FPLinux is built from source on your PC. One command builds a complete image for one phone. The next page, Run FPLinux, loads that image into the phone’s RAM.

  • A Linux x86-64 PC with Python 3.14.
  • Unprivileged user namespaces, and newuidmap and newgidmap with subordinate UID and GID ranges for your user.
  • Network access for setup, or matching saved dependency inputs.
  • The exact target name from your phone page.

Check the phone’s support status, boot key and storage limits before building. The examples below use nokia-ta1618; replace it with your phone’s target.

FPLinux keeps one prepared Alpine root filesystem in its working data directory and runs it with its pinned Kern runtime. Builds, source checks and formatting use this filesystem read-only, with writable files kept in their own working directories.

FPLinux keeps downloads, the prepared environment, build results, logs and connection state under .data/ beside the checkout. Standalone archives also use .data/ beside their launcher. Public commands manage this directory; keep your source files and experiments outside it.

Set FPLINUX_DATA_DIR before setup to choose another location, for example a directory on a larger disk:

PC
export FPLINUX_DATA_DIR="$HOME/FPLinuxData"
./fplinux data-path

The value can be an absolute path or a path relative to the checkout or extracted archive. It is independent of the terminal’s current directory. data-path prints the selected absolute path without preparing the environment; data-path --check also checks that the location does not overlap source files or local private material. Keep checkout working data outside site/: its tools treat that whole directory as website input. An empty value is an error.

Keep the same location while using or reconnecting to a running phone. Changing it selects another store; it does not move files or saved connections. Explicit file paths passed to commands keep their own meaning. Your personal phone data store remains separate, so replacing a checkout or archive does not require another compatible phone backup.

Use prune to remove disposable files. Removing the entire working directory also removes the prepared environment and saved connection keys.

  1. Get the source:

    PC
    git clone https://github.com/fplinux/fplinux.git
    cd fplinux
  2. Prepare the build environment and your phone’s dependencies, then check the host:

    PC
    ./fplinux setup nokia-ta1618
    ./fplinux doctor

    setup nokia-ta1618 downloads the pinned inputs for this target and prepares the shared build environment. If the environment’s inputs change, it prepares and validates a complete replacement before switching to it and removing the previous environment. Changes to phone sources reuse the existing environment. doctor reports anything on the host that prevents a build.

  3. Build the image for your phone:

    PC
    ./fplinux build nokia-ta1618

    A successful build reports the build directory after output::

    Output
    build nokia-ta1618 --build-type release: OK
    output: .data/out/nokia-ta1618/…
    ramboot.bin SHA256: …

Builds use up to eight CPUs and run at a lower scheduling priority, so the desktop stays usable. Add --jobs N to change the number of parallel compilation jobs, or --verbose to watch the complete tool output. Run ./fplinux build --help for all options.

Each build has an 8 GiB memory limit. Add --memory-mib N to set a positive limit in MiB, for example --memory-mib 4096 for 4 GiB on a host with less available RAM. Build processes use nice level 10, preserving an already lower scheduling priority.

Where supported, Bluetooth, FM radio, the speaker and tuned audio levels need data from your own phone. UMS9117 RAM builds keep this data separate from the kernel and root filesystem: run reuses compatible saved data or prepares it as needed without rebuilding. A live NAND backup requires a second launch. For a microSD system card or Qin’s optional original-file import, prepare the data before building the image; see Device data.

Add --without-device-data to build without prepared personal data while keeping it in your personal store. A later build without this option includes the selected prepared data again. Use this option when building a Qin image for a standalone RAM archive; see Packaging.

The Xiaomi Qin 1s+ build also compiles its RAM-loading stages and includes them in the bundle. Use xiaomi-qin-1s-plus with the same build, run, console and verify commands; no separate loader files or phone backup are needed to start it. Its standalone archives run on Linux x86-64.

Two choices change what you build:

  • Boot mode. The default build runs entirely from RAM and leaves nothing behind after power-off. Supported UMS9117 targets use --profile microsd-uboot for a microSD system card; the Xiaomi Qin 1s+ implementation uses --profile microsd-root, which loads Linux over USB and uses the card for the system root. Both require the PC at every start. See microSD system card for profile selection and the shared procedure, and check your phone’s support status before selecting a profile.
  • Build type. release is the default. --build-type debug adds kernel diagnostics; see Debugging.

Use the same profile and build type in every command for that build. If you built with options, pass the same options to run, console, verify and inspect. Packaging accepts release builds only:

PC
./fplinux build nokia-ta1618 --build-type debug
./fplinux run nokia-ta1618 --build-type debug
./fplinux console nokia-ta1618 --build-type debug

Each combination of phone, profile and build type is kept separately. Building one does not replace another.

Choose the preparation you need:

Command Prepares
./fplinux setup The shared Alpine build environment
./fplinux setup nokia-ta1618 The shared environment and this target’s dependencies for every supported boot profile, release and debug builds, and Linux archives
./fplinux setup nokia-ta1618 --host windows The same target build dependencies, with Windows archive tools, runtime and driver inputs instead of the Linux archive runtime
./fplinux setup --site The pinned site runtime and npm dependencies, without the Alpine environment
./fplinux setup --all The shared environment, every checkout dependency and the site tools

The target, --site and --all selections are mutually exclusive. --host requires a target. Setup prepares inputs and tools; build phone images, ZIP archives and the offline site with their respective commands. --force rebuilds only the shared environment and cannot be used with --site.

Builds use local inputs and never download dependencies. After setup, run the same build command with or without a network connection:

PC
./fplinux build nokia-ta1618

If the environment or an exact input is missing or out of date, the command stops and names the setup command to run. Add --offline to setup when all selected originals are already stored locally, for example ./fplinux setup nokia-ta1618 --offline.

To keep the pinned downloads and build environment outside the build cache, or restore them into a matching checkout, use Dependency snapshots.

FPLinux reuses earlier build results and removes obsolete build intermediates automatically. To list disposable cache entries, including workspaces left by interrupted commands and old logs, then remove them:

PC
./fplinux prune
./fplinux prune --apply

Without --apply, prune only shows what it would remove. Review its candidate: entries before applying it; protected: entries are retained.

A successful build proves that your checkout produced a complete image. It does not prove that the image boots or that a feature works on a phone. The support status lists what works on each phone.

The command prints where its complete log is stored. To show the failed part of the most recent build:

PC
./fplinux logs show latest --command build --failed

See Debugging for more ways to read logs.

A build can reach its memory budget while the host still has free memory. In that case, increase the budget with --memory-mib N, choosing a value that fits the host’s available RAM. For example:

PC
./fplinux build nokia-ta1618 --memory-mib 12288

This raises the build limit from 8 GiB to 12 GiB; leave enough RAM for the rest of the PC. If the host itself runs out of memory, close other memory-heavy programs or reduce parallel compilation:

PC
./fplinux build nokia-ta1618 --jobs 1

Rebuild it from scratch, then check the host again:

PC
./fplinux setup --force
./fplinux doctor

Run FPLinux on your phone.