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.

How Does PerlApp Work?

PerlApp first determines which modules and external files the converted script depends upon. The PerlApp program 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.

When requiring modules, be sure to use the --add option to list additional modules for PerlApp to traverse. Simple require statements (see below) do not contain enough information for PerlApp to load the necessary module(s).

    require $module;

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.

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 with verbose feedback:

    perlapp --verbose

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 executabl 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 requires, which then requires, 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.