Skip to content

A graphical application is an Alpine aport with a program, a desktop entry and any translations or images it needs. Your first application contains a complete small recipe. The system archive format has a separate Packaging guide.

Distribute optional application APKs from the same FPLinux build as the system. Rebuild them together when the UI interface changes; an APK built against another system build has no binary compatibility guarantee.

Declare fplinux-ui as a runtime dependency and fplinux-ui-dev as a target build dependency. The latter provides the installed headers and pkg-config metadata. Use clang22 lld22 pkgconf as build tools, plus gettext for translation catalogs. Use the target compiler and flags supplied to the aport, not the PC compiler.

Before invoking pkg-config, set PKG_CONFIG_SYSROOT_DIR="$CBUILDROOT" and PKG_CONFIG_LIBDIR="$CBUILDROOT/usr/lib/pkgconfig:$CBUILDROOT/usr/share/pkgconfig". This selects the ARM libraries. Keep local library ordering in LOCAL_BUILD_DEPENDENCIES in scripts/fplinux_cli/alpine/registration.py; makedepends_host alone does not establish that ordering.

The shared CLI is compiled into applications, not exported by libfplinux-ui. Register CLI_SOURCES in SHARED_APORT_SOURCES, list fplinux-cli.c and fplinux-cli.h in the recipe, and compile fplinux-cli.c with the application. Follow the CLI contract before opening GUI resources.

Keep pkgrel=0 for project packages before the first release. Source changes invalidate build receipts; do not bump package versions for a local edit. Regenerate sha512sums with ./fplinux checksum <aport>, never by editing the hashes. External originals belong in the declared dependency system.

Choose the owner that actually needs the application. A phone’s [bundle].packages builds an optional APK beside that phone’s image. Platform bundle packages serve all targets of that platform. Rootfs package selection installs the package in the image instead. Do not select the same package as both an optional bundle APK and a rootfs package.

For a local tutorial, add its name to the selected phone’s existing [bundle] list, preserving the other entries. Also register its shared sources and local build dependencies. The selected package list supplies the bundle’s APK inventory; do not maintain a second list of APK filenames in release metadata.

Run ./fplinux build <target>. Its output directory contains apks/<package>.apk. The ordinary RAM ZIP omits these optional APKs; keep that distinction when distributing an application.

Use a distinct reverse-domain-style ID such as org.example.counter. It identifies the catalog entry, session connection, translations and private application state. The desktop filename is <ID>.desktop, and the program passes the same ID to fplinux_ui_open().

The program runs as the application user fplinux. It is not a root shell and must not open the display, evdev input or audio hardware directly. The runtime and session provide those services. Applications sharing this account are not isolated from each other’s files by a per-application sandbox.

Install the file under /usr/share/applications/ with mode 0644 and normal package ownership. The session refuses untrusted or writable catalog metadata. An ordinary application entry needs:

Key Meaning
Type=Application Identifies a launchable application
Name Default catalog name
Name[ru] Optional translated catalog name; other installed languages use their own code
Exec One absolute executable path, without arguments or field substitutions
X-FPLinux-Mode=integrated Start between the session’s bars; fullscreen requests the whole display
Icon Optional simple icon name, without a path or extension
Categories Optional semicolon-separated categories used to group the entry
X-FPLinux-FileExtensions Optional semicolon-terminated extension list, such as jar;; matching ignores ASCII letter case
NoDisplay=true Hide the catalog entry while allowing it to open registered file types
Hidden=true Disable both catalog launch and file handling

Install the executable with mode 0755. Set Exec to the executable path alone; this entry does not support a shell command or command-line arguments. The launcher display mode belongs to the system launcher.

Declare only formats that the application can actually read. The session uses extensions to select a handler; the handler must validate the file contents. An unrecognized file stays available for ordinary operations in Files. Several matching applications produce an Open with choice using their localized desktop names and icons.

An application requests an open with fplinux_ui_open_file(ui, absolute_path). The path must be valid UTF-8 and name a readable regular file without symbolic links. A nonzero return value is the request ID, not success: observe FPLINUX_UI_EVENT_DOCUMENT_RESULT for acceptance, cancellation or an error. Only one request can be pending for a UI. The request uses the existing application permissions and does not grant root access.

A handler installs a callback with fplinux_ui_set_document_handler(). Both a new process and an existing task receive the document through that callback; Exec stays unchanged and carries no file argument. The callback’s path is borrowed for its duration. Copy it before returning FPLINUX_UI_DOCUMENT_WAIT for asynchronous work or a decision dialog, then answer with fplinux_ui_document_reply().

Return FPLINUX_UI_DOCUMENT_ACCEPTED after accepting the file and preparing its screen. The UI runtime sends that result after the new frame is committed and synchronized; the previous application frame cannot acknowledge a new document. WAIT allows a decision dialog to appear without declaring success. Cancel preserves the handler’s existing work. After a successful open, ordinary foreground Close resumes the live initiating task; Home keeps its usual meaning.

FPLINUX_UI_DOCUMENT_RESTART_REQUIRED serves handlers whose execution engine cannot be reused in the same process. It enters the existing close handshake: Cancel keeps the task, while Ready closes it and starts the same installed handler with the pending document. A request can restart the handler once. Do not use this response to bypass a save or close decision.

Install PNG tiles as /usr/share/icons/hicolor/<N>x<N>/apps/<Icon>.png, with actual dimensions matching the directory. The catalog selects sizes for the current profile and can reduce a larger tile. Current profiles use tiles up to 60 pixels, so provide a sufficiently large source rather than assuming 48 pixels covers every screen.

Without an icon, the application remains accessible with the catalog’s generic image. Use a clear application-specific image; do not use a system action glyph or the FPLinux brand as its identity. Keep icon licenses with the package. See layout and appearance for images inside the application.

Use the shared optional-package workflow to transfer and install the matching APK. Open the program from the catalog. A binary started directly in a shell has not been started by the session manager and cannot establish a normal GUI session; --help remains usable from a shell.

Close the application before replacing or removing its package. A rebuilt APK can keep the same package version, so remove the installed package before installing its replacement. The catalog refreshes when installed entries change. Removing the package leaves its separately saved application data; storage lifetime follows Keeping data.

Use Logging for application output and Debugging for diagnostics. Installation success alone does not establish GUI behavior on a physical phone.