PerlApp - Overview

What is PerlApp?

The PerlApp utility converts a Perl program into an executable file. The executable can be freestanding (for use on systems where Perl is not installed), or dependent (for use on systems where Perl is installed). Freestanding programs built with PerlApp are larger in size than dependent applications because required Perl modules are included in the executable.

PerlApp is not a compiler. The Perl source code and the contents of embedded modules must be parsed and compiled when the executable is invoked. However, PerlApp makes it easier to distribute Perl scripts, as Perl (or a specific version and combination of Perl modules) does not need to be resident on the target system. PerlApp applications run as fast as the source Perl script.

The applications can also be deployed to systems that either do not have Perl or do not have the correct combination of modules installed. Additionally, PerlApp ensures that your code is always executed by a specific version of Perl, even if the user has a different Perl version already installed. As a side benefit, it can also be used for some degree of source code hiding.

PerlApp can create executables for operating systems and platforms other than the one it is run on.

How Does PerlApp Work?

PerlApp first determines which modules and external files the converted script depends upon. It starts this process by scanning the script source code. When occurrences of use, do, or require are found, PerlApp locates the corresponding module and parses the source of that module. PerlApp ends module parsing when all modules are located.

Use the --add option to specify additional modules for PerlApp to traverse. require statements that use variables do not contain enough information for PerlApp to load the necessary module(s) (see What PerlApp Includes in Freestanding Executables below).

PerlApp has built-in heuristics for major Perl modules that determine additional modules at runtime; for example, DBI, LWP, Tk. PerlApp determines the additional required modules so that they are available in freestanding applications.

PerlApp then determines which modules to include in the generated executable. Usually, all located modules are included. This also includes the dynamic object files (.so/.dll) and AutoLoader files (.al) that go with the located modules. If the --dependent option is used, only modules located under the directories given by the --lib option are included.

If the target platform for the executable is different from the one PerlApp is running on, the necessary Perl distribution and modules are fetched via PPM.

Finally, the executable is built with all the modules compressed (unless the --nocompress option is used) and included. When the executable runs, it attempts to load any use, do and require statements that are bundled inside of the application itself.

File Extraction

When the executable built with PerlApp runs, it extracts its dynamic object files in the /tmp/pdk directory. If the application is built using the --clean option, PerlApp also appends the process id to this directory name to avoid race conditions during cleanup. The directory location can be set using the TMPDIR environment variable. On Windows, the TEMP environment variable can be used to override the location. The location can also be hardcoded using the the --tmpdir command-line option.

Unless the --clean option is used, extracted files are left behind when the application terminates and reused by later incarnations of the same application (or by other PerlApp-created executables).

Freestanding Executables

When creating executables with PerlApp, the --freestanding switch is the default. Deploy the freestanding executable on a system with or without Perl installed.

The following example makes a freestanding executable file named myscript.exe from the Perl script myscript.pl with verbose feedback:

    perlapp --verbose myscript.pl

For freestanding executables, the @INC array contains the fully specified absolute path to the directory the executable is stored in. This is typically not the same as the current working directory.

What PerlApp Includes in Freestanding Executables

PerlApp packages the Perl program with all the required Perl modules and a modified Perl interpreter into the binary executable. When the executable is run, it searches for modules within itself before searching the file system. Building freestanding applications with PerlApp ensures that the executable is always executed by the desired version of Perl, even if the target system is running a different version.

PerlApp includes modules mentioned in require and use statements. For example, if the file A.pm requires B.pm, which then requires C.pm, PerlApp includes all of these packages. However, PerlApp does not include a module that is mentioned in a variable. For example, in a script with the following line:

    require $module;

PerlApp does not include the module identified by $module. To explicitly include this module, rebuild the PerlApp using the --add <list> command-line switch, where <list> is a semicolon-delimited list of the modules to explicitly include. PerlApp detects which DLLs are loaded by the *.pm files. However, if a DLL that has been loaded by a .pm file depends upon a second DLL, the second DLL is not bound into the executable. Otherwise, PerlApp includes numerous system DLLs.

Cross-platform Wrapping

PerlApp can create executables for non-native operating systems and platforms (i.e. an operating system or processor architecture other than the one PerlApp is currently running on). For example, PerlApp running on a Windows Vista machine can create a Mac OS X application, and vice-versa.

To do this, PerlApp needs to wrap the Perl code with an appropriate Perl interpreter and all required modules for the target platform. PerlApp will maintain a cached Perl installation for the foreign platform unless the --target-perl option is used to specify an existing installation. The PerlApp maintained installation will use the same build number as the ActivePerl used locally. PerlApp will use the locally configured PPM repositories to try to install all locally installed packages into the cached foreign Perl installation as well.

See the PerlApp Reference for more information on the --target, --target-install, and --target-perl options.