Skip to content

Contributing

Prepare the pinned environment with ./fplinux setup before running source checks and tests. Use ./fplinux setup --all for the complete quality gate, or select the target whose build inputs you need; see setup selections. Checks, tests and formatting use local inputs and report the setup command needed if an input is missing. These commands do not require a completed phone build, and you do not install formatters or linters yourself. Code follows the code style, and messages from the kernel, loader and phone programs follow the logging contract.

The source is on GitHub. Phone, application and feature pages link to their source under the page title. Porting defines the ownership boundaries for shared code, SoC support, board data and phone packages. Follow those boundaries when adding support or choosing where a change belongs.

PC
./fplinux format scripts/fplinux_cli/cache/prune/operations.py common/host/fplinux-usb-keyboard.c

Pass each file you edited as a path relative to the checkout. The command does not walk directories. It refuses files that have no project formatter instead of guessing one. Tracked and non-ignored untracked sources are accepted. Selected files are formatted together; if any formatter fails, the command leaves them unchanged. The source-format contract describes ordering, templates and format-specific limits.

Use ./fplinux format --plan PATH... to see which tool owns each path without preparing the environment or changing files. ./fplinux format --changed selects staged, unstaged and non-ignored untracked files; append paths to limit that selection. Add --plan to inspect the selection without formatting. Unsupported and site-owned files are listed and skipped when selecting changes.

Declared Linux patches are accepted too. Their affected C and header regions use the pinned Linux formatting tools; other patch contents are retained. This needs the pinned Linux source archive prepared by setup for the affected target. Ordinary plain text and other patch series have no formatter and are rejected.

Before you commit or submit a change, run the complete gate without reusing earlier results:

PC
./fplinux check --no-cache

While you work, run only the parts you need. --list shows them:

PC
./fplinux check --list
./fplinux check python
./fplinux check tests

python checks Python formatting, lint and types. tests runs all five pytest tiers. The complete gate includes both. ./fplinux test selects smaller workloads and always executes them.

On a PC with little memory, check the kernel configurations one at a time:

PC
./fplinux check --no-cache --jobs 1

For check, --jobs limits simultaneous kernel configurations, not test processes. Its default is three when kernel checks are selected, and one otherwise or with --verbose. Explicit values above one require the kernel scope and cannot be combined with --verbose. For build, --jobs instead limits parallel compilation.

Use test --workers N or check --test-workers N to limit parallel native test workers. The default leaves two available CPUs free, up to eight workers. Directory and tier selections of host_tool run in parallel; tests in the same file stay together so their module fixtures are reused. Explicit module and node selections retain sequential execution, order and collection-error handling. Other tiers and host namespace tests also run sequentially. --workers 1 selects sequential execution. Stop-first, sanitizer and outcome-history runs run sequentially; explicit values above one cannot be combined with --failfast or --sanitize.

An ordinary build or RAM load without source changes does not need the gate.

The graphical session, its applications and shared UI libraries participate in the default source checks and test discovery. Focused graphical-session tests can also be selected explicitly with ./fplinux test.

Run pytest workloads by a directory, dotted module, class or test name, a pytest node selector, or one tier:

PC
./fplinux test tests.small.workspace.test_snapshot
./fplinux test 'tests/small/workspace/test_snapshot.py::WorkspaceSnapshotTests::test_snapshot_recipe_includes_file_mode'
./fplinux test tests/host_tool/gui
./fplinux test --tier small

The tiers are small, host_process, host_tool, artifact and public_workflow. Without a selection, all five run in that order. Node selectors use path.py::Class::method or path.py::test_function; append [case-id] to select a parameterized case, and quote brackets in the shell. --verbose shows individual test names and streams output; --failfast stops on the first failure or error. Adjacent selections share one pytest session and its fixtures, except with --failfast or when a selection repeats or contains another one; those run separately in the requested order.

Pytest records the last outcome of each test under the managed data root for both test and check. --last-failed runs only the selected tests that failed when they last ran; if none of them has a recorded failure, all of them run. It requires a selection or --tier. --failed-first runs those failures before the other selected tests. Without these options the record does not change which tests run or their result.

Tests run against a captured source snapshot. Directory selections must exist inside tests/<tier>/ in that snapshot and use ordinary pytest discovery. Most tests run with read-only sources and no network access in the pinned environment. Source-cache ownership and environment-publication metadata tests run on the host with real subordinate UID/GID mappings and the same locked Python dependencies, including when selected through a directory. They require the namespace support used by setup; unavailable mappings fail instead of skipping tests.

A selected run always executes. A complete successful ./fplinux test also satisfies the test portion of a later check on the same captured inputs and environment; it does not satisfy the source or kernel checks. Partial selections, --last-failed and sanitizer runs do not publish that result. Any changed input makes it a cache miss, and check --no-cache forces execution. Exit status is 0 for success, 1 for failures or unresolved names, 2 for invalid arguments and 5 when pytest finds no tests. Ctrl+C returns 130.

Pytest rejects unknown markers and configuration options. Each run reports skipped and expected-failure cases and the 20 slowest setup, call or teardown durations. Use those measurements before changing fixture lifetimes to optimize test time.

The command logs also contain JUnit XML for every pytest invocation, including every test’s outcome and total setup, call and teardown time. When tests run in parallel, the sum of their durations can exceed elapsed time.

Add --sanitize to a test selection to instrument native GCC builds, including LVGL, with AddressSanitizer and fatal UndefinedBehaviorSanitizer. Leak checking is disabled (detect_leaks=0). The command first checks fatal undefined-behavior reports in the pinned runtime. It retains complete reports with the command logs and treats findings as failures even when pytest expects a child to fail. ARM cross builds, freestanding code, static ABI probes and the MRE engine peer with its real address-space limit remain outside native instrumentation.

Sanitizer workloads use a 3 GiB memory cap, 2 GiB of temporary space, and budgets of 2700 seconds for host_tool and 900 seconds for host_process. Parallel native tests scale the memory and temporary-space limits with their worker count; sequential workloads retain their existing limits.

After you change a source file of an Alpine package under alpine/aports/, regenerate its checksums:

PC
./fplinux checksum fplinux-terminal

This is the only supported way to update them. Do not run abuild checksum in the checkout or edit digest lines by hand. The command uses local sources; prepare missing inputs with the setup command it reports.

./fplinux setup installs the repository’s commit-message hook. Messages use type(scope): subject, then a blank line and a body that explains the change:

Commit message
type(scope): subject
Explain what changed and why.

For example, the subject perf(ums9117): enable NEON and reduce codec overhead uses type perf and scope ums9117. The scope and the body are required. Accepted scopes are listed in commitlint.config.mjs.

Choose the scope of the component that owns the change. Shared controls and navigation use ui; application lifecycle, locking and phone session policy use session; GPU and display presentation use graphics; the shared host loading and reconnect workflow uses runtime. Use an application’s scope for a change confined to that application, such as fix(terminal): return to the parent options menu. Platform and phone scopes use their full project identifiers. A shared change keeps its owning scope when it also updates callers or tests.

Start with Your first application for the complete source-to-APK workflow. The screens and commands guide explains how to use the common controls, and layout and appearance covers one application across phone screen sizes.

Open the included API Demos application from the launcher to explore the shared UI controls. Its examples name the C functions they use; the installed headers in fplinux-ui-dev define the interfaces. Application packages depend on fplinux-ui and build against fplinux-ui-dev.

Follow the application-state contract when saving preferences, reporting storage errors and handling close decisions.

The documentation site lives in site/ and uses the exact Node.js and npm versions declared by the root package. Prepare only the site inputs and tools, then start a local preview that reloads as you edit:

PC
./fplinux setup --site
export PATH="$(./fplinux data-path)/site/node/bin:$PATH"
cd site
npm run dev

If you already restored a matching dependency snapshot, use ./fplinux setup --site --offline. Setup installs the pinned Linux x86-64 glibc Node.js runtime, imports locked registry archives into its npm cache and runs npm ci offline. It does not prepare the Alpine environment. The runtime remains available under site/node/bin in the working data directory for subsequent site commands.

Pages are in site/src/content/docs/. Run these commands from the checkout root before submitting a documentation change; the site command selects its own working directory:

PC
./fplinux site format
./fplinux site check
./fplinux site build
./fplinux site build-offline

Ultracite supplies the Oxlint, Astro ESLint, Prettier and Stylelint presets. format formats site code, styles, MDX and JSON; it preserves code examples and asset files. check checks formatting and runs type-aware linting on JavaScript and TypeScript with Oxlint and on Astro components with ESLint. It also checks accessibility and CSS including component styles, then runs Astro’s type checks. Unused rule-disable comments are errors. check also runs the site’s behavior tests. build renders the pages and checks internal links. MDX content is parsed during formatting and the build.

The site tools are separate from ./fplinux format and ./fplinux check; site format formats the whole site. The source gate checks maintained Markdown and repository-local links; run site check and site build for the site components, sidebar and page links. site build-offline exports the same pages to out/site-offline/ inside the selected working data directory. Open its index.html directly without a server. The export includes local assets and a simple word search; it does not use the hosted Pagefind search. Linux microSD system-card exports include this generated site as docs/ on the computer.