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.
What you need
Section titled “What you need”- A Linux x86-64 PC with Python 3.14.
- Unprivileged user namespaces, and
newuidmapandnewgidmapwith 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.
Working data directory
Section titled “Working data directory”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:
export FPLINUX_DATA_DIR="$HOME/FPLinuxData"./fplinux data-pathThe 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.
Build your first image
Section titled “Build your first image”-
Get the source:
PC git clone https://github.com/fplinux/fplinux.gitcd fplinux -
Prepare the build environment and your phone’s dependencies, then check the host:
PC ./fplinux setup nokia-ta1618./fplinux doctorsetup nokia-ta1618downloads 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.doctorreports anything on the host that prevents a build. -
Build the image for your phone:
PC ./fplinux build nokia-ta1618A successful build reports the build directory after
output::Output build nokia-ta1618 --build-type release: OKoutput: .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.
Choose a build
Section titled “Choose a build”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-ubootfor 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.
releaseis the default.--build-type debugadds 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:
./fplinux build nokia-ta1618 --build-type debug./fplinux run nokia-ta1618 --build-type debug./fplinux console nokia-ta1618 --build-type debugEach combination of phone, profile and build type is kept separately. Building one does not replace another.
Select setup inputs
Section titled “Select setup inputs”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.
Build without network access
Section titled “Build without network access”Builds use local inputs and never download dependencies. After setup, run the same build command with or without a network connection:
./fplinux build nokia-ta1618If 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.
Free disk space
Section titled “Free disk space”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:
./fplinux prune./fplinux prune --applyWithout --apply, prune only shows what it would remove. Review its candidate: entries before applying it; protected: entries are retained.
What a successful build proves
Section titled “What a successful build proves”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.
Troubleshooting
Section titled “Troubleshooting”The build fails
Section titled “The build fails”The command prints where its complete log is stored. To show the failed part of the most recent build:
./fplinux logs show latest --command build --failedSee Debugging for more ways to read logs.
The host runs out of memory
Section titled “The host runs out of memory”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:
./fplinux build nokia-ta1618 --memory-mib 12288This 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:
./fplinux build nokia-ta1618 --jobs 1The build environment looks broken
Section titled “The build environment looks broken”Rebuild it from scratch, then check the host again:
./fplinux setup --force./fplinux doctorNext step
Section titled “Next step”Run FPLinux on your phone.