NAME

PAX::AppImage - application image builder and launcher packager

SYNOPSIS

use PAX::AppImage;

my $images = PAX::AppImage->new(root => '.pax/apps');
my $built = $images->build(
    entrypoint => 'bin/app.pl',
    name       => 'my-app',
    lib_dirs   => ['lib'],
    asset_dirs => ['share'],
);

my $image = $images->load(name => 'my-app');

DESCRIPTION

This module builds the persistent app-image layout that PAX uses for packaged applications which keep a named runtime directory instead of collapsing into a single standalone binary.

An app image contains the normalized image metadata, a compiled launcher, the Unix-socket location used by the app server, preload-module hints, and the embedded asset payload list. The launcher it generates can either talk to the running app server or fall back to launching the Perl entrypoint directly when the server socket is not available.

METHODS

new, build, load, path_for

Use new to choose the root that stores named app images, build to write or refresh one image, load to inspect saved metadata, and path_for to locate the image manifest on disk.

PURPOSE

This module keeps the app-image model in one place so the CLI, packaging code, and runtime server agree on how named packaged applications are laid out.

WHY IT EXISTS

PAX supports both single-binary standalone packaging and named application images. The application-image path needs launcher generation, embedded asset tracking, and preload discovery that do not belong in the generic CLI layer.

WHEN TO USE

Edit this file when a change affects named app-image layout, launcher source generation, preload discovery, embedded asset packaging, or the metadata contract written to image.json.

HOW TO USE

Call build with an entrypoint, optional application name, and any library or asset roots that should travel with the packaged application. The resulting metadata can then be loaded again by name through load or served through the app-server runtime.

WHAT USES IT

This module is used by the app-image build commands, the packaged app server, and the acceptance tests that cover named packaged applications with embedded assets.

EXAMPLES

Example 1:

perl -Ilib -MPAX::AppImage -e 'PAX::AppImage->new(root => q(.pax/apps))'

Load the module and construct an image manager from a source checkout.

Example 2:

prove -lv t/app_image.t

Run the focused regression coverage for named app-image packaging.