One-file programs with pperl --bundle - a tutorial#

A Perl program rarely travels alone. It needs an interpreter on the machine it runs on, and usually a handful of modules from CPAN or from your own lib/, installed where that interpreter looks. pperl --bundle removes both requirements: it writes one executable file that holds pperl, your program and every module the program loads that pperl does not already carry. Copy that file to another Linux machine and run it.

You are assumed to know how to run a Perl program and what use and require do. Nothing besides pperl is needed to make a bundle.

Making one#

Take a program that uses a module of its own:

hello.pl
lib/My/Greet.pm
# hello.pl
use strict;
use warnings;
use My::Greet 'greet';

my $who = shift // 'world';
print greet($who), "\n";

--bundle takes the name of the file to write after -o, the directories to search for modules after -I, as for a normal run, and the program last:

pperl --bundle -o hello -I lib hello.pl
# pperl: bundled hello.pl and 1 module(s) into hello (44364991 bytes)

./hello Ann
# Hello, Ann!

The result is an ordinary executable. It does not need pperl, lib/ or hello.pl any more.

What goes in#

pperl finds the modules by compiling the program. Everything that is loaded while it compiles is bundled: each use, and each require inside a BEGIN block, together with the modules those load in turn. So the BEGIN blocks and the import of every use run while the bundle is made; the program’s main code does not.

A module that the program loads only while it runs, with a require in its main code or a plugin name read from a configuration file, is not seen by that compile. Name it with --include, once per module:

pperl --bundle -o hello -I lib --include My::Plugin hello.pl

An included module is loaded without its import, and the modules it uses come along.

Modules that are built into pperl are never copied into a bundle: the pperl inside it has them already. A bundle of a program that uses nothing but built-in modules reports 0 module(s).

A program that does not compile produces no file. pperl prints the compiler’s messages and stops:

pperl: --bundle: broken.pl does not compile (the messages above)

Running it#

The bundle runs the program and nothing else. Every argument belongs to the program, including those that look like pperl’s own options: ./hello -v passes -v to hello.pl; it does not print pperl’s version.

$0 is the bundle as it was started: ./hello in the example above, or hello when it is found through PATH. So messages and usage lines name the command the user typed. This holds from the time the program runs. Code in a BEGIN block still sees the path the program has inside the bundle.

A file that runs anywhere#

By default the bundle is built from the pperl that makes it. A pperl linked against shared libraries makes a bundle that needs the same libraries on the machine where it runs.

--base names another pperl to build from. With a static pperl, the bundle is a static executable as well, and it runs on a Linux machine of the same architecture with nothing installed:

pperl --bundle -o hello --base /opt/pperl-static/pperl -I lib hello.pl

A static pperl leaves out the modules that need a C library at run time, Net::SSLeay and XML::LibXML among them (the list). The app loads the modules pperl carries from its base, so --bundle first has the base load each one the program uses, and refuses to build an app the base could not run:

pperl: --bundle: --base /opt/pperl-static/pperl cannot load modules the program uses:
  Net/SSLeay.pm: Can't locate Net/SSLeay.pm in @INC (you may need to install the Net::SSLeay module) (not supported by a static pperl, which cannot load libssl)

Such a program needs a dynamically linked base, and the libraries on the machine where the app runs.

--base may also name an existing bundle. The new bundle then holds pperl once, not twice.

Where the modules are while it runs#

Inside a bundle, the bundled modules behave like the modules built into pperl. require finds them right after pperl’s own and ahead of every directory on disk, so a copy of the same module installed on the machine is not loaded instead.

Their files are written on first need into a directory tree of the bundle’s own: the first of these locations that already holds the tree or can hold it.

  1. $XDG_CACHE_HOME/pperl

  2. $HOME/.cache/pperl

  3. $XDG_RUNTIME_DIR/pperl

  4. /tmp/pperl-<uid>, where <uid> is the numeric user id

Because the list does not end at the home directory, a bundle still runs as a service whose home is read-only, for instance under systemd’s ProtectHome=read-only.

%INC, __FILE__ and $Config{privlibexp} name paths in that tree:

/home/you/.cache/pperl/baa952461d7205b7/lib/My/Greet.pm

This also applies to the program itself: its __FILE__ and $FindBin::Bin point into the tree (.../lib/script/), not to the directory the bundle was started from. A data file or another script that sits beside the program is therefore not reachable through them, and --bundle does not copy such files: it bundles modules only. The same goes for the data files some distributions install beside their modules, the share directories that File::ShareDir looks up. Ship such files next to the bundle and find them from $^X, which inside a bundle is the bundle’s full path (see below). $0 would not do: started through PATH, it is the bare name hello.

use File::Basename 'dirname';
my $config = dirname($^X) . '/hello.conf';

Running Perl from inside a bundle#

Inside a bundle, $^X is the bundle, by its full path. That may be the only interpreter on the machine, but started as it is, it runs the program again. A program that starts a helper with $^X -MSome::Module -e ... would run itself with those arguments.

Set PPERL_BUNDLE_PERL=1 in the helper’s environment. The bundle then acts as pperl, and the bundled modules are still found:

local $ENV{PPERL_BUNDLE_PERL} = 1;
system $^X, '-MMy::Greet=greet', '-e', 'print greet("helper"), "\n"';

Limits#

  • Modules only. Data files, share directories and other scripts are not bundled; see above.

  • Loaded while compiling, or named. A module that only the running program loads is missing unless --include names it.

  • Modules from an @INC hook. A module that a code reference in @INC supplies has no file to copy. pperl reports it and leaves it out; the hook supplies it again when the bundle runs, if the hook is part of the program.

    pperl: --bundle: My/Hooked.pm was loaded through an @INC hook, not from a file; not bundled
    
  • No XS. A bundle holds what pperl can run: Perl code and the modules built into pperl. A distribution with a compiled part has to install under pperl first; see Installing CPAN modules.