PP(1)                  User Contributed Perl Documentation                 PP(1)

       pp - PAR Packager

       pp [ -ABCEFILMPTSVXacdefghilmnoprsuvxz ] [ parfile | scriptfile ]...

       Note: When running on Microsoft Windows, the a.out below will be replaced
       by a.exe instead.

           % pp hello.pl               # Pack 'hello.pl' into executable 'a.out'
           % pp -o hello hello.pl      # Pack 'hello.pl' into executable 'hello'
                                       # (or 'hello.exe' on Win32)

           % pp -o foo foo.pl bar.pl   # Pack 'foo.pl' and 'bar.pl' into 'foo'
           % ./foo                     # Run 'foo.pl' inside 'foo'
           % mv foo bar; ./bar         # Run 'bar.pl' inside 'foo'
           % mv bar baz; ./baz         # Error: Can't open perl script "baz"

           % pp -p file                # Creates a PAR file, 'a.par'
           % pp -o hello a.par         # Pack 'a.par' to executable 'hello'
           % pp -S -o hello file       # Combine the two steps above

           % pp -p -o out.par file     # Creates 'out.par' from 'file'
           % pp -B -p -o out.par file  # same as above, but bundles core modules
                                       # and removes any local paths from @INC
           % pp -P -o out.pl file      # Creates 'out.pl' from 'file'
           % pp -B -p -o out.pl file   # same as above, but bundles core modules
                                       # and removes any local paths from @INC
                                       # (-B is assumed when making executables)

           % pp -e "print 123"         # Pack a one-liner into 'a.out'
           % pp -p -e "print 123"      # Creates a PAR file 'a.par'
           % pp -P -e "print 123"      # Creates a perl script 'a.pl'

           % pp -c hello               # Check dependencies from "perl -c hello"
           % pp -x hello               # Check dependencies from "perl hello"
           % pp -n -x hello            # same as above, but skips static scanning

           % pp -I /foo hello          # Extra include paths
           % pp -M Foo::Bar hello      # Extra modules in the include path
           % pp -M abbrev.pl hello     # Extra libraries in the include path
           % pp -X Foo::Bar hello      # Exclude modules
           % pp -a data.txt hello      # Additional data files

           % pp -r hello               # Pack 'hello' into 'a.out', runs 'a.out'
           % pp -r hello a b c         # Pack 'hello' into 'a.out', runs 'a.out'
                                       # with arguments 'a b c'

           % pp hello --log=c          # Pack 'hello' into 'a.out', logs
                                       # messages into 'c'

           # Pack 'hello' into a console-less 'out.exe' (Win32 only)
           % pp --gui -o out.exe hello

           % pp @file hello.pl         # Pack 'hello.pl' but read _additional_
                                       # options from file 'file'

       pp creates standalone executables from Perl programs, using the
       compressed packager provided by PAR, and dependency detection heuristics
       offered by Module::ScanDeps.  Source files are compressed verbatim
       without compilation.

       You may think of pp as "perlcc that works without hassle". :-)

       A GUI interface is also available as the tkpp command.

       It does not provide the compilation-step acceleration provided by perlcc
       (however, see -f below for byte-compiled, source-hiding techniques), but
       makes up for it with better reliability, smaller executable size, and
       full retrieval of original source code.

       When a single input program is specified, the resulting executable will
       behave identically as that program.  However, when multiple programs are
       packaged, the produced executable will run the one that has the same
       basename as $0 (i.e. the filename used to invoke it).  If nothing
       matches, it dies with the error "Can't open perl script "$0"".

       Options are available in a short form and a long form.  For example, the
       three lines below are all equivalent:

           % pp -o output.exe input.pl
           % pp --output output.exe input.pl
           % pp --output=output.exe input.pl

       Since the command lines can become sufficiently long to reach the limits
       imposed by some shells, it is possible to have pp read some of its
       options from one or more text files. The basic usage is to just include
       an argument starting with an 'at' (@) sigil. This argument will be
       interpreted as a file to read options from. Mixing ordinary options and
       @file options is possible. This is implemented using the Getopt::ArgvFile
       module, so read its documentation for advanced usage.

       -a, --addfile=FILE|DIR
           Add an extra file into the package.  If the file is a directory,
           recursively add all files inside that directory, with links turned
           into actual files.

           By default, files are placed under "/" inside the package with their
           original names.  You may override this by appending the target
           filename after a ";", like this:

               % pp -a "old_filename.txt;new_filename.txt"
               % pp -a "old_dirname;new_dirname"

           You may specify "-a" multiple times.

       -A, --addlist=FILE
           Read a list of file/directory names from FILE, adding them into the
           package.  Each line in FILE is taken as an argument to -a above.

           You may specify "-A" multiple times.

       -B, --bundle
           Bundle core modules in the resulting package.  This option is enabled
           by default, except when "-p" or "-P" is specified.

           Since PAR version 0.953, this also strips any local paths from the
           list of module search paths @INC before running the contained script.

       -C, --clean
           Clean up temporary files extracted from the application at runtime.
           By default, these files are cached in the temporary directory; this
           allows the program to start up faster next time.

       -c, --compile
           Run "perl -c inputfile" to determine additional run-time

       -cd, --cachedeps=FILE
           Use FILE to cache detected dependencies. Creates FILE unless present.
           This will speed up the scanning process on subsequent runs.

       -d, --dependent
           Reduce the executable size by not including a copy of perl
           interpreter.  Executables built this way will need a separate
           perl5x.dll or libperl.so to function correctly.  This option is only
           available if perl is built as a shared library.

       -e, --eval=STRING
           Package a one-liner, much the same as "perl -e '...'"

       -E, --evalfeature=STRING
           Behaves just like "-e", except that it implicitly enables all
           optional features (in the main compilation unit) with Perl 5.10 and
           later.  See feature.

       -x, --execute
           Run "perl inputfile" to determine additional run-time dependencies.

           Using this option, pp may be able to detect the use of modules that
           can't be determined by static analysis of "inputfile". Examples are
           stuff loaded by run-time loaders like Module::Runtime or "plugin"
           loaders like Module::Loader. Note that which modules are detected
           depends on which parts of your program are exercised when running
           "inputfile". E.g. if your program immediately terminates when run as
           "perl inputfile" because it lacks mandatory arguments, then this
           option will probably have no effect. You may use --xargs to supply
           arguments in this case.

           If -x is given, splits the "STRING" using the function "shellwords"
           from Text::ParseWords and passes the result as @ARGV when running
           "perl inputfile".

       -X, --exclude=MODULE
           Exclude the given module from the dependency search path and from the
           package. If the given file is a zip or par or par executable, all the
           files in the given file (except MANIFEST, META.yml and script/*) will
           be excluded and the output file will "use" the given file at runtime.

       -f, --filter=FILTER
           Filter source script(s) with a PAR::Filter subclass.  You may specify
           multiple such filters.

           If you wish to hide the source code from casual prying, this will do:

               % pp -f Bleach source.pl

           If you are more serious about hiding your source code, you should
           have a look at Steve Hay's PAR::Filter::Crypto module. Make sure you
           understand the Filter::Crypto caveats!

       -g, --gui
           Build an executable that does not have a console window. This option
           is ignored on non-MSWin32 platforms or when "-p" is specified.

       -h, --help
           Show basic usage information.

       -I, --lib=DIR
           Add the given directory to the perl module search path.  May be
           specified multiple times.

       -l, --link=FILE|LIBRARY
           Add the given shared library (a.k.a. shared object or DLL) into the
           packed file.  Also accepts names under library paths; i.e.  "-l
           ncurses" means the same thing as "-l libncurses.so" or "-l
           /usr/local/lib/libncurses.so" in most Unixes.  May be specified
           multiple times.

       -L, --log=FILE
           Log the output of packaging to a file rather than to stdout.

       -F, --modfilter=FILTER[=REGEX],
           Filter included perl module(s) with a PAR::Filter subclass.  You may
           specify multiple such filters.

           By default, the PodStrip filter is applied.  In case that causes
           trouble, you can turn this off by setting the environment variable
           "PAR_VERBATIM" to 1.

           Since PAR 0.958, you can use an optional regular expression (REGEX
           above) to select the files in the archive which should be filtered.

             pp -o foo.exe -F Bleach=warnings\.pm$ foo.pl

           This creates a binary executable foo.exe from foo.pl packaging all
           files as usual except for files ending in "warnings.pm" which are
           filtered with PAR::Filter::Bleach.

       -M, --module=MODULE
           Add the specified module into the package, along with its

           The following variants may be used to add whole module namespaces:

           -M Foo::**
               Add every module in the "Foo" namespace except "Foo" itself, i.e.
               add "Foo::Bar", "Foo::Bar::Quux" etc up to any depth.

           -M Foo::*
               Add every module at level 1 in the "Foo" namespace, i.e.  add
               "Foo::Bar", but neither "Foo::Bar::Quux" nor "Foo".

           -M Foo::
               Shorthand for "-M Foo -M Foo:**": every module in the "Foo"
               namespace including "Foo" itself.

           Instead of a module name, MODULE may also be specified as a filename
           relative to the @INC path, i.e.  "-M Module/ScanDeps.pm" means the
           same thing as "-M Module::ScanDeps".

           If MODULE has an extension that is not ".pm"/".ix"/".al", it will not
           be scanned for dependencies, and will be placed under "/" instead of
           "/lib/" inside the PAR file.  This use is deprecated -- consider
           using the -a option instead.

           You may specify "-M" multiple times.

       -m, --multiarch
           Build a multi-architecture PAR file.  Implies -p.

       -n, --noscan
           Skip the default static scanning altogether, using run-time
           dependencies from -c or -x exclusively.

       -N, --namespace=NAMESPACE
           Add all modules in the namespace into the package, along with their
           dependencies. If "NAMESPACE" is something like "Foo::Bar" then this
           will add all modules "Foo/Bar/Quux.pm", "Foo/Bar/Fred/Barnie.pm" etc
           that can be located in your module search path. It mimics the
           behaviour of "plugin" loaders like Module::Loader.

           This is different from using "-M Foo::Bar::", as the latter insists
           on adding "Foo/Bar.pm" which might not exist in the above "plugin"

           You may specify "-N" multiple times.

       -o, --output=FILE
           File name for the final packaged executable.

       -p, --par
           Create PAR archives only; do not package to a standalone binary.

       -P, --perlscript
           Create stand-alone perl script; do not package to a standalone

       -r, --run
           Run the resulting packaged script after packaging it.


           Make the packaged executable reusable for running arbitrary, external
           Perl scripts as if they were part of the package:

             pp -o myapp --reusable someapp.pl
             ./myapp --par-options --reuse otherapp.pl

           The second line will run otherapp.pl instead of someapp.pl.

       -S, --save
           Do not delete generated PAR file after packaging.

       -s, --sign
           Cryptographically sign the generated PAR or binary file using

       -T, --tempcache
           Set the program unique part of the cache directory name that is used
           if the program is run without -C. If not set, a hash of the
           executable is used.

           When the program is run, its contents are extracted to a temporary
           directory.  On Unix systems, this is commonly
           /tmp/par-USER/cache-XXXXXXX.  USER is replaced by the name of the
           user running the program, but "spelled" in hex.  XXXXXXX is either a
           hash of the executable or the value passed to the "-T" or
           "--tempcache" switch.

       -u, --unicode
           Package Unicode support (essentially utf8_heavy.pl and everything
           below the directory unicore in your perl library).

           This option exists because it is impossible to detect using static
           analysis if your program needs Unicode support at runtime. (Note: If
           your program contains "use utf8" this does not imply it needs Unicode
           support. It merely says that your program is written in UTF-8.)

           If your packed program exits with an error message like

             Can't locate utf8_heavy.pl in @INC (@INC contains: ...)

           try to pack it with "-u" (or use "-x").

       -v, --verbose[=NUMBER]
           Increase verbosity of output; NUMBER is an integer from 1 to 3, 3
           being the most verbose.  Defaults to 1 if specified without an
           argument.  Alternatively, -vv sets verbose level to 2, and -vvv sets
           it to 3.

       -V, --version
           Display the version number and copyrights of this program.

       -z, --compress=NUMBER
           Set zip compression level; NUMBER is an integer from 0 to 9, 0 = no
           compression, 9 = max compression.  Defaults to 6 if -z is not used.

           Command-line options (switches).  Switches in this variable are taken
           as if they were on every pp command line.

       Here are some recipes showing how to utilize pp to bundle source.pl with
       all its dependencies, on target machines with different expected

       Stone-alone setup:
           To make a stand-alone executable, suitable for running on a machine
           that doesn't have perl installed:

               % pp -o packed.exe source.pl        # makes packed.exe
               # Now, deploy 'packed.exe' to target machine...
               $ packed.exe                        # run it

       Perl interpreter only, without core modules:
           To make a packed .pl file including core modules, suitable for
           running on a machine that has a perl interpreter, but where you want
           to be sure of the versions of the core modules that your program

               % pp -B -P -o packed.pl source.pl   # makes packed.pl
               # Now, deploy 'packed.pl' to target machine...
               $ perl packed.pl                    # run it

       Perl with core modules installed:
           To make a packed .pl file without core modules, relying on the target
           machine's perl interpreter and its core libraries.  This produces a
           significantly smaller file than the previous version:

               % pp -P -o packed.pl source.pl      # makes packed.pl
               # Now, deploy 'packed.pl' to target machine...
               $ perl packed.pl                    # run it

       Perl with PAR.pm and its dependencies installed:
           Make a separate archive and executable that uses the archive. This
           relies upon the perl interpreter and libraries on the target machine.

               % pp -p source.pl                   # makes source.par
               % echo "use PAR 'source.par';" > packed.pl;
               % cat source.pl >> packed.pl;       # makes packed.pl
               # Now, deploy 'source.par' and 'packed.pl' to target machine...
               $ perl packed.pl                    # run it, perl + core modules required

       Note that even if your perl was built with a shared library, the
       'Stand-alone executable' above will not need a separate perl5x.dll or
       libperl.so to function correctly.  But even in this case, the underlying
       system libraries such as libc must be compatible between the host and
       target machines.  Use "--dependent" if you are willing to ship the shared
       library with the application, which can significantly reduce the
       executable size.

       tkpp, par.pl, parl, perlcc

       PAR, PAR::Packer, Module::ScanDeps

       Getopt::Long, Getopt::ArgvFile

       Simon Cozens, Tom Christiansen and Edward Peschko for writing perlcc;
       this program try to mimic its interface as close as possible, and copied
       liberally from their code.

       Jan Dubois for writing the exetype.pl utility, which has been partially
       adapted into the "-g" flag.

       Mattia Barbon for providing the "myldr" binary loader code.

       Jeff Goff for suggesting the name pp.

       Audrey Tang <cpan@audreyt.org>, Steffen Mueller <smueller@cpan.org>
       Roderich Schupp <rschupp@cpan.org>

       You can write to the mailing list at <par@perl.org>, or send an empty
       mail to <par-subscribe@perl.org> to participate in the discussion.

       Please submit bug reports to <bug-par-packer@rt.cpan.org>.

       Copyright 2002-2009 by Audrey Tang <cpan@audreyt.org>.

       Neither this program nor the associated parl program impose any licensing
       restrictions on files generated by their execution, in accordance with
       the 8th article of the Artistic License:

           "Aggregation of this Package with a commercial distribution is
           always permitted provided that the use of this Package is embedded;
           that is, when no overt attempt is made to make this Package's
           interfaces visible to the end user of the commercial distribution.
           Such use shall not be construed as a distribution of this Package."

       Therefore, you are absolutely free to place any license on the resulting
       executable, as long as the packed 3rd-party libraries are also available
       under the Artistic License.

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

       See LICENSE.

perl v5.30.2                       2020-03-08                              PP(1)