1pp(3)                 User Contributed Perl Documentation                pp(3)
2
3
4

NAME

6       pp - PAR Packager
7

SYNOPSIS

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

EXAMPLES

12       Note: When running on Microsoft Windows, the a.out below will be
13       replaced by a.exe instead.
14
15           % pp hello.pl               # Pack 'hello.pl' into executable 'a.out'
16           % pp -o hello hello.pl      # Pack 'hello.pl' into executable 'hello'
17                                       # (or 'hello.exe' on Win32)
18
19           % pp -o foo foo.pl bar.pl   # Pack 'foo.pl' and 'bar.pl' into 'foo'
20           % ./foo                     # Run 'foo.pl' inside 'foo'
21           % mv foo bar; ./bar         # Run 'bar.pl' inside 'foo'
22           % mv bar baz; ./baz         # Error: Can't open perl script "baz"
23
24           % pp -p file                # Creates a PAR file, 'a.par'
25           % pp -o hello a.par         # Pack 'a.par' to executable 'hello'
26           % pp -S -o hello file       # Combine the two steps above
27
28           % pp -p -o out.par file     # Creates 'out.par' from 'file'
29           % pp -B -p -o out.par file  # same as above, but bundles core modules
30                                       # and removes any local paths from @INC
31           % pp -P -o out.pl file      # Creates 'out.pl' from 'file'
32           % pp -B -p -o out.pl file   # same as above, but bundles core modules
33                                       # and removes any local paths from @INC
34                                       # (-B is assumed when making executables)
35
36           % pp -e "print 123"         # Pack a one-liner into 'a.out'
37           % pp -p -e "print 123"      # Creates a PAR file 'a.par'
38           % pp -P -e "print 123"      # Creates a perl script 'a.pl'
39
40           % pp -c hello               # Check dependencies from "perl -c hello"
41           % pp -x hello               # Check dependencies from "perl hello"
42           % pp -n -x hello            # same as above, but skips static scanning
43
44           % pp -I /foo hello          # Extra include paths
45           % pp -M Foo::Bar hello      # Extra modules in the include path
46           % pp -M abbrev.pl hello     # Extra libraries in the include path
47           % pp -X Foo::Bar hello      # Exclude modules
48           % pp -a data.txt hello      # Additional data files
49
50           % pp -r hello               # Pack 'hello' into 'a.out', runs 'a.out'
51           % pp -r hello a b c         # Pack 'hello' into 'a.out', runs 'a.out'
52                                       # with arguments 'a b c'
53
54           % pp hello --log=c          # Pack 'hello' into 'a.out', logs
55                                       # messages into 'c'
56
57           # Pack 'hello' into a console-less 'out.exe' (Win32 only)
58           % pp --gui -o out.exe hello
59
60           % pp @file hello.pl         # Pack 'hello.pl' but read _additional_
61                                       # options from file 'file'
62

DESCRIPTION

64       pp creates standalone executables from Perl programs, using the
65       compressed packager provided by PAR, and dependency detection
66       heuristics offered by Module::ScanDeps.  Source files are compressed
67       verbatim without compilation.
68
69       You may think of pp as "perlcc that works without hassle". :-)
70
71       A GUI interface is also available as the tkpp command.
72
73       It does not provide the compilation-step acceleration provided by
74       perlcc (however, see -f below for byte-compiled, source-hiding
75       techniques), but makes up for it with better reliability, smaller
76       executable size, and full retrieval of original source code.
77
78       When a single input program is specified, the resulting executable will
79       behave identically as that program.  However, when multiple programs
80       are packaged, the produced executable will run the one that has the
81       same basename as $0 (i.e. the filename used to invoke it).  If nothing
82       matches, it dies with the error "Can't open perl script "$0"".
83

OPTIONS

85       Options are available in a short form and a long form.  For example,
86       the three lines below are all equivalent:
87
88           % pp -o output.exe input.pl
89           % pp --output output.exe input.pl
90           % pp --output=output.exe input.pl
91
92       Since the command lines can become sufficiently long to reach the
93       limits imposed by some shells, it is possible to have pp read some of
94       its options from one or more text files. The basic usage is to just
95       include an argument starting with an 'at' (@) sigil. This argument will
96       be interpreted as a file to read options from. Mixing ordinary options
97       and @file options is possible. This is implemented using the
98       Getopt::ArgvFile module, so read its documentation for advanced usage.
99
100       -a, --addfile=FILE|DIR
101           Add an extra file into the package.  If the file is a directory,
102           recursively add all files inside that directory, with links turned
103           into actual files.
104
105           By default, files are placed under "/" inside the package with
106           their original names.  You may override this by appending the
107           target filename after a ";", like this:
108
109               % pp -a "old_filename.txt;new_filename.txt"
110               % pp -a "old_dirname;new_dirname"
111
112           You may specify "-a" multiple times.
113
114       -A, --addlist=FILE
115           Read a list of file/directory names from FILE, adding them into the
116           package.  Each line in FILE is taken as an argument to -a above.
117
118           You may specify "-A" multiple times.
119
120       -B, --bundle
121           Bundle core modules in the resulting package.  This option is
122           enabled by default, except when "-p" or "-P" is specified.
123
124           Since PAR version 0.953, this also strips any local paths from the
125           list of module search paths @INC before running the contained
126           script.
127
128       -C, --clean
129           Clean up temporary files extracted from the application at runtime.
130           By default, these files are cached in the temporary directory; this
131           allows the program to start up faster next time.
132
133       -c, --compile
134           Run "perl -c inputfile" to determine additional run-time
135           dependencies.
136
137       -cd, --cachedeps=FILE
138           Use FILE to cache detected dependencies. Creates FILE unless
139           present. This will speed up the scanning process on subsequent
140           runs.
141
142       -d, --dependent
143           Reduce the executable size by not including a copy of perl
144           interpreter.  Executables built this way will need a separate
145           perl5x.dll or libperl.so to function correctly.  This option is
146           only available if perl is built as a shared library.
147
148       -e, --eval=STRING
149           Package a one-liner, much the same as "perl -e '...'"
150
151       -E, --evalfeature=STRING
152           Behaves just like "-e", except that it implicitly enables all
153           optional features (in the main compilation unit) with Perl 5.10 and
154           later.  See feature.
155
156       -x, --execute
157           Run "perl inputfile" to determine additional run-time dependencies.
158
159           Using this option, pp may be able to detect the use of modules that
160           can't be determined by static analysis of "inputfile". Examples are
161           stuff loaded by run-time loaders like Module::Runtime or "plugin"
162           loaders like Module::Loader. Note that which modules are detected
163           depends on which parts of your program are exercised when running
164           "inputfile". E.g. if your program immediately terminates when run
165           as "perl inputfile" because it lacks mandatory arguments, then this
166           option will probably have no effect. You may use --xargs to supply
167           arguments in this case.
168
169       --xargs=STRING
170           If -x is given, splits the "STRING" using the function "shellwords"
171           from Text::ParseWords and passes the result as @ARGV when running
172           "perl inputfile".
173
174       -X, --exclude=MODULE
175           Exclude the given module from the dependency search path and from
176           the package. If the given file is a zip or par or par executable,
177           all the files in the given file (except MANIFEST, META.yml and
178           script/*) will be excluded and the output file will "use" the given
179           file at runtime.
180
181       -f, --filter=FILTER
182           Filter source script(s) with a PAR::Filter subclass.  You may
183           specify multiple such filters.
184
185           If you wish to hide the source code from casual prying, this will
186           do:
187
188               % pp -f Bleach source.pl
189
190           If you are more serious about hiding your source code, you should
191           have a look at Steve Hay's PAR::Filter::Crypto module. Make sure
192           you understand the Filter::Crypto caveats!
193
194       -g, --gui
195           Build an executable that does not have a console window. This
196           option is ignored on non-MSWin32 platforms or when "-p" is
197           specified.
198
199       -h, --help
200           Show basic usage information.
201
202       -I, --lib=DIR
203           Add the given directory to the perl module search path.  May be
204           specified multiple times.
205
206       -l, --link=FILE|LIBRARY
207           Add the given shared library (a.k.a. shared object or DLL) into the
208           packed file.  Also accepts names under library paths; i.e.  "-l
209           ncurses" means the same thing as "-l libncurses.so" or "-l
210           /usr/local/lib/libncurses.so" in most Unixes.  May be specified
211           multiple times.
212
213       -L, --log=FILE
214           Log the output of packaging to a file rather than to stdout.
215
216       -F, --modfilter=FILTER[=REGEX],
217           Filter included perl module(s) with a PAR::Filter subclass.  You
218           may specify multiple such filters.
219
220           By default, the PodStrip filter is applied.  In case that causes
221           trouble, you can turn this off by setting the environment variable
222           "PAR_VERBATIM" to 1.
223
224           Since PAR 0.958, you can use an optional regular expression (REGEX
225           above) to select the files in the archive which should be filtered.
226           Example:
227
228             pp -o foo.exe -F Bleach=warnings\.pm$ foo.pl
229
230           This creates a binary executable foo.exe from foo.pl packaging all
231           files as usual except for files ending in "warnings.pm" which are
232           filtered with PAR::Filter::Bleach.
233
234       -M, --module=MODULE
235           Add the specified module into the package, along with its
236           dependencies.
237
238           The following variants may be used to add whole module namespaces:
239
240           -M Foo::**
241               Add every module in the "Foo" namespace except "Foo" itself,
242               i.e.  add "Foo::Bar", "Foo::Bar::Quux" etc up to any depth.
243
244           -M Foo::*
245               Add every module at level 1 in the "Foo" namespace, i.e.  add
246               "Foo::Bar", but neither "Foo::Bar::Quux" nor "Foo".
247
248           -M Foo::
249               Shorthand for "-M Foo -M Foo:**": every module in the "Foo"
250               namespace including "Foo" itself.
251
252           Instead of a module name, MODULE may also be specified as a
253           filename relative to the @INC path, i.e.  "-M Module/ScanDeps.pm"
254           means the same thing as "-M Module::ScanDeps".
255
256           If MODULE has an extension that is not ".pm"/".ix"/".al", it will
257           not be scanned for dependencies, and will be placed under "/"
258           instead of "/lib/" inside the PAR file.  This use is deprecated --
259           consider using the -a option instead.
260
261           You may specify "-M" multiple times.
262
263       -m, --multiarch
264           Build a multi-architecture PAR file.  Implies -p.
265
266       -n, --noscan
267           Skip the default static scanning altogether, using run-time
268           dependencies from -c or -x exclusively.
269
270       -N, --namespace=NAMESPACE
271           Add all modules in the namespace into the package, along with their
272           dependencies. If "NAMESPACE" is something like "Foo::Bar" then this
273           will add all modules "Foo/Bar/Quux.pm", "Foo/Bar/Fred/Barnie.pm"
274           etc that can be located in your module search path. It mimics the
275           behaviour of "plugin" loaders like Module::Loader.
276
277           This is different from using "-M Foo::Bar::", as the latter insists
278           on adding "Foo/Bar.pm" which might not exist in the above "plugin"
279           scenario.
280
281           You may specify "-N" multiple times.
282
283       -o, --output=FILE
284           File name for the final packaged executable.
285
286       -p, --par
287           Create PAR archives only; do not package to a standalone binary.
288
289       -P, --perlscript
290           Create stand-alone perl script; do not package to a standalone
291           binary.
292
293       -r, --run
294           Run the resulting packaged script after packaging it.
295
296       --reusable
297           EXPERIMENTAL
298
299           Make the packaged executable reusable for running arbitrary,
300           external Perl scripts as if they were part of the package:
301
302             pp -o myapp --reusable someapp.pl
303             ./myapp --par-options --reuse otherapp.pl
304
305           The second line will run otherapp.pl instead of someapp.pl.
306
307       -S, --save
308           Do not delete generated PAR file after packaging.
309
310       -s, --sign
311           Cryptographically sign the generated PAR or binary file using
312           Module::Signature.
313
314       -T, --tempcache
315           Set the program unique part of the cache directory name that is
316           used if the program is run without -C. If not set, a hash of the
317           executable is used.
318
319           When the program is run, its contents are extracted to a temporary
320           directory.  On Unix systems, this is commonly
321           /tmp/par-USER/cache-XXXXXXX.  USER is replaced by the name of the
322           user running the program, but "spelled" in hex.  XXXXXXX is either
323           a hash of the executable or the value passed to the "-T" or
324           "--tempcache" switch.
325
326       -u, --unicode
327           Note: This option is ignored for Perl 5.32 and above.
328
329           Package Unicode support (essentially utf8_heavy.pl and everything
330           below the directory unicore in your perl library).
331
332           This option exists because it is impossible to detect using static
333           analysis whether your program needs Unicode support at runtime.
334           (Note: If your program contains "use utf8" this does not imply it
335           needs Unicode support. It merely says that your program source is
336           written in UTF-8.)
337
338           If your packed program exits with an error message like
339
340             Can't locate utf8_heavy.pl in @INC (@INC contains: ...)
341
342           try to pack it with "-u" (or use "-x").
343
344       -v, --verbose[=NUMBER]
345           Increase verbosity of output; NUMBER is an integer from 1 to 3, 3
346           being the most verbose.  Defaults to 1 if specified without an
347           argument.  Alternatively, -vv sets verbose level to 2, and -vvv
348           sets it to 3.
349
350       -V, --version
351           Display the version number and copyrights of this program.
352
353       -z, --compress=NUMBER
354           Set zip compression level; NUMBER is an integer from 0 to 9, 0 = no
355           compression, 9 = max compression.  Defaults to 6 if -z is not used.
356

ENVIRONMENT

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

NOTES

363       Here are some recipes showing how to utilize pp to bundle source.pl
364       with all its dependencies, on target machines with different expected
365       settings:
366
367       Stone-alone setup:
368           To make a stand-alone executable, suitable for running on a machine
369           that doesn't have perl installed:
370
371               % pp -o packed.exe source.pl        # makes packed.exe
372               # Now, deploy 'packed.exe' to target machine...
373               $ packed.exe                        # run it
374
375       Perl interpreter only, without core modules:
376           To make a packed .pl file including core modules, suitable for
377           running on a machine that has a perl interpreter, but where you
378           want to be sure of the versions of the core modules that your
379           program uses:
380
381               % pp -B -P -o packed.pl source.pl   # makes packed.pl
382               # Now, deploy 'packed.pl' to target machine...
383               $ perl packed.pl                    # run it
384
385       Perl with core modules installed:
386           To make a packed .pl file without core modules, relying on the
387           target machine's perl interpreter and its core libraries.  This
388           produces a significantly smaller file than the previous version:
389
390               % pp -P -o packed.pl source.pl      # makes packed.pl
391               # Now, deploy 'packed.pl' to target machine...
392               $ perl packed.pl                    # run it
393
394       Perl with PAR.pm and its dependencies installed:
395           Make a separate archive and executable that uses the archive. This
396           relies upon the perl interpreter and libraries on the target
397           machine.
398
399               % pp -p source.pl                   # makes source.par
400               % echo "use PAR 'source.par';" > packed.pl;
401               % cat source.pl >> packed.pl;       # makes packed.pl
402               # Now, deploy 'source.par' and 'packed.pl' to target machine...
403               $ perl packed.pl                    # run it, perl + core modules required
404
405       Note that even if your perl was built with a shared library, the
406       'Stand-alone executable' above will not need a separate perl5x.dll or
407       libperl.so to function correctly.  But even in this case, the
408       underlying system libraries such as libc must be compatible between the
409       host and target machines.  Use "--dependent" if you are willing to ship
410       the shared library with the application, which can significantly reduce
411       the executable size.
412

SEE ALSO

414       tkpp, par.pl, parl, perlcc
415
416       PAR, PAR::Packer, Module::ScanDeps
417
418       Getopt::Long, Getopt::ArgvFile
419

ACKNOWLEDGMENTS

421       Simon Cozens, Tom Christiansen and Edward Peschko for writing perlcc;
422       this program try to mimic its interface as close as possible, and
423       copied liberally from their code.
424
425       Jan Dubois for writing the exetype.pl utility, which has been partially
426       adapted into the "-g" flag.
427
428       Mattia Barbon for providing the "myldr" binary loader code.
429
430       Jeff Goff for suggesting the name pp.
431

AUTHORS

433       Audrey Tang <cpan@audreyt.org>, Steffen Mueller <smueller@cpan.org>
434       Roderich Schupp <rschupp@cpan.org>
435
436       You can write to the mailing list at <par@perl.org>, or send an empty
437       mail to <par-subscribe@perl.org> to participate in the discussion.
438
439       Please submit bug reports to <bug-par-packer@rt.cpan.org>.
440
442       Copyright 2002-2009 by Audrey Tang <cpan@audreyt.org>.
443
444       Neither this program nor the associated parl program impose any
445       licensing restrictions on files generated by their execution, in
446       accordance with the 8th article of the Artistic License:
447
448           "Aggregation of this Package with a commercial distribution is
449           always permitted provided that the use of this Package is embedded;
450           that is, when no overt attempt is made to make this Package's
451           interfaces visible to the end user of the commercial distribution.
452           Such use shall not be construed as a distribution of this Package."
453
454       Therefore, you are absolutely free to place any license on the
455       resulting executable, as long as the packed 3rd-party libraries are
456       also available under the Artistic License.
457
458       This program is free software; you can redistribute it and/or modify it
459       under the same terms as Perl itself.
460
461       See LICENSE.
462
463
464
465perl v5.32.1                      2021-01-27                             pp(3)
Impressum