--- name: One-file programs --- ```{index} single: --bundle single: app bundle single: deployment; one executable file ``` # 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: ```text hello.pl lib/My/Greet.pm ``` ```perl # 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: ```bash 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. ```{index} single: --bundle; --include single: --bundle; which modules ``` ## 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: ```bash 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: ```text pperl: --bundle: broken.pl does not compile (the messages above) ``` ```{index} single: --bundle; arguments single: --bundle; $0 ``` ## 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. ```{index} single: --bundle; --base single: static build; --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: ```bash 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](../../getting_started.md#dynamic-and-static-binaries)). 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: ```text 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. ```{index} single: --bundle; library tree single: --bundle; __FILE__ single: --bundle; FindBin single: XDG_CACHE_HOME; --bundle single: ProtectHome ``` ## 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-`, where `` 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: ```text /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`. ```perl use File::Basename 'dirname'; my $config = dirname($^X) . '/hello.conf'; ``` ```{index} single: PPERL_BUNDLE_PERL single: --bundle; $^X ``` ## 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: ```perl local $ENV{PPERL_BUNDLE_PERL} = 1; system $^X, '-MMy::Greet=greet', '-e', 'print greet("helper"), "\n"'; ``` ```{index} single: --bundle; @INC hook single: --bundle; limits ``` ## 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. ```text 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](../cpan/index).