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 Note that Getopt::ArgvFile is used here with parameter
100 "resolveEnvVars=1", i.e. substrings of the form ${FOO"}" in the
101 contents of @file are replaced with the value of environment variable
102 FOO.
103 -a, --addfile=FILE|DIR
105 Add an extra file into the package. If the file is a directory,
106 recursively add all files inside that directory, with links turned
107 into actual files.
108 By default, files are placed under "/" inside the package with
110 their original names. You may override this by appending the
111 target filename after a ";", like this:
112 % pp -a "old_filename.txt;new_filename.txt"
114 % pp -a "old_dirname;new_dirname"
115 You may specify "-a" multiple times.
117 -A, --addlist=FILE
119 Read a list of file/directory names from FILE, adding them into the
120 package. Each line in FILE is taken as an argument to -a above.
121 You may specify "-A" multiple times.
123 -B, --bundle
125 Bundle core modules in the resulting package. This option is
126 enabled by default, except when "-p" or "-P" is specified.
127 Since PAR version 0.953, this also strips any local paths from the
129 list of module search paths @INC before running the contained
130 script.
131 -C, --clean
133 Clean up temporary files extracted from the application at runtime.
134 By default, these files are cached in the temporary directory; this
135 allows the program to start up faster next time.
136 -c, --compile
138 Run "perl -c inputfile" to determine additional run-time
139 dependencies.
140 -cd, --cachedeps=FILE
142 Use FILE to cache detected dependencies. Creates FILE unless
143 present. This will speed up the scanning process on subsequent
144 runs.
145 -d, --dependent
147 Reduce the executable size by not including a copy of perl
148 interpreter. Executables built this way will need a separate
149 perl5x.dll or libperl.so to function correctly. This option is
150 only available if perl is built as a shared library.
151 -e, --eval=STRING
153 Package a one-liner, much the same as "perl -e '...'"
154 -E, --evalfeature=STRING
156 Behaves just like "-e", except that it implicitly enables all
157 optional features (in the main compilation unit) with Perl 5.10 and
158 later. See feature.
159 -x, --execute
161 Run "perl inputfile" to determine additional run-time dependencies.
162 Using this option, pp may be able to detect the use of modules that
164 can't be determined by static analysis of "inputfile". Examples are
165 stuff loaded by run-time loaders like Module::Runtime or "plugin"
166 loaders like Module::Loader. Note that which modules are detected
167 depends on which parts of your program are exercised when running
168 "inputfile". E.g. if your program immediately terminates when run
169 as "perl inputfile" because it lacks mandatory arguments, then this
170 option will probably have no effect. You may use --xargs to supply
171 arguments in this case.
172 --xargs=STRING
174 If -x is given, splits the "STRING" using the function "shellwords"
175 from Text::ParseWords and passes the result as @ARGV when running
176 "perl inputfile".
177 -X, --exclude=MODULE
179 Exclude the given module from the dependency search path and from
180 the package. If the given file is a zip or par or par executable,
181 all the files in the given file (except MANIFEST, META.yml and
182 script/*) will be excluded and the output file will "use" the given
183 file at runtime.
184 -f, --filter=FILTER
186 Filter source script(s) with a PAR::Filter subclass. You may
187 specify multiple such filters.
188 If you wish to hide the source code from casual prying, this will
190 do:
191 % pp -f Bleach source.pl
193 If you are more serious about hiding your source code, you should
195 have a look at Steve Hay's PAR::Filter::Crypto module. Make sure
196 you understand the Filter::Crypto caveats!
197 Note: Most filters are incompatible with "__DATA__" sections in
199 your source. The packed executable typically aborts with an error
200 message like
201 readline() on unopened filehandle DATA at (eval 13) line 3.
203 -g, --gui
205 Build an executable that does not have a console window. This
206 option is ignored on non-MSWin32 platforms or when "-p" is
207 specified.
208 -h, --help
210 Show basic usage information.
211 -I, --lib=DIR
213 Add the given directory to the perl module search path. May be
214 specified multiple times.
215 -l, --link=FILE|LIBRARY
217 Add the given shared library (a.k.a. shared object or DLL) into the
218 packed file. Also accepts names under library paths; i.e. "-l
219 ncurses" means the same thing as "-l libncurses.so" or "-l
220 /usr/local/lib/libncurses.so" in most Unixes. May be specified
221 multiple times.
222 -L, --log=FILE
224 Log the output of packaging to a file rather than to stdout.
225 -F, --modfilter=FILTER[=REGEX],
227 Filter included perl module(s) with a PAR::Filter subclass. You
228 may specify multiple such filters.
229 By default, the PodStrip filter is applied. In case that causes
231 trouble, you can turn this off by setting the environment variable
232 "PAR_VERBATIM" to 1.
233 Since PAR 0.958, you can use an optional regular expression (REGEX
235 above) to select the files in the archive which should be filtered.
236 Example:
237 pp -o foo.exe -F Bleach=warnings\.pm$ foo.pl
239 This creates a binary executable foo.exe from foo.pl packaging all
241 files as usual except for files ending in "warnings.pm" which are
242 filtered with PAR::Filter::Bleach.
243 Note: The same restriction on "__DATA__" sections holds as for
245 --filter.
246 -M, --module=MODULE
248 Add the specified module into the package, along with its
249 dependencies.
250 The following variants may be used to add whole module namespaces:
252 -M Foo::**
254 Add every module in the "Foo" namespace except "Foo" itself,
255 i.e. add "Foo::Bar", "Foo::Bar::Quux" etc up to any depth.
256 -M Foo::*
258 Add every module at level 1 in the "Foo" namespace, i.e. add
259 "Foo::Bar", but neither "Foo::Bar::Quux" nor "Foo".
260 -M Foo::
262 Shorthand for "-M Foo -M Foo:**": every module in the "Foo"
263 namespace including "Foo" itself.
264 Instead of a module name, MODULE may also be specified as a
266 filename relative to the @INC path, i.e. "-M Module/ScanDeps.pm"
267 means the same thing as "-M Module::ScanDeps".
268 If MODULE has an extension that is not ".pm"/".ix"/".al", it will
270 not be scanned for dependencies, and will be placed under "/"
271 instead of "/lib/" inside the PAR file. This use is deprecated --
272 consider using the -a option instead.
273 You may specify "-M" multiple times.
275 -m, --multiarch
277 Build a multi-architecture PAR file. Implies -p.
278 -n, --noscan
280 Skip the default static scanning altogether, using run-time
281 dependencies from -c or -x exclusively.
282 -N, --namespace=NAMESPACE
284 Add all modules in the namespace into the package, along with their
285 dependencies. If "NAMESPACE" is something like "Foo::Bar" then this
286 will add all modules "Foo/Bar/Quux.pm", "Foo/Bar/Fred/Barnie.pm"
287 etc that can be located in your module search path. It mimics the
288 behaviour of "plugin" loaders like Module::Loader.
289 This is different from using "-M Foo::Bar::", as the latter insists
291 on adding "Foo/Bar.pm" which might not exist in the above "plugin"
292 scenario.
293 You may specify "-N" multiple times.
295 -o, --output=FILE
297 File name for the final packaged executable.
298 -p, --par
300 Create PAR archives only; do not package to a standalone binary.
301 -P, --perlscript
303 Create stand-alone perl script; do not package to a standalone
304 binary.
305 -r, --run
307 Run the resulting packaged script after packaging it.
308 --reusable
310 EXPERIMENTAL
311 Make the packaged executable reusable for running arbitrary,
313 external Perl scripts as if they were part of the package:
314 pp -o myapp --reusable someapp.pl
316 ./myapp --par-options --reuse otherapp.pl
317 The second line will run otherapp.pl instead of someapp.pl.
319 -S, --save
321 Do not delete generated PAR file after packaging.
322 -s, --sign
324 Cryptographically sign the generated PAR or binary file using
325 Module::Signature.
326 -T, --tempcache
328 Set the program unique part of the cache directory name that is
329 used if the program is run without -C. If not set, a hash of the
330 executable is used.
331 When the program is run, its contents are extracted to a temporary
333 directory. On Unix systems, this is commonly
334 /tmp/par-USER/cache-XXXXXXX. USER is replaced by the name of the
335 user running the program, but "spelled" in hex. XXXXXXX is either
336 a hash of the executable or the value passed to the "-T" or
337 "--tempcache" switch.
338 -u, --unicode
340 Note: This option is ignored for Perl 5.32 and above.
341 Package Unicode support (essentially utf8_heavy.pl and everything
343 below the directory unicore in your perl library).
344 This option exists because it is impossible to detect using static
346 analysis whether your program needs Unicode support at runtime.
347 (Note: If your program contains "use utf8" this does not imply it
348 needs Unicode support. It merely says that your program source is
349 written in UTF-8.)
350 If your packed program exits with an error message like
352 Can't locate utf8_heavy.pl in @INC (@INC contains: ...)
354 try to pack it with "-u" (or use "-x").
356 -v, --verbose[=NUMBER]
358 Increase verbosity of output; NUMBER is an integer from 1 to 3, 3
359 being the most verbose. Defaults to 1 if specified without an
360 argument. Alternatively, -vv sets verbose level to 2, and -vvv
361 sets it to 3.
362 -V, --version
364 Display the version number and copyrights of this program.
365 -z, --compress=NUMBER
367 Set zip compression level; NUMBER is an integer from 0 to 9, 0 = no
368 compression, 9 = max compression. Defaults to 6 if -z is not used.
369
371 PP_OPTS
372 Command-line options (switches). Switches in this variable are
373 taken as if they were on every pp command line.
374
376 Here are some recipes showing how to utilize pp to bundle source.pl
377 with all its dependencies, on target machines with different expected
378 settings:
379 Stone-alone setup:
381 To make a stand-alone executable, suitable for running on a machine
382 that doesn't have perl installed:
383 % pp -o packed.exe source.pl # makes packed.exe
385 # Now, deploy 'packed.exe' to target machine...
386 $ packed.exe # run it
387 Perl interpreter only, without core modules:
389 To make a packed .pl file including core modules, suitable for
390 running on a machine that has a perl interpreter, but where you
391 want to be sure of the versions of the core modules that your
392 program uses:
393 % pp -B -P -o packed.pl source.pl # makes packed.pl
395 # Now, deploy 'packed.pl' to target machine...
396 $ perl packed.pl # run it
397 Perl with core modules installed:
399 To make a packed .pl file without core modules, relying on the
400 target machine's perl interpreter and its core libraries. This
401 produces a significantly smaller file than the previous version:
402 % pp -P -o packed.pl source.pl # makes packed.pl
404 # Now, deploy 'packed.pl' to target machine...
405 $ perl packed.pl # run it
406 Perl with PAR.pm and its dependencies installed:
408 Make a separate archive and executable that uses the archive. This
409 relies upon the perl interpreter and libraries on the target
410 machine.
411 % pp -p source.pl # makes source.par
413 % echo "use PAR 'source.par';" > packed.pl;
414 % cat source.pl >> packed.pl; # makes packed.pl
415 # Now, deploy 'source.par' and 'packed.pl' to target machine...
416 $ perl packed.pl # run it, perl + core modules required
417 Note that even if your perl was built with a shared library, the
419 'Stand-alone executable' above will not need a separate perl5x.dll or
420 libperl.so to function correctly. But even in this case, the
421 underlying system libraries such as libc must be compatible between the
422 host and target machines. Use "--dependent" if you are willing to ship
423 the shared library with the application, which can significantly reduce
424 the executable size.
425
427 tkpp, par.pl, parl, perlcc
428 PAR, PAR::Packer, Module::ScanDeps
430 Getopt::Long, Getopt::ArgvFile
432
434 Simon Cozens, Tom Christiansen and Edward Peschko for writing perlcc;
435 this program try to mimic its interface as close as possible, and
436 copied liberally from their code.
437 Jan Dubois for writing the exetype.pl utility, which has been partially
439 adapted into the "-g" flag.
440 Mattia Barbon for providing the "myldr" binary loader code.
442 Jeff Goff for suggesting the name pp.
444
446 Audrey Tang <cpan@audreyt.org>, Steffen Mueller <smueller@cpan.org>
447 Roderich Schupp <rschupp@cpan.org>
448 You can write to the mailing list at <par@perl.org>, or send an empty
450 mail to <par-subscribe@perl.org> to participate in the discussion.
451 Please submit bug reports to <bug-par-packer@rt.cpan.org>.
453
455 Copyright 2002-2009 by Audrey Tang <cpan@audreyt.org>.
456 Neither this program nor the associated parl program impose any
458 licensing restrictions on files generated by their execution, in
459 accordance with the 8th article of the Artistic License:
460 "Aggregation of this Package with a commercial distribution is
462 always permitted provided that the use of this Package is embedded;
463 that is, when no overt attempt is made to make this Package's
464 interfaces visible to the end user of the commercial distribution.
465 Such use shall not be construed as a distribution of this Package."
466 Therefore, you are absolutely free to place any license on the
468 resulting executable, as long as the packed 3rd-party libraries are
469 also available under the Artistic License.
470 This program is free software; you can redistribute it and/or modify it
472 under the same terms as Perl itself.
473 See LICENSE.
475perl v5.36.0 2022-12-02 pp(3)