NAME¶
pp - PAR Packager
SYNOPSIS¶
pp [
-ABCEFILMPTSVXacdefghilmnoprsvxz ]
[
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
# 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' 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
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¶
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 interpeted 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 additonal
run-time dependencies.
- -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 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
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, --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 "-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[=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.
Example:
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
dependencies. 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
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.
- --reusable
- EXPERIMENTAL
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 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.
When the program is run, its contents are extracted to a temporary
directory. On Unix systems, this is commonly
/tmp/par-USERNAME/cache-XXXXXXX. USERNAME is replaced by the
user running the program, and XXXXXXX is either a hash of the
executable or the value passed to the "-T" or
"--tempcache" switch.
- -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:
- 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 uses:
% 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.
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>, Steffen Mueller <smueller@cpan.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¶
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 <
http://www.perl.com/perl/misc/Artistic.html>