Home on AppBundle Documentation & Implementation Details

Tooling Usage & Explanation

Sat, 12 Jul 2025 14:25:11 +0000

`pelf`

The pelf command is responsible for assembling an AppBundle by combining an ELF runtime, runtime information, static tools, and a compressed filesystem image.

Functionality

Purpose: Creates an AppBundle from an AppDir, embedding necessary metadata and tools.
Key Operations:
- Reads an AppDir, verifies that it contains an executable AppRun
- Copies the runtime to the output file
- Embeds runtime information (MessagePack format) in the .pbundle_runtime_info section of the output file
- If the runtime is a universal runtime (e.g: noEmbed edition), it puts a ZSTD-compressed tar archive of static tools (depending the chosen filesystem: e.g., dwarfs, squashfuse, unsquashfs) in the .pbundle_static_tools section of the output file.
- Compresses the AppDir into a DwarFS or SquashFS filesystem image and appends it to the output file
- Sets the AppBundle’s executable permissions and finalizes the output file.

Command-Line Usage

The pelf tool is can be invoked with the following flags:

AppBundle Runtime Logic Specification

Sat, 12 Jul 2025 12:15:35 +0000

This document describes how the AppBundle runtime operates, including how it reads its own information, extracts static tools, determines environment variables, and handles runtime flags.

Execution Flow

When an AppBundle is executed, the runtime performs the following steps:

Read Runtime Information:
- The runtime reads the .pbundle_runtime_info section from the ELF file, which contains CBOR-encoded metadata.
- This section includes:
  - AppBundleID: A unique identifier for the AppBundle. (e.g: “com.brave.Browser-xplshn-2025-05-19”. You’re not forced to follow this format, but if you do, you can create a dbin repository that countains your AppBundle by using our appstream-helper tool. $NAME-$MAINTAINER-$DATE or preferably: $APPSTREAM_ID-$MAINTAINER-$DATE, so that you don’t have to include an AppStream file within the AppDir for appstream-helper to get metadata from it)
  - PelfVersion: The version of the pelf tool used to create the AppBundle.
  - HostInfo: System information from uname -mrsp(v) of the build machine.
  - FilesystemType: Either “dwarfs” or “squashfs”.
  - Hash: A hash of the filesystem image for integrity verification.
  - DisableRandomWorkDir: A boolean indicating whether to use a fixed working directory.
  - MountOrExtract: A uint8 value (0–3) specifying the run behavior (see below).
- The runtime uses this information to configure its behavior and locate the filesystem image.
Extract Static Tools:

AppBundle File Format Specification

Sat, 12 Jul 2025 11:00:32 +0000

This document outlines the structure and composition of an AppBundle, a self-contained executable format designed to package applications with their dependencies for portable execution on Linux systems.

File Structure

An AppBundle is a single executable file that combines an ELF (Executable and Linkable Format) runtime with an appended filesystem image containing the application’s data. The structure is as follows:

ELF Runtime:
- The AppBundle begins with an ELF executable, identifiable by the magic bytes “AB” or optionally “AI” at the start of the file.
- This runtime is responsible for handling the execution logic, including mounting or extracting the filesystem image and setting up the environment.
Runtime Information Section (.pbundle_runtime_info):

AppBundleID Format Specification

Sat, 12 Jul 2025 11:00:32 +0000

An AppBundleID is required for every AppBundle to ensure proper functionality, such as generating the mountDir and enabling tools like appstream-helper to figure out info about the AppBundle. It can be non-compliant (i.e., not follow Type I, II, or III) if distribution via AppBundleHUB or dbin is not intended.

Supported Formats

Type I: Legacy Format

Structure: name-versionString-maintainer or name-date-maintainer
Examples: steam-v128.0.3-xplshn, steam-20250101-xplshn
Description: Consists of the application name, either a version or date, and the maintainer/repository identifier. Suitable for filenames on systems with restrictive character support (e.g., no #, :).
Use Case: Legacy distribution; preferred only for filenames

Type II: Modern Format without Date

Structure: name#repo[:version]
Examples: steam#xplshn:v128.0.3, steam#xplshn
Description: Includes the application name, repository/maintainer, and an optional version. Uses # to separate name and repository, with : for version.
Use Case: Most preferred format, in its short-form version

Type III: Modern Format with Optional Date

Structure: name#repo[:version][@date]
Examples: steam#xplshn:v128.0.3@20250101, steam#xplshn@20250101
Description: The most flexible format, including application name, repository/maintainer, optional version, and optional date. Uses #, :, and @ as separators.
Use Case: Most preferred format, as it contains the most complete data for appstream-helper to parse

Requirements and Usage

AppBundleHUB Distribution: For inclusion in AppBundleHUB or dbin repositories, the AppBundleID must adhere to Type I, II, or III, as these formats allow appstream-helper to parse metadata (name/appstreamID, version, maintainer, date) for automated repository indexing.
Recommendation: Type III is encouraged for the AppBundleID, as it is the most complete while Type I is recommended for AppBundle filenames on systems that may not support special characters like #, :, or @ used in Type II and Type III.

NOTEs

The program’s AppStreamID should be used as the Name in the AppBundleID if the AppBundle does not ship with an .xml appstream metainfo file in the top-level of its AppDir. This way appstream-helper can use scrapped Flathub data to automatically populate a .description, .icon, .screenshots, .rank & .version entry for the dbin repository index file
Type I, II & III are all parsable by appstream-helper