NAME
pp - Perl Packager
SYNOPSIS
% 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, 'file.par'
% pp -S -o hello file # Creates a PAR file, 'file.par',
# then packages it to executable 'hello'
% 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
# (-B is assumed when making executables)
% pp -e 'print q//' # Pack a one-liner into 'a.out'
% pp -c -e 'print q//' # Creates a PAR file 'a.out.par'
% pp -I /foo hello # Extra paths (notice space after -I)
% pp -M Foo::Bar hello # Extra modules (notice space after -M)
% pp -X Foo::Bar hello # Exclude modules (notice space after -X)
% 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'
DESCRIPTION
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". :-)
It does not provide the compilation-step acceleration provided by perlcc (although a ByteLoader variant of pp is entirely possible), but makes up for it with better reliability, smaller executable size, and full retrieval of original source code.
If 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"
.
On Microsoft Windows platforms, a.exe is used instead of a.out as the default executable name.
OPTIONS
- -M module names
-
Adds the given modules to the dependency search patch and to the binary.
- -X module names
-
Excludes the given modules to the dependency search patch and to the binary.
- -I library directories
-
Adds the given directories to the perl library file search path.
- -o output file name
-
Specifies the file name for the final packaged executable.
- -p PAR file name
-
Create PAR archives only; do not package to a standalone binary.
- -e perl code
-
Package a one-liner, much the same as
perl -e '...'
- -S
-
Do not delete generated PAR file after packaging.
- -v
-
Increase verbosity of output; can be repeated for more verbose output.
- -r
-
Run the resulting packaged script after packaging it.
- -log
-
Log the output of packaging to a file rather than to stdout.
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 source.pl # makes source.par % par.pl -B -Opacked.pl source.par # makes packed.pl # Now, deploy 'packed.pl' to target machine... $ perl packed.pl # run it
- Perl with core module installed:
-
% pp -p source.pl # makes source.par % par.pl -b -Opacked.pl source.par # makes packed.pl # 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 if your perl was built with a shared library, the 'Stand-alone setup' above will still need a separate perl5x.dll or libperl.so to function correctly. Patches to include a copy of libperl with the executable are most welcome.
SEE ALSO
PAR, Module::ScanDeps, par.pl, parl, perlcc
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.
Mattia Barbon for providing the myldr
binary loader code.
Jeff Goff for suggesting the name pp
.
AUTHORS
Autrijus Tang <autrijus@autrijus.org>
PAR has a mailing list, <par@perl.org>, that you can write to; send an empty mail to <par-subscribe@perl.org> to join the list and participate in the discussion.
Please send bug reports to <bug-par@rt.cpan.org>.
COPYRIGHT
Copyright 2002, 2003 by Autrijus Tang <autrijus@autrijus.org>.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.