Export #

The ll-builder export command is used to export applications from the local build cache into a UAB (Universal Application Bundle) file. This is the recommended format. It can also export to the deprecated linglong layer file format.

Basic Usage #

ll-builder export [OPTIONS]

To view all available options and their detailed descriptions, run:

ll-builder export --help

Main Options #

• -f, --file FILE: Specify the path to the linglong.yaml configuration file (default: ./linglong.yaml). The directory containing linglong.yaml serves as the project's working directory.
• -o, --output FILE: Specify the output file path. For UAB, this is typically the full path or filename of the .uab file. For layers, this is the prefix for the output filenames.
• -z, --compressor X: Specify the compression algorithm. Supports lz4 (UAB default), lzma (layer default), zstd.
• --icon FILE: Specify an icon for the exported UAB file (UAB mode only, mutually exclusive with --layer).
• --loader FILE: Specify a custom loader for the exported UAB file (UAB mode only, mutually exclusive with --layer).
• --layer: (Deprecated) Export as layer file format instead of UAB (mutually exclusive with --icon, --loader).
• --no-develop: When exporting layer files, do not include the develop module.

Exporting UAB Files (Recommended) #

A UAB (Universal Application Bundle) file is a self-contained, offline-distributable file format that includes the content required to run the application. This is the recommended export format.

After execution, the ll-builder export command generates a .uab file in the project's working directory (or the path specified with -o), for example, <app_id>_<version>_<arch>.uab.

You can customize the UAB export using other options:

# Export UAB file specifying icon and output path
ll-builder export --icon assets/app.png -o dist/my-app-installer.uab

# Export UAB file using zstd compression
ll-builder export -z zstd -o my-app-zstd.uab

# Export UAB file specifying a custom loader
ll-builder export --loader /path/to/custom/loader -o my-app-custom-loader.uab

Exporting Layer Files (Deprecated) #

Note: Exporting layer file format is deprecated. Using the UAB format is recommended.

Export layer files using the command ll-builder export --layer. Other examples:

# Export layer format without the develop module
ll-builder export --layer --no-develop

# Export layer format and specify the output file prefix
ll-builder export --layer -o my-app
# (Generates my-app_binary.layer and my-app_develop.layer)

Exporting layer files generates the following files:

• *_binary.layer: Contains the basic files required for the application to run.
• *_develop.layer: (Optional) Contains files for development and debugging. This file is not generated if the --no-develop option is used.

Advanced Notes #

A UAB is a statically linked ELF executable intended to run on any Linux distribution. By default, exporting a UAB file uses the "bundle mode". Using the --loader parameter exports a UAB file in "custom loader mode".

Bundle Mode #

Bundle mode is primarily for distribution and supports self-running capabilities as much as possible. Users typically install offline-distributed applications via ll-cli install <UABfile>, which automatically completes the required runtime environment for the application. Once installed, the UAB application is used the same way as an application installed directly from a repository.

During export in bundle mode, the builder attempts to automatically resolve application dependencies and export necessary content (best effort). If you grant executable permissions to a bundle mode UAB file and run it, the application runs directly without being installed. In this case, the application still runs in an isolated container, but missing parts of the runtime environment will use the host system's environment directly, so the application is not guaranteed to run.

If application developers need to rely on the self-running feature, ensure the application includes the necessary runtime dependencies.

Custom Loader Mode #

A UAB file exported in custom loader mode contains only the application data and the provided custom loader. After the UAB file is unpacked and mounted, control is handed over to the custom loader, which runs outside the container environment. The environment variable LINGLONG_UAB_APPROOT stores the application's directory. The custom loader is responsible for initializing the application's required runtime environment, such as library search paths.

In this mode, the application needs to ensure its compatibility with the target system. The recommended practice is to build the application on the oldest supported system version and include all dependencies.