ActiveState Docs

PDK 6.0 Documentation

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 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.

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).

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 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.