1pp(3) User Contributed Perl Documentation pp(3)
2
6 pp - PAR Packager
7
9 pp [ -ABCEFILMPTSVXacdefghilmnoprsuvxz ] [ parfile | scriptfile ]...
10
12 Note: When running on Microsoft Windows, the a.out below will be
13 replaced by a.exe instead.
14 % 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 % 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 % 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 % 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 % 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 % 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 % 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 % 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 % pp hello --log=c # Pack 'hello' into 'a.out', logs
55 # messages into 'c'
56 # Pack 'hello' into a console-less 'out.exe' (Win32 only)
58 % pp --gui -o out.exe hello
59 % pp @file hello.pl # Pack 'hello.pl' but read _additional_
61 # options from file 'file'
62
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 You may think of pp as "perlcc that works without hassle". :-)
70 A GUI interface is also available as the tkpp command.
72 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 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
85 Options are available in a short form and a long form. For example,
86 the three lines below are all equivalent:
87 % pp -o output.exe input.pl
89 % pp --output output.exe input.pl
90 % pp --output=output.exe input.pl
91 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 -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 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 % pp -a "old_filename.txt;new_filename.txt"
110 % pp -a "old_dirname;new_dirname"
111 You may specify "-a" multiple times.
113 -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 You may specify "-A" multiple times.
119 -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 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 -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 -c, --compile
134 Run "perl -c inputfile" to determine additional run-time
135 dependencies.
136 -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 -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 -e, --eval=STRING
149 Package a one-liner, much the same as "perl -e '...'"
150 -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 -x, --execute
157 Run "perl inputfile" to determine additional run-time dependencies.
158 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 --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 -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 -f, --filter=FILTER
182 Filter source script(s) with a PAR::Filter subclass. You may
183 specify multiple such filters.
184 If you wish to hide the source code from casual prying, this will
186 do:
187 % pp -f Bleach source.pl
189 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 Note: Most filters are incompatible with "__DATA__" sections in
195 your source. The packed executable typically aborts with an error
196 message like
197 readline() on unopened filehandle DATA at (eval 13) line 3.
199 -g, --gui
201 Build an executable that does not have a console window. This
202 option is ignored on non-MSWin32 platforms or when "-p" is
203 specified.
204 -h, --help
206 Show basic usage information.
207 -I, --lib=DIR
209 Add the given directory to the perl module search path. May be
210 specified multiple times.
211 -l, --link=FILE|LIBRARY
213 Add the given shared library (a.k.a. shared object or DLL) into the
214 packed file. Also accepts names under library paths; i.e. "-l
215 ncurses" means the same thing as "-l libncurses.so" or "-l
216 /usr/local/lib/libncurses.so" in most Unixes. May be specified
217 multiple times.
218 -L, --log=FILE
220 Log the output of packaging to a file rather than to stdout.
221 -F, --modfilter=FILTER[=REGEX],
223 Filter included perl module(s) with a PAR::Filter subclass. You
224 may specify multiple such filters.
225 By default, the PodStrip filter is applied. In case that causes
227 trouble, you can turn this off by setting the environment variable
228 "PAR_VERBATIM" to 1.
229 Since PAR 0.958, you can use an optional regular expression (REGEX
231 above) to select the files in the archive which should be filtered.
232 Example:
233 pp -o foo.exe -F Bleach=warnings\.pm$ foo.pl
235 This creates a binary executable foo.exe from foo.pl packaging all
237 files as usual except for files ending in "warnings.pm" which are
238 filtered with PAR::Filter::Bleach.
239 Note: The same restriction on "__DATA__" sections holds as for
241 --filter.
242 -M, --module=MODULE
244 Add the specified module into the package, along with its
245 dependencies.
246 The following variants may be used to add whole module namespaces:
248 -M Foo::**
250 Add every module in the "Foo" namespace except "Foo" itself,
251 i.e. add "Foo::Bar", "Foo::Bar::Quux" etc up to any depth.
252 -M Foo::*
254 Add every module at level 1 in the "Foo" namespace, i.e. add
255 "Foo::Bar", but neither "Foo::Bar::Quux" nor "Foo".
256 -M Foo::
258 Shorthand for "-M Foo -M Foo:**": every module in the "Foo"
259 namespace including "Foo" itself.
260 Instead of a module name, MODULE may also be specified as a
262 filename relative to the @INC path, i.e. "-M Module/ScanDeps.pm"
263 means the same thing as "-M Module::ScanDeps".
264 If MODULE has an extension that is not ".pm"/".ix"/".al", it will
266 not be scanned for dependencies, and will be placed under "/"
267 instead of "/lib/" inside the PAR file. This use is deprecated --
268 consider using the -a option instead.
269 You may specify "-M" multiple times.
271 -m, --multiarch
273 Build a multi-architecture PAR file. Implies -p.
274 -n, --noscan
276 Skip the default static scanning altogether, using run-time
277 dependencies from -c or -x exclusively.
278 -N, --namespace=NAMESPACE
280 Add all modules in the namespace into the package, along with their
281 dependencies. If "NAMESPACE" is something like "Foo::Bar" then this
282 will add all modules "Foo/Bar/Quux.pm", "Foo/Bar/Fred/Barnie.pm"
283 etc that can be located in your module search path. It mimics the
284 behaviour of "plugin" loaders like Module::Loader.
285 This is different from using "-M Foo::Bar::", as the latter insists
287 on adding "Foo/Bar.pm" which might not exist in the above "plugin"
288 scenario.
289 You may specify "-N" multiple times.
291 -o, --output=FILE
293 File name for the final packaged executable.
294 -p, --par
296 Create PAR archives only; do not package to a standalone binary.
297 -P, --perlscript
299 Create stand-alone perl script; do not package to a standalone
300 binary.
301 -r, --run
303 Run the resulting packaged script after packaging it.
304 --reusable
306 EXPERIMENTAL
307 Make the packaged executable reusable for running arbitrary,
309 external Perl scripts as if they were part of the package:
310 pp -o myapp --reusable someapp.pl
312 ./myapp --par-options --reuse otherapp.pl
313 The second line will run otherapp.pl instead of someapp.pl.
315 -S, --save
317 Do not delete generated PAR file after packaging.
318 -s, --sign
320 Cryptographically sign the generated PAR or binary file using
321 Module::Signature.
322 -T, --tempcache
324 Set the program unique part of the cache directory name that is
325 used if the program is run without -C. If not set, a hash of the
326 executable is used.
327 When the program is run, its contents are extracted to a temporary
329 directory. On Unix systems, this is commonly
330 /tmp/par-USER/cache-XXXXXXX. USER is replaced by the name of the
331 user running the program, but "spelled" in hex. XXXXXXX is either
332 a hash of the executable or the value passed to the "-T" or
333 "--tempcache" switch.
334 -u, --unicode
336 Note: This option is ignored for Perl 5.32 and above.
337 Package Unicode support (essentially utf8_heavy.pl and everything
339 below the directory unicore in your perl library).
340 This option exists because it is impossible to detect using static
342 analysis whether your program needs Unicode support at runtime.
343 (Note: If your program contains "use utf8" this does not imply it
344 needs Unicode support. It merely says that your program source is
345 written in UTF-8.)
346 If your packed program exits with an error message like
348 Can't locate utf8_heavy.pl in @INC (@INC contains: ...)
350 try to pack it with "-u" (or use "-x").
352 -v, --verbose[=NUMBER]
354 Increase verbosity of output; NUMBER is an integer from 1 to 3, 3
355 being the most verbose. Defaults to 1 if specified without an
356 argument. Alternatively, -vv sets verbose level to 2, and -vvv
357 sets it to 3.
358 -V, --version
360 Display the version number and copyrights of this program.
361 -z, --compress=NUMBER
363 Set zip compression level; NUMBER is an integer from 0 to 9, 0 = no
364 compression, 9 = max compression. Defaults to 6 if -z is not used.
365
367 PP_OPTS
368 Command-line options (switches). Switches in this variable are
369 taken as if they were on every pp command line.
370
372 Here are some recipes showing how to utilize pp to bundle source.pl
373 with all its dependencies, on target machines with different expected
374 settings:
375 Stone-alone setup:
377 To make a stand-alone executable, suitable for running on a machine
378 that doesn't have perl installed:
379 % pp -o packed.exe source.pl # makes packed.exe
381 # Now, deploy 'packed.exe' to target machine...
382 $ packed.exe # run it
383 Perl interpreter only, without core modules:
385 To make a packed .pl file including core modules, suitable for
386 running on a machine that has a perl interpreter, but where you
387 want to be sure of the versions of the core modules that your
388 program uses:
389 % pp -B -P -o packed.pl source.pl # makes packed.pl
391 # Now, deploy 'packed.pl' to target machine...
392 $ perl packed.pl # run it
393 Perl with core modules installed:
395 To make a packed .pl file without core modules, relying on the
396 target machine's perl interpreter and its core libraries. This
397 produces a significantly smaller file than the previous version:
398 % pp -P -o packed.pl source.pl # makes packed.pl
400 # Now, deploy 'packed.pl' to target machine...
401 $ perl packed.pl # run it
402 Perl with PAR.pm and its dependencies installed:
404 Make a separate archive and executable that uses the archive. This
405 relies upon the perl interpreter and libraries on the target
406 machine.
407 % pp -p source.pl # makes source.par
409 % echo "use PAR 'source.par';" > packed.pl;
410 % cat source.pl >> packed.pl; # makes packed.pl
411 # Now, deploy 'source.par' and 'packed.pl' to target machine...
412 $ perl packed.pl # run it, perl + core modules required
413 Note that even if your perl was built with a shared library, the
415 'Stand-alone executable' above will not need a separate perl5x.dll or
416 libperl.so to function correctly. But even in this case, the
417 underlying system libraries such as libc must be compatible between the
418 host and target machines. Use "--dependent" if you are willing to ship
419 the shared library with the application, which can significantly reduce
420 the executable size.
421
423 tkpp, par.pl, parl, perlcc
424 PAR, PAR::Packer, Module::ScanDeps
426 Getopt::Long, Getopt::ArgvFile
428
430 Simon Cozens, Tom Christiansen and Edward Peschko for writing perlcc;
431 this program try to mimic its interface as close as possible, and
432 copied liberally from their code.
433 Jan Dubois for writing the exetype.pl utility, which has been partially
435 adapted into the "-g" flag.
436 Mattia Barbon for providing the "myldr" binary loader code.
438 Jeff Goff for suggesting the name pp.
440
442 Audrey Tang <cpan@audreyt.org>, Steffen Mueller <smueller@cpan.org>
443 Roderich Schupp <rschupp@cpan.org>
444 You can write to the mailing list at <par@perl.org>, or send an empty
446 mail to <par-subscribe@perl.org> to participate in the discussion.
447 Please submit bug reports to <bug-par-packer@rt.cpan.org>.
449
451 Copyright 2002-2009 by Audrey Tang <cpan@audreyt.org>.
452 Neither this program nor the associated parl program impose any
454 licensing restrictions on files generated by their execution, in
455 accordance with the 8th article of the Artistic License:
456 "Aggregation of this Package with a commercial distribution is
458 always permitted provided that the use of this Package is embedded;
459 that is, when no overt attempt is made to make this Package's
460 interfaces visible to the end user of the commercial distribution.
461 Such use shall not be construed as a distribution of this Package."
462 Therefore, you are absolutely free to place any license on the
464 resulting executable, as long as the packed 3rd-party libraries are
465 also available under the Artistic License.
466 This program is free software; you can redistribute it and/or modify it
468 under the same terms as Perl itself.
469 See LICENSE.
471perl v5.32.1 2021-01-27 pp(3)