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 -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 -h, --help
200 Show basic usage information.
201 -I, --lib=DIR
203 Add the given directory to the perl module search path. May be
204 specified multiple times.
205 -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 -L, --log=FILE
214 Log the output of packaging to a file rather than to stdout.
215 -F, --modfilter=FILTER[=REGEX],
217 Filter included perl module(s) with a PAR::Filter subclass. You
218 may specify multiple such filters.
219 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 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 pp -o foo.exe -F Bleach=warnings\.pm$ foo.pl
229 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 -M, --module=MODULE
235 Add the specified module into the package, along with its
236 dependencies.
237 The following variants may be used to add whole module namespaces:
239 -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 -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 -M Foo::
249 Shorthand for "-M Foo -M Foo:**": every module in the "Foo"
250 namespace including "Foo" itself.
251 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 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 You may specify "-M" multiple times.
262 -m, --multiarch
264 Build a multi-architecture PAR file. Implies -p.
265 -n, --noscan
267 Skip the default static scanning altogether, using run-time
268 dependencies from -c or -x exclusively.
269 -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 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 You may specify "-N" multiple times.
282 -o, --output=FILE
284 File name for the final packaged executable.
285 -p, --par
287 Create PAR archives only; do not package to a standalone binary.
288 -P, --perlscript
290 Create stand-alone perl script; do not package to a standalone
291 binary.
292 -r, --run
294 Run the resulting packaged script after packaging it.
295 --reusable
297 EXPERIMENTAL
298 Make the packaged executable reusable for running arbitrary,
300 external Perl scripts as if they were part of the package:
301 pp -o myapp --reusable someapp.pl
303 ./myapp --par-options --reuse otherapp.pl
304 The second line will run otherapp.pl instead of someapp.pl.
306 -S, --save
308 Do not delete generated PAR file after packaging.
309 -s, --sign
311 Cryptographically sign the generated PAR or binary file using
312 Module::Signature.
313 -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 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 -u, --unicode
327 Note: This option is ignored for Perl 5.32 and above.
328 Package Unicode support (essentially utf8_heavy.pl and everything
330 below the directory unicore in your perl library).
331 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 If your packed program exits with an error message like
339 Can't locate utf8_heavy.pl in @INC (@INC contains: ...)
341 try to pack it with "-u" (or use "-x").
343 -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 -V, --version
351 Display the version number and copyrights of this program.
352 -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
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
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 Stone-alone setup:
368 To make a stand-alone executable, suitable for running on a machine
369 that doesn't have perl installed:
370 % pp -o packed.exe source.pl # makes packed.exe
372 # Now, deploy 'packed.exe' to target machine...
373 $ packed.exe # run it
374 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 % 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 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 % 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 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 % 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 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
414 tkpp, par.pl, parl, perlcc
415 PAR, PAR::Packer, Module::ScanDeps
417 Getopt::Long, Getopt::ArgvFile
419
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 Jan Dubois for writing the exetype.pl utility, which has been partially
426 adapted into the "-g" flag.
427 Mattia Barbon for providing the "myldr" binary loader code.
429 Jeff Goff for suggesting the name pp.
431
433 Audrey Tang <cpan@audreyt.org>, Steffen Mueller <smueller@cpan.org>
434 Roderich Schupp <rschupp@cpan.org>
435 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 Please submit bug reports to <bug-par-packer@rt.cpan.org>.
440
442 Copyright 2002-2009 by Audrey Tang <cpan@audreyt.org>.
443 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 "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 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 This program is free software; you can redistribute it and/or modify it
459 under the same terms as Perl itself.
460 See LICENSE.
462perl v5.32.1 2021-01-27 pp(3)