pp - Perl Packager

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

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

    % pp hello                  # Pack 'hello' into executable 'a.out'
    % pp -o hello hello.pl      # Pack 'hello.pl' into executable 'hello'

    % 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 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 CW$0 (i.e. the filename used to invoke it). If nothing matches, it dies with the error CWCan'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

-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 CW/ inside the package with their original names. You may override this by appending the target filename after a CW;, like this:

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

You may specify CW-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 CW-A multiple times.

-B, --bundle

Bundle core modules in the resulting package. This option is enabled by default, except when CW-p or CW-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 CWperl -c inputfile to determine additonal run-time dependencies.

-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 CWperl -e '...'

-x, --execute

Run CWperl 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 specify 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 CW-p is specified.

-h, --help

Show basic usage information.

-i, --icon=FILE

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

-N, --info=KEY=VAL

Add additional information for the packed file, both in CWMETA.yml and in the executable header (if applicable). The name/value pair is joined by CW=. You may specify CW-N multiple times, or use CW; to link several pairs. For Win32 executables, these special CWKEY 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. CW-l ncurses means the same thing as CW-l libncurses.so or CW-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 dependencies. Also accepts filenames relative to the CW@INC path; i.e. CW-M Module::ScanDeps means the same thing as CW-M Module/ScanDeps.pm. If MODULE has an extension that is not CW.pm/CW.ix/CW.al, it will not be scanned for dependencies, and will be placed under CW/ instead of CW/lib/ inside the PAR file. This use is deprecated consider using the -a option instead. You may specify CW-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.

-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 Module::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 CW1 to CW3, CW3 being the most verbose. Defaults to CW1 if specified without an argument. Alternatively, -vv sets verbose level to CW2, and -vvv sets it to CW3.

-V, --version

Display the version number and copyrights of this program.

-z, --compress=NUMBER

Set zip compression level; NUMBER is an integer from CW0 to CW9, CW0 = no compression, CW9 = max compression. Defaults to CW6 if -z is not used.

PP_OPTS

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

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 CW-g flag.

Mattia Barbon for providing the CWmyldr binary loader code.

Jeff Goff for suggesting the name CWpp.

Autrijus Tang <autrijus@autrijus.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-subscribe@perl.org> to participate in the discussion.

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

Copyright 2002, 2003, 2004, 2005 by Autrijus Tang <autrijus@autrijus.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 <http://www.perl.com/perl/misc/Artistic.html>