1pp(3) User Contributed Perl Documentation pp(3)
2
6 pp - PAR Packager
7
9 pp [ -ABCEFILMPTSVXacdefghilmnoprsvxz ] [ 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' with icon (Win32 only)
58 % pp --gui --icon hello.ico -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 interpeted 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 additonal 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 additonal run-time dependencies.
158 -X, --exclude=MODULE
160 Exclude the given module from the dependency search path and from
161 the package. If the given file is a zip or par or par executable,
162 all the files in the given file (except MANIFEST, META.yml and
163 script/*) will be excluded and the output file will "use" the given
164 file at runtime.
165 -f, --filter=FILTER
167 Filter source script(s) with a PAR::Filter subclass. You may
168 specify multiple such filters.
169 If you wish to hide the source code from casual prying, this will
171 do:
172 % pp -f Bleach source.pl
174 If you are more serious about hiding your source code, you should
176 have a look at Steve Hay's PAR::Filter::Crypto module. Make sure
177 you understand the Filter::Crypto caveats!
178 -g, --gui
180 Build an executable that does not have a console window. This
181 option is ignored on non-MSWin32 platforms or when "-p" is
182 specified.
183 -h, --help
185 Show basic usage information.
186 -i, --icon=FILE
188 Specify an icon file (in .ico, .exe or .dll format) for the
189 executable. This option is ignored on non-MSWin32 platforms or when
190 "-p" is specified.
191 -N, --info=KEY=VAL
193 Add additional information for the packed file, both in "META.yml"
194 and in the executable header (if applicable). The name/value pair
195 is joined by "=". You may specify "-N" multiple times, or use ";"
196 to link several pairs.
197 For Win32 executables, these special "KEY" names are recognized:
199 Comments CompanyName FileDescription FileVersion
201 InternalName LegalCopyright LegalTrademarks OriginalFilename
202 ProductName ProductVersion
203 -I, --lib=DIR
205 Add the given directory to the perl library file search path. May
206 be specified multiple times.
207 -l, --link=FILE|LIBRARY
209 Add the given shared library (a.k.a. shared object or DLL) into the
210 packed file. Also accepts names under library paths; i.e. "-l
211 ncurses" means the same thing as "-l libncurses.so" or "-l
212 /usr/local/lib/libncurses.so" in most Unixes. May be specified
213 multiple times.
214 -L, --log=FILE
216 Log the output of packaging to a file rather than to stdout.
217 -F, --modfilter=FILTER[=REGEX],
219 Filter included perl module(s) with a PAR::Filter subclass. You
220 may specify multiple such filters. By default, the PodStrip filter
221 is applied.
222 Since PAR 0.958, you can use an optional regular expression (REGEX
224 above) to select the files in the archive which should be filtered.
225 Example:
226 pp -o foo.exe -F Bleach=warnings\.pm$ foo.pl
228 This creates a binary executable foo.exe from foo.pl packaging all
230 files as usual except for files ending in "warnings.pm" which are
231 filtered with PAR::Filter::Bleach.
232 -M, --module=MODULE
234 Add the specified module into the package, along with its
235 dependencies. Also accepts filenames relative to the @INC path;
236 i.e. "-M Module::ScanDeps" means the same thing as "-M
237 Module/ScanDeps.pm".
238 If MODULE has an extension that is not ".pm"/".ix"/".al", it will
240 not be scanned for dependencies, and will be placed under "/"
241 instead of "/lib/" inside the PAR file. This use is deprecated --
242 consider using the -a option instead.
243 You may specify "-M" multiple times.
245 -m, --multiarch
247 Build a multi-architecture PAR file. Implies -p.
248 -n, --noscan
250 Skip the default static scanning altogether, using run-time
251 dependencies from -c or -x exclusively.
252 -o, --output=FILE
254 File name for the final packaged executable.
255 -p, --par
257 Create PAR archives only; do not package to a standalone binary.
258 -P, --perlscript
260 Create stand-alone perl script; do not package to a standalone
261 binary.
262 -r, --run
264 Run the resulting packaged script after packaging it.
265 --reusable
267 EXPERIMENTAL
268 Make the packaged executable reusable for running arbitrary,
270 external Perl scripts as if they were part of the package:
271 pp -o myapp --reusable someapp.pl
273 ./myapp --par-options --reuse otherapp.pl
274 The second line will run otherapp.pl instead of someapp.pl.
276 -S, --save
278 Do not delete generated PAR file after packaging.
279 -s, --sign
281 Cryptographically sign the generated PAR or binary file using
282 Module::Signature.
283 -T, --tempcache
285 Set the program unique part of the cache directory name that is
286 used if the program is run without -C. If not set, a hash of the
287 executable is used.
288 When the program is run, its contents are extracted to a temporary
290 directory. On Unix systems, this is commonly
291 /tmp/par-USERNAME/cache-XXXXXXX. USERNAME is replaced by the user
292 running the program, and XXXXXXX is either a hash of the executable
293 or the value passed to the "-T" or "--tempcache" switch.
294 -v, --verbose[=NUMBER]
296 Increase verbosity of output; NUMBER is an integer from 1 to 3, 3
297 being the most verbose. Defaults to 1 if specified without an
298 argument. Alternatively, -vv sets verbose level to 2, and -vvv
299 sets it to 3.
300 -V, --version
302 Display the version number and copyrights of this program.
303 -z, --compress=NUMBER
305 Set zip compression level; NUMBER is an integer from 0 to 9, 0 = no
306 compression, 9 = max compression. Defaults to 6 if -z is not used.
307
309 PP_OPTS
310 Command-line options (switches). Switches in this variable are
311 taken as if they were on every pp command line.
312
314 Here are some recipes showing how to utilize pp to bundle source.pl
315 with all its dependencies, on target machines with different expected
316 settings:
317 Stone-alone setup:
319 To make a stand-alone executable, suitable for running on a machine
320 that doesn't have perl installed:
321 % pp -o packed.exe source.pl # makes packed.exe
323 # Now, deploy 'packed.exe' to target machine...
324 $ packed.exe # run it
325 Perl interpreter only, without core modules:
327 To make a packed .pl file including core modules, suitable for
328 running on a machine that has a perl interpreter, but where you
329 want to be sure of the versions of the core modules that your
330 program uses:
331 % pp -B -P -o packed.pl source.pl # makes packed.pl
333 # Now, deploy 'packed.pl' to target machine...
334 $ perl packed.pl # run it
335 Perl with core modules installed:
337 To make a packed .pl file without core modules, relying on the
338 target machine's perl interpreter and its core libraries. This
339 produces a significantly smaller file than the previous version:
340 % pp -P -o packed.pl source.pl # makes packed.pl
342 # Now, deploy 'packed.pl' to target machine...
343 $ perl packed.pl # run it
344 Perl with PAR.pm and its dependencies installed:
346 Make a separate archive and executable that uses the archive. This
347 relies upon the perl interpreter and libraries on the target
348 machine.
349 % pp -p source.pl # makes source.par
351 % echo "use PAR 'source.par';" > packed.pl;
352 % cat source.pl >> packed.pl; # makes packed.pl
353 # Now, deploy 'source.par' and 'packed.pl' to target machine...
354 $ perl packed.pl # run it, perl + core modules required
355 Note that even if your perl was built with a shared library, the
357 'Stand-alone executable' above will not need a separate perl5x.dll or
358 libperl.so to function correctly. But even in this case, the
359 underlying system libraries such as libc must be compatible between the
360 host and target machines. Use "--dependent" if you are willing to ship
361 the shared library with the application, which can significantly reduce
362 the executable size.
363
365 tkpp, par.pl, parl, perlcc
366 PAR, PAR::Packer, Module::ScanDeps
368 Getopt::Long, Getopt::ArgvFile
370
372 Simon Cozens, Tom Christiansen and Edward Peschko for writing perlcc;
373 this program try to mimic its interface as close as possible, and
374 copied liberally from their code.
375 Jan Dubois for writing the exetype.pl utility, which has been partially
377 adapted into the "-g" flag.
378 Mattia Barbon for providing the "myldr" binary loader code.
380 Jeff Goff for suggesting the name "pp".
382
384 Audrey Tang <cpan@audreyt.org>, Steffen Mueller <smueller@cpan.org>
385 <http://par.perl.org/> is the official PAR website. You can write to
387 the mailing list at <par@perl.org>, or send an empty mail to
388 <par-subscribe@perl.org> to participate in the discussion.
389 Please submit bug reports to <bug-par@rt.cpan.org>.
391
393 Copyright 2002-2009 by Audrey Tang <cpan@audreyt.org>.
394 Neither this program nor the associated parl program impose any
396 licensing restrictions on files generated by their execution, in
397 accordance with the 8th article of the Artistic License:
398 "Aggregation of this Package with a commercial distribution is
400 always permitted provided that the use of this Package is embedded;
401 that is, when no overt attempt is made to make this Package's
402 interfaces visible to the end user of the commercial distribution.
403 Such use shall not be construed as a distribution of this Package."
404 Therefore, you are absolutely free to place any license on the
406 resulting executable, as long as the packed 3rd-party libraries are
407 also available under the Artistic License.
408 This program is free software; you can redistribute it and/or modify it
410 under the same terms as Perl itself.
411 See <http://www.perl.com/perl/misc/Artistic.html>
413perl v5.12.3 2009-08-26 pp(3)