The PerlApp utility converts a Perl program into a standalone application.
This utility combines a Perl program, all of the required Perl modules and a
modified Perl interpreter into one binary unit. When the resulting application
is run, it searches for modules within itself before searching the filesystem.

Most commonly, PerlApp is invoked with the name of the Perl program that you
want converted as an argument. This produces a working application. Some of the
options described below make it possible to control which modules are included
and how the generated application behaves.

If PerlApp is invoked without arguments, the graphical interface is
displayed. If invoked with the --version or --help option, it will print
the corresponding message and exit.

List additional modules to include in the application. PerlApp also attempts
to include modules that the listed modules depend on. Multiple modules can be
separated by whitespace or a semicolon. This option can be repeated. For
example:

perlapp myscript.pl --add IO::Socket --add XML::Parser::Expat

...would include IO::Socket and XML::Parser in your application.

PerlApp uses built-in heuristics to determine any additional modules that may
be required at runtime. When building an executable, missing modules are
displayed as errors. In a few cases, however, the heuristics are used to
downgrade errors to warnings. PerlApp issues warnings for the following:

Windows executables built without Unix, Mac, VMS and OS/2 modules

Non-Windows executables built without Win32::* modules

All lowercase module names (because they are sometimes detected incorrectly by
PerlApp)

The bound file is extracted into the TEMP directory upon application start.
It is deleted when the application terminates. The extraction directory is
added to the PATH environment variable (as well as to the LD_LIBRARY_PATH
variable on Unix). It is also added to the front of @INC.

Specifies the access mode for the file when extracted either by the extract
option or the PerlApp::extract_bound_file() function. File permissions must
be specified as an octal number (0555 by default); PerlApp implicitly calls
chmod() after extracting the file to make sure it ends up with the right
permission bits. The mode= prefix is optional.

Note: Files bound using the extract suboption of --bind or extracted
via PerlApp::get_bound_file() are written to a a per-process temporary
directory and are automatically deleted when the process ends. This occurs
regardless of whether the --clean option is used.

Similar to --lib, but it searches for a MakeMaker-like blib directory
structure starting in libpath and working back up to five levels of '..'. If
found, it adds both the lib and the arch part of the blib structure to
the module search path.

Clean up object files that were extracted from the application at runtime. By
default, these files are cached in the temporary directory to allow the next
invocation of the application to start more quickly.

Create a debugging application. It connects to a remote debugger at startup.
The default host is '127.0.0.1' and the default port is ':2000'. Using a
single dash '-' selects the standard Perl command-line debugger from the local
Perl installation.

The special port name ':komodo' provides support for remote debugging with
the ActiveState Komodo IDE (version 1.2 and later,
http://www.ActiveState.com/Komodo). Komodo uses a custom version of
perl5db.pl. The path to this file must be made available to the application
either via the PERL5LIB environment variable (for dependent applications) or
via the --libPerlApp command-line option (for freestanding
applications). For example:

perlapp --lib /path-to/komodo-1.2/perl/site/lib ...

Refer to the Komodo Remote Debugging documentation for additional information.

Build an application that loads modules installed with Perl on the target
system. This option makes the application smaller, but it might not run
correctly if Perl and/or the required modules are not installed on the target
system.

Modules loaded from the directories specified with a --lib or --blib
option are still included. This allows you to selectively include only some
non-standard modules in your PerlApp generated application.

Use the 'dynamic DLL loader'. By default, PerlApp writes bundled DLLs to disk
in the tmp directory and then uses the operating system to load them into
the process. The default setting is --nodyndll.

The dynamic DLL loader bypasses some operating system mechanisms and loads the
libraries directly from memory without ever writing them to disk. However it
may not be fully compatible with all types of DLLs. It is also not yet
compatible with Windows 9x. Executables generated using the --dyndll option
do not run on Windows 95/98/Me.

Print this manpage and exit. If an optional topic is specified, only
sections whose headings include the topic word are printed. Option names as
topics must be specified without the leading dashes. Examples:

Associate icons with the application. The filename given must be an .ico,
.dll or .exe filename. For .dll and .exe files, the name can be
followed by a comma and the icon number. The first icon in the file is ,0,
the second ,1, etc. If the icon number is not provided, then ,0 is
assumed.

Separated multiple filenames with semicolons. This option can be repeated.

The arguments to this option is a sequence of name/value pairs that is used to
initialize the version information of the generated application. Name/value
pairs are separated by an equals sign, with each pair separated by a semicolon.
Valid names are as follows, and are case-insensitive:

The internal name of the file (e.g. a module name if the file is a dynamic-link
library). If the file has no internal name, this string should be the same as
the original filename, without an extension.

The original name of the file, not including a path. An application uses this
information to determine whether a file has been renamed by a user. The format
of the name depends on the filesystem for which the file was created.

The version of the product with which the file is distributed in the form
'W.X.Y.Z' where W, X, Y, and Z are numbers in the range 0-65535. X, Y, and Z
are optional and default to 0. Typically, the first number represents the major
version number, the second represents the minor version number, the third
represents the build number, and the last represents the private part number.

All values are taken as strings except FileVersion and ProductVersion,
which must be in the form 'W.X.Y.Z' (where W, X, Y, and Z are numbers in the
range 0-65535. X, Y, and Z are optional and default to 0).

Add to the path where PerlApp looks for modules to include in the
application. The libpath can contain multiple directories that are separated
in the same way as the PATH environment variable. This option can be
repeated.

PerlApp will automatically add architecture and version specific
subdirectories the same way the Perl -I option and the Perl lib pragma
do.

The content of the PERL5LIB environment variable is automatically added via
an implicit --lib option.

Do not try to compress embedded modules and libraries. Compression produces a
smaller application, but might slow down execution because the script and
modules must be decompressed before they can be parsed.

Specifies that the generated application does not use a runtime library
directory. This is different from not specifying the --runlib option because
the default runlib location is the directory where the application is stored.

Specifies the location of the runtime library directory. This directory is
added to @INC and the PATH environment variable at runtime. The runlib
directory should normally be a relative path. It is resolved at runtime
relative to the location of the executable and not relative to the current
working directory. The default value for this option is ".".

The --norunlib option can be used to specify that no runlib directory should
be used.

The runlib directory is also used to locate shared library files specified
using the --use option.

The fully qualified path to the runlib directory is stored in the
$PerlApp::RUNLIB variable.

Tells PerlApp to scan scriptname for additional module dependencies.
scriptname itself is not included in the generated executable. Separate
multiple scriptnames with a semicolon. The option can be repeated.

This option is being used to create a shared library that can be referenced by
other applications with the --use option.

The --shared option must be used to grant other programs access to modules
bundled in the current executable.

Specifies the sharing mode for the generated executable. Valid values for
mode are "none", "private" or "public". The default, "none", prevents other
applications from accessing modules bundled in this executable.

The "private" mode allows applications built with the same PDK license to
access any bundled modules. This means that part of the license serial number
is encoded in the generated executable. The accessing application must then
also be built using the "private" sharing mode to enable serial number
matching.

Shared libraries built with the "public" sharing mode can be accessed by all
executables built by the PDK without restriction.

Specify an alternate location for the /tmp directory. This can be used in
scenarios where /tmp is not writeable (e.g. for some virtual web servers
hosted by ISPs). This option should only be used with an absolute pathname.

Note: PerlApp does not automatically create this directory; it must exist
before the application is run.

Prevents modules from being included in the executable. Prerequisites for these
modules are excluded unless they are also referenced in other parts of the
application.

Multiple modules can be separated by whitespace or a semicolon. This option can
be repeated.

If a command explicitly adds and removes modules at the same time, modules
added with --add will not be removed by --trim.

The --trim option supports the following wildcard notations: --trim
Module::* excludes Module::Foo, but neither Module itself nor
Module::Foo::Bar. --trim Module::** excludes Module::Foo and
Module::Foo::Bar, but not Module. --trim Module:: works the same as
--trim Module;Module::**, excluding all of Module, Module::Foo and
Module::Foo::Bar. Note that you may have to quote the * character to
prevent wildcard expansion by your command shell.

This prevents including core modules that are loaded implicitly by Perl on
certain syntactic constructs. The following modules belong to this category and
are always included unless this option is used:

Errno
File::Glob
PerlIO
PerlIO::scalar
attributes

You can also use the --trim option to exclude these modules on a one-by-one
basis.

Specifies shared library file containing additional modules. Modules found in a
shared library will are not included in the generated executable, reducing its
size.

The libname argument can be specified using a full path name. At runtime,
the library is located in the runtime library directory specified by the
--runlib option. If the library cannot be found, the executable will not
run.

If the shared library has been built as a "private" shared library, the
application that is using it must be built with the "private" --shared
option too.

Separte multiple libnames with semicolons. The option can be repeated.

Don't include perl56.dll or perl58.dll in the generated application. This
option makes the application smaller, but it will not run correctly unless the
perl5?.dll corresponding to your ActivePerl version is present on the target
system. The PDK license allows you to redistribute the perl5?.dll together
with your application. It should be installed on the target system in the same
directory as your application and not be put into a system directory on the
PATH.

Writes the content of a bound file to the filesystem. The file is created in a
temporary directory and is automatically deleted when the application
terminates. The function returns the full filename of the temporary file
created:

Returns the content of files included in the executable with the --bind
command-line option. Returns the whole file as a single string in scalar
context or separate lines in list context, in which case lines are always split
on newline (i.e. $/ is not considered).

The $PerlApp::PERL5LIB variable contains the value of the PERL5LIB
environment variable. If that does not exist, it contains the value of the
PERLLIB environment variable. If that one does not exists either,
$PerlApp::PERL5LIB is undef.

When the application built with PerlApp runs, it extracts its dynamic object
files in the pdk-username subdirectory of the temporary directory. The
temporary directory is located using the TEMP environment variable. It is
also possible to hardcode the location with the --tmpdir command-line
option.

On Unix, dynamic object files are extracted in the /tmp/pdk-username
directory. The temporary directory location can be overridden with the
TMPDIR environment variable.

If the application was built using the --clean option, PerlApp also appends
the process id to the username when creating the temporary directory (e.g.,
pdk-username-1234). This avoids race conditions during cleanup. Unless the
--clean option is used, extracted files are left behind when the application
terminates. They are reused by later incarnations of the same application (or
by other PDK-created executables).

PerlApp uses the PERLAPP_OPT environment variable to set default
command-line options. PerlApp treats these options as if they were specified
at the beginning of every PerlApp command line. Note: Perl must be in your
PATH if you want to use PERLAPP_OPT.

All directories specified in the PERL5LIB environment variable are treated
as if they had been specified with the --lib command-line option. Therefore
modules located in PERL5LIB directories will be included even in dependent
applications. If PERL5LIB is not set, PerlApp will use the value of
PERLLIB instead (just like regular Perl).

PerlApp will pipe the output of perlapp --help through the program
specified in the PAGER environment variable if STDOUT is a terminal.

In general, PerlApp cannot determine whether a module is absolutely needed
at runtime. For the error message above, looking at the source code of the
File::Temp module reveals that the VMS::Stdio module is only used on the VMS
platform:

require VMS::Stdio if $^O eq 'VMS';

It is therefore safe to ignore the error. PerlApp includes a number of
platform-specific rules telling it that certain dependencies are likely not
required. In those cases, the error messages are downgraded to a warning. In
all other cases it is the responsibility of the user to verify if the module is
needed or not. PerlApp still generates a valid executable, even while this
error message is displayed.

It is possible to suppress the error/warning message by explicitly excluding
the missing module with the --trim option:

Windows uses case-insensitive filesystems. It is often possible to misspell a
module name and still have Perl load the correct file. For example:

use Win32::Eventlog;

...loads the Win32::EventLog module, but it does not import any
symbols from it: Perl tries to call the
Win32::Eventlog->import() method, which doesn't exist, and
gives up. PerlApp on Windows generates an error when
the file name and the module name cases don't match:

It is important to either correct the wrong spelling in the program or rename
the file on disk to the correct name as PerlApp internally uses a
case-sensitive file name lookup and otherwise does not load the file at
runtime.

PerlApp sometimes needs to include additional module-specific data files.
When the module is installed both into the standard Perl library tree and into
an additional location added either via the --lib option or PERL5LIB
environment variable, the data file will be found twice (but only included
once). The same problem can happen when the standard Perl library directories
are specified again using --lib or PERL5LIB. The error message should
display both the original and the duplicate filenames:

The first thing PerlApp needs to do is to determine which modules and
external files the converted script depends upon. The PerlApp program starts
out by scanning the source code of the script. When it finds occurrences of
use, do or require, it tries to locate the corresponding module and
then parse the source of that module. This continues as long as PerlApp
finds new modules to examine.

PerlApp does not try to run the script. It will not automatically determine
which modules might be loaded by a statement such as:

require $module;

In cases like this, try listing additional modules to traverse with the
--add option.

The PerlApp program has some built-in heuristics for major Perl modules that
determine additional modules at runtime, like DBI, LWP, Tk. PerlApp
anticipates which additional modules are required so that they are available in
freestanding executables.

PerlApp then decides which modules to include in the generated application.
Normally, 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 application is built with all the modules compressed (unless the
--nocompress option is used) and included. When the application runs
arranges for any use, do and require statements to look for and
extract the corresponding modules in itself.

Because building shared versions of libperl is not currently standard practice
on Unix, PerlApp must include a complete perl interpreter in the executable.
Future versions of ActivePerl will include a shared version of libperl so
that dependent executables can be smaller.

It will always have the value: perl. The $^X is a special variable that
normally contains the filename of the Perl interpreter that is executing the
script. It is sometimes used in calls to system or exec to invoke perl from
within the script.