DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

pp(1)





NAME

       pp - Perl Packager


SYNOPSIS

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


EXAMPLES

       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
           % 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
                                       # (-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' with icon (Win32 only)
           % pp --gui --icon hello.ico -o out.exe hello

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


DESCRIPTION

       pp creates standalone executables from Perl programs, using the com-
       pressed 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 tech-
       niques), but makes up for it with better reliability, smaller exe-
       cutable 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

       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 lim-
       its 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
       interpeted as a file to read options from. Mixing ordinary options and
       @file options is possible. This is implemented using the Getopt::Argv-
       File 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 tar-
           get 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.

       -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 additonal run-time dependen-
           cies.

       -d, --dependent
           Reduce the executable size by not including a copy of perl inter-
           preter.  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 '...'"

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

       -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 spec-
           ify multiple such filters.

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

               % pp -f Bleach source.pl

           Users with Perl 5.8.1 and above may also try out the experimental
           byte-compiling filter, which will strip away all comments and
           indents:

               % pp -f Bytecode source.pl

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

       -h, --help
           Show basic usage information.

       -i, --icon=FILE
           Specify an icon file (in .ico, .exe or .dll format) for the exe-
           cutable. This option is ignored on non-MSWin32 platforms or when
           "-p" is specified.

       -N, --info=KEY=VAL
           Add additional information for the packed file, both in "META.yml"
           and in the executable header (if applicable).  The name/value pair
           is joined by "=".  You may specify "-N" multiple times, or use ";"
           to link several pairs.

           For Win32 executables, these special "KEY" names are recognized:

               Comments        CompanyName     FileDescription FileVersion
               InternalName    LegalCopyright  LegalTrademarks OriginalFilename
               ProductName     ProductVersion

       -I, --lib=DIR
           Add the given directory to the perl library file 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
           Filter included perl module(s) with a PAR::Filter subclass.  You
           may specify multiple such filters.

       -M, --module=MODULE
           Add the specified module into the package, along with its dependen-
           cies.  Also accepts filenames relative to the @INC path; i.e. "-M
           Module::ScanDeps" means the same thing as "-M Module/ScanDeps.pm".

           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 depen-
           dencies from -c or -x exclusively.

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

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

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

       -s, --sign
           Cryptographically sign the generated PAR or binary file using Mod-
           ule::Signature.

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

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


ENVIRONMENT

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


NOTES

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

       Stand-alone setup
               % 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:
               % pp -B -P -o packed.pl source.pl   # makes packed.exe
               # Now, deploy 'packed.exe' to target machine...
               $ perl packed.pl                    # run it

       Perl with core module installed:
               % pp -P -o packed.pl source.pl      # makes packed.exe
               # Now, deploy 'packed.pl' to target machine...
               $ perl packed.pl                    # run it

       Perl with PAR.pm and its dependencies installed:
               % 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

       Note that even if your perl was built with a shared library, the
       'Stand-alone setup' above will not need a separate perl5x.dll or
       libperl.so to function correctly.  Use "--dependent" if you are willing
       to ship the shared library with the application, which can signifi-
       cantly reduce the executable size.


SEE ALSO

       tkpp, par.pl, parl, perlcc

       PAR, PAR::Packer, Module::ScanDeps

       Getopt::Long, Getopt::ArgvFile


ACKNOWLEDGMENTS

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


AUTHORS

       Audrey Tang <cpan@audreyt.org>

       <http://par.perl.org/> is the official PAR website.  You can write to
       the mailing list at <par@perl.org>, or send an empty mail to <par-sub-
       scribe@perl.org> to participate in the discussion.

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


COPYRIGHT

       Copyright 2002, 2003, 2004, 2005, 2006 by Audrey Tang
       <cpan@audreyt.org>.

       Neither this program nor the associated parl program impose any licens-
       ing 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 result-
       ing 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 <http://www.perl.com/perl/misc/Artistic.html>

perl v5.8.8                       2006-05-30                             PP(1)

Man(1) output converted with man2html