1PAR::FAQ(3)           User Contributed Perl Documentation          PAR::FAQ(3)
2
3
4

NAME

6       PAR::FAQ - Frequently Asked Questions about PAR
7

SYNOPSIS

9       This is the Frequently Asked Questions list for the Perl Archive
10       Toolkit.  This (included) FAQ list might be outdated. The Wiki version
11       at the above URL is guaranteed to be up to date.
12

DESCRIPTION

14   Where is the Windows binary version?
15       You can find windows binaries here:
16
17       <http://www.cpan.org/authors/id/S/SM/SMUELLER/>
18
19       There are three ways to install them. Sorted in order of preference:
20
21       cpan
22
23       Run the cpan command line tool that comes with Perl. In the cpan shell,
24       type
25
26         install PAR
27
28       and wait for the script to download and extract PAR and its
29       dependencies. If you have a C compiler installed, PAR will be built on
30       your computer for your specific version of Perl. If you do not have a C
31       compiler, the installer will look at the site referenced above for a
32       compatible binary release and ask you whether you would like to install
33       it.
34
35       ppm
36
37       If you are using ActivePerl from ActiveState, you can use the 'ppm'
38       program that comes with the ActiveState Perl. Instructions can be found
39       below. PAR is available from various PPM repositories and some packages
40       are compatible with some versions of ActivePerl and not with others.
41       There is an incomplete PAR-Win32 Binary Compatibility List at
42       <http://par.wikia.com/wiki/PAR_PPM_Compatibility_List> There are at
43       least three relevant PPM repositories: The default ActiveState one, the
44       bribes repository which is used in the example below and Randy Kobes'
45       repository at <http://theoryx5.uwinnipeg.ca/ppms/>.
46
47           C:\> ppm3
48           # activestate was out of date compared to this one
49           % rep add bribes http://www.bribes.org/perl/ppm
50           # move it to first place on list of repositories
51           % rep up bribes
52           CPAN>upgrade -install PAR
53
54       And finally, 'q' to quit and that's all :-) You have access to pp and
55       so on...
56
57       manual
58
59       For reference, here's the old explanation of how to install it by hand:
60       The file you need will be called
61       PAR-X.XX-MSWin32-x86-multi-thread-Y.Y.Y.par where X.XX is the version
62       of PAR you will use and Y.Y.Y is the version of Perl you have. Unzip
63       this file (you may need to rename it to end with .zip instead of .par
64       first) and copy all the files in the script directory into a directory
65       in your PATH. Now you should be able to use PAR.
66
67   Can PAR bundle all its prerequisites?
68       Note: This entry needs serious attention.
69
70       Yes and no.
71
72       It would be possible to do this but it would also introduce a
73       maintenance nightmare. A new version of PAR would have to be released
74       whenever a new version of any of the dependencies came out. This is
75       already painful with the included Module::Install.
76
77       The original proposal which led to this FAQ entry considered the case
78       where you want to install PAR without a working CPAN.pm/CPAN shell
79       installation or without internet connectivity. By default, PAR will try
80       to install its dependencies from CPAN using the CPAN.pm module.
81
82       Given that you have a development machine with PAR installed and with a
83       working CPAN.pm, it is reasonably simple to create one or more .par
84       distributions of PAR's dependencies. Install PAR::Dist::FromCPAN. Then
85       you can create .par distributions (read: binaries installable with the
86       pure-perl PAR::Dist on the same architecture) for the PAR dependencies
87       as follows:
88
89         mkdir par_files
90         cpan2par --pattern PAR --follow --out par_files/ --merge --skip File::.*
91                  --skip Getopt::Std --skip Carp --skip Data::Dumper --skip Time::Local
92                  --skip 'Test\b.*' --skip Text::ParseWords --skip ExtUtils::.*
93                  --skip Getopt::Long --skip Text::Abbrev --skip DirHandle --skip Pod::.*
94
95       (Line breaks inserted for readability.) What happens here? cpan2par
96       uses the API of the CPAN.pm module to fetch the PAR distribution from
97       CPAN, unpacks it, builds it, creates a .par archive from its compiled
98       state and then does the same for any of its dependencies. And then for
99       its dependencies dependencies and... You get the idea. This is what the
100       --follow option does. We add a couple of --skip options to skip core
101       modules which we need not include and any Test::* modules. The --merge
102       option merges all of the .par distributions into the original PAR one.
103       Voila! (Future versions of PAR::Dist::FromCPAN might include an option
104       --skip-core which would skip any modules contained in the core
105       distribution.)
106
107       After this command worked its magic, you should have a single file
108       PAR-VERSION-ARCHNAME-PERLVERSION.par in the subdirectory 'par_files/'.
109       You can now install PAR and its non-core dependencies on any machine
110       that has the architecture of your development system (and a binary
111       compatible perl version) using PAR::Dist as follows:
112
113         perl -MPAR::Dist -einstall_par
114
115       Provided that you run the command from within the directory containing
116       the aforementioned .par file (and no other .par file).
117
118       Since you might not even have PAR::Dist on the target machine, you can
119       do this simple hack to get a basic installer:
120
121         perl -MPAR::Dist -e'open my $fh, "<", $INC{"PAR/Dist.pm"}; print <$fh>;
122              print "\npackage main;\nPAR::Dist::install_par(\@ARGV ? shift(\@ARGV)
123              : ());\n\n"'
124              > installer.pl
125
126       (Again: Line breaks inserted for readability.) This looks for your
127       installed copy of PAR::Dist, reads it, writes it to STDOUT and appends
128       two lines of code: "package main;" and a call to
129       PAR::Dist::install_par. By default, it will install any (single) .par
130       file in the current directory. If supplied with a file name as first
131       argument, it will install the specified file. It should have no non-
132       core dependencies! So shipping the generated PAR-....par file and the
133       installer.pl file to the target machine and running "perl installer.pl"
134       should just magically install PAR and its dependencies for you.
135
136       Now, this whole trick works equally well for any other modules. In
137       fact, if you have PAR on the target machine, you needn't even install
138       the modules in the .par file in order to use them! You can just add
139       "use PAR 'foo-bar.par';" to your code and any modules will be loaded
140       from the .par file as necessary. ("perl -MPAR=foo-bar.par
141       your_script.pl" works, too.) The documentation of the PAR module has
142       details on this.
143
144       Finally, note that you can install PAR::Repository::Client on the
145       target machines and subsequently use PAR 0.951 and later to
146       automatically fetch any unfulfilled dependencies from a (remote or
147       local) repository:
148
149         use PAR { repository => 'http://my_local_secure_host/repository' };
150
151       or:
152
153         use PAR { repository => 'file:///path/to/repository' };
154
155       Details, again, in the PAR documentation and in the
156       PAR::Repository::Client documentation.
157
158       Answer from: Steffen Mueller, 16 August 2006
159
160   If I try to compile my wxGlade generated script, it doesn't run. What's
161       wrong?
162       Note: Is this still a problem?
163
164       Comment out the line that starts with " unless (caller) ", and compile
165       it again. Note that this is considered a bug; clearing the caller stack
166       is a development in progress.
167
168   I get a link error '/usr/bin/ld: cannot find -lperl' during the 'make' step
169       of the installation on Debian. What's wrong?
170       Install the "libperl-dev" package.
171
172       Note that Debian provides (usually up-to-date) packages of the modules
173       in the PAR ecosystem: Module::Scandeps, PAR, PAR::Dist and PAR::Packer;
174       the corresponding packages are called "libmodule-scandeps-perl",
175       "libpar-dist-perl", "libpar-perl" and "libpar-packer-perl".
176
177   I specify a .ico file with --icon for Win32, but the icon is still the
178       black and white camel. What's wrong?
179       Unlike Perl2EXE, which can use a standard 16-color bitmap as an
180       application icon, PAR requires a true Windows icon file. Download a
181       trial version of Microangelo and use that to create your .ico file. The
182       latest Netpbm tools at <http://netpbm.sourceforge.net/> has
183       ppmtowinicon, which can tack a pbm and convert it to a windows icon. It
184       is open source and has win32 ports.
185
186       Gimp for Windows can also create Windows icon files
187       <http://gimp-win.sourceforge.net/>.
188
189   I added a directory to my PAR file using "zip -r" or winzip, and then
190       generated an executable from this PAR file, and the executable failed
191       to run (IO error: reading header signature :..). What's wrong?
192       As pointed out by Alan Stewart, zip adds a directory entry for the new
193       directory, and it causes the PAR executable to fail. Just use :
194
195         zip -r -D hello.par my_dir/
196
197       or the Archive::Zip::addTree as follows :
198
199         $zip->addTree( $root, $dest, sub { -f } )
200
201   On what platforms can I run PAR? On what platforms will the resulting
202       executable run?
203       Win32 (95/98/ME/NT4/2K/XP), FreeBSD, Linux, AIX, Solaris, Darwin and
204       Cygwin.
205
206       The resulting executable will run on any platforms that supports the
207       binary format of the generating platform.
208
209   How do I extract my script out of packed executable?
210       In other words, "I did a `pp foo.pl' and I lost foo.pl, how do I get it
211       back?".
212
213       The answer is to just use unzip/winzip/winrar/whatever to decompress
214       the executable, treating it like a normal Zip file. You may need to
215       rename the executable into a .zip extension first.
216
217   Can PAR completely hide my source code?
218       Not completely, but possible to a degree. Starting from version 0.76,
219       PAR supports an input filter mechanism, which can be used to implement
220       source obfuscators (or even product activation schemes).
221
222       But if you are looking for 100% bulletproof way of hiding source code,
223       it is not possible with any language. Learning Perl, 3rd Edition has
224       this answer to offer (quoted with permission from Randal Schwartz):
225
226       If you're wishing for an opaque binary, though, we have to tell you
227       that they don't exist. If someone can install and run your program,
228       they can turn it back into source code. Granted, this won't necessarily
229       be the same source that you started with, but it will be some kind of
230       source code. The real way to keep your secret algorithm a secret is,
231       alas, to apply the proper number of attorneys; they can write a license
232       that says "you can do this with the code, but you can't do that. And if
233       you break our rules, we've got the proper number of attorneys to ensure
234       that you'll regret it."
235
236       Other than that, I would point you at PAR::Filter::Crypto. Be sure to
237       read the CAVEATS and WARNINGS sections of the documentation.
238
239   On Windows XP, pp crashes saying that "par.exe has encountered a problem"
240       This is believed to be fixed by PAR 0.76_99. The following answer
241       applies to PAR 0.76 and earlier:
242
243       You may be able to escape this problem by setting some executables to
244       Windows 95 compatibility mode. Specifically, find "parl.exe" (probably
245       in "C:\perl\5.8.0\bin") using Windows Explorer, and right-click on it
246       and choose "Properties". Choose the "Compatibility" tab and tick the
247       box for "Run this program with compatibility mode for" and check that
248       the dropdown shows "Windows 95". Then click OK.
249
250       Now you can hopefully run pp as normal to generate an EXE. Before you
251       can run the generated EXE, you'll need to set its compatibility mode
252       too, in the same way as you did for parl.exe.
253
254       This workaround is known not to work in all cases, and the developers
255       are working on a solution to the problem. See these posts for more
256       info:
257
258       <http://www.mail-archive.com/par@perl.org/msg00423.html>,
259       <http://www.mail-archive.com/par@perl.org/msg00435.html>,
260       <http://www.mail-archive.com/par@perl.org/msg00573.html>,
261       <http://www.mail-archive.com/par@perl.org/msg00670.html>
262
263   Perl Tk tips
264       On Windows XP start your script with
265
266         use strict; use Encode::Unicode; use Tk;
267
268       Some widgets use xbm bitmaps which don't get picked up by PAR. The
269       error is:
270
271         couldn't read bitmap file "": No such file or directory
272         error reading bitmap file "" at Tk/Widget.pm line 205.
273         at Tk/Widget.pm line 203
274
275       Fix is to find the missing xbm files (perl -V tells you where to start
276       looking) and add them to the executable eg
277
278       copy missing xbm files to script directory then:
279
280           % pp --add cbxarrow.xbm --add arrowdownwin.xbm -o test test.pl
281
282   Problem with Win32::Perms and Perms.DLL
283       With a script my.pl using Win32::Perms, pp -o my.exe my.pl you may
284       have:
285
286         Can't locate loadable object for module Win32::Perms in @INC
287         (@INC contains: CODE(0xb97eec) CODE(0xc8a99c) .)
288         at ../blib/lib/PAR/Heavy.pm line 78
289
290       In fact the dll is Perms.DLL wit DLL in capital letters. That's the
291       problem. The bootstrap function of PAR in the Dynaloader module fails
292       looking for Perms.dll in the table of dlls which contains only
293       Perms.DLL. And so the solution is just rename Perms.DLL in Perms.dll
294       and do pp -o my.exe my.pl ... and everything goes right.
295
296   Under Win32, a pp packed executable has trouble executing other perl
297       scripts or pp packed executable
298       Note: Is this still current?
299
300       When running on a Win32 system, if a perl script is packed with pp and
301       invokes another Perl script or pp packed executable, either with
302       system() or backticks, the invoked program runs with the copy of
303       perl5x.dll already loaded into memory. If the calling executable was
304       packed with "pp -d", the perl5x.dll is the one from the installed perl
305       bin directory. Otherwise, it is the one packed with the executable. The
306       perl5x.dll from the bin dir knows the @INC paths for the installed
307       libraries; the one in the executable does not. Because of this, a
308       program packed without "-d" calling a program with packed with "-d" or
309       calling perl.exe to run a plain Perl script may fail. This is a Win32
310       limitation.
311
312   How can I make a .exe that runs with no console window under Windows?
313       Use the --gui switch, ie
314
315           % pp --gui -o file.exe file.pl
316
317       I found that this is not documented on all versions of pp ... Some
318       versions have a more complete doc than others when you type "pp -h"
319       etc. (This should be reasonably documented now.)
320
321       When searching for an answer to this myself, I found many references to
322       using "exetype" ... it comes as a .bat with ActivePerl, or you can find
323       an exetype.pl from several places. You run "exetype file.exe
324       [WINDOWS|CONSOLE]". This worked, I think, but still did not achieve the
325       desired result on my PAR executable. While the exe itself did not
326       generate a console window, par.exe (which was invoked in my exe
327       somewhere) DID generate a console window, with a titlebar saying
328       "par.exe <strange-looking path to file in temp dir>", whereas before
329       changing the console window title bar just displayed the path to my
330       .exe.
331
332   How can I change the icon of the generated .exe file under Windows?
333       There is another not-completely-documented switch that only works on
334       windows, --icon MyIcon.ico. So just use this:
335
336           % pp --icon "c:\path to\MyIcon.ico" -o file.exe file.pl.
337
338       (This should also be documented now?)
339
340   The command line parameters (@ARGV) of a pp-ed binary called from another
341       pp-ed binary are missing or broken. What the...?
342       This was a bug in releases up to and including PAR-0.90. Please upgrade
343       to PAR 0.91 or later and the problem will go away.
344
345   I want to include a pp-ed binary in an RPM package. How can I make this
346       work?
347       The binary executables outputted by pp (on Linux) are not valid ELF
348       binaries because it basically attaches a zip archive to the binary
349       loader and does not modify the ELF headers to reflect that. When
350       building an RPM archive, the validity of the ELF headers is checked by
351       default. This can result in problems when packaging pp-ed binaries in
352       RPM archives.
353
354       Scott McBrien helped track down what can be done to get this to work:
355
356         [I]t appears that the RPM archive that is generated gets a list of
357         the MD5 sums for components of the executable file calculated by
358         prelink.  By disabling prelink, it fixed the problem; in my RPM .spec
359         file:
360         %define         __prelink_undo_cmd     %{nil}
361
362       After quite some time, it seems like the smart folks at Redhat found
363       the culprit. I'm glad *they* did, because I wouldn't have:
364
365         It appears that we found a solution that works. It like the pp
366         executables are already stripped, so we don't want rpm stripping them
367         again, which, of course, renders them useless.
368
369         In this case, we added the following lines to the spec file to keep rpm
370         from running the strip process and not produce debuginfo packages:
371
372         %define __spec_install_post :
373         %define debug_package %{nil}
374
375         Don't forget to add the ":" character to __spec_install_post as above or
376         this won't work.
377
378       Much praise to all who helped track this down! The discussion can be
379       found in the following RT tickets:
380       <http://rt.cpan.org/Public/Bug/Display.html?id=18536|#18536> and
381       <http://rt.cpan.org/Public/Bug/Display.html?id=19609|#19609>.
382
383       -- Steffen Mueller, 22 July 2006
384
385   How can I package Wx applications?
386       Have a look at the separately maintained Wx::Perl::Packager module.
387
388       -- Steffen Mueller, 3 July 2006
389
390   How can I package Catalyst web applications?
391       Catalyst has some builtin PAR support. I found the following URL to be
392       very helpful:
393
394       <http://catalyst.infogami.com/cookbook/par>.
395
396       -- Steffen Mueller, 21 July 2006
397
398   The resulting files are huge! How can I reduce the size of the output file?
399       The executables generated by pp generally contain a copy of your Perl
400       shared libraries, the Perl core modules and any module dependencies
401       your packaged application may have. That is a lot. Sometimes, PAR
402       packages too much. It adheres to the philosophy of rather making the
403       application work than generating a streamlined executable. If you want
404       to optimize this, you will have to do so by excluding specific modules.
405
406       Chris Dolan's recent post to the PAR mailing list explains this well.
407       Quoting Chris: (<http://www.nntp.perl.org/group/perl.par/2490>)
408
409         [...]
410         I've found a few tricks that can help a lot:
411
412         * If you know the target platform has Perl pre-installed (e.g. Mac OS X)
413           then use the "--dependent" flag. This skips all of the core modules,
414           yielding a much smaller executable.
415
416           One significant caveat is moving to older systems.  For example,
417           Mac OS X 10.2 had Perl 5.6.0 which has 146 fewer core modules than
418           Perl 5.8.6 which shipped with Mac OS X 10.4, and (even more significantly)
419           is binary-incompatible with any extra XS modules added from CPAN.
420           Other platforms can be even harder to predict.
421
422         * Watch for modules that pull in lots of dependencies
423
424           A good example is DBI.  If your program uses DBI, then Module::ScanDeps
425           pulls in ALL of the DBD::* modules (some of which are large) installed on
426           your system, because it cannot realistically parse the DBI->connect()
427           arguments which specify which database drivers are actually needed.
428           In one of my MySQL-based applications, I use this invocation of PAR:
429
430             pp -X DBD::SQLite -X DBD::CSV -X DBD::File -X DBD::Excel
431
432           which saves quite a few bytes, because both DBD::SQLite and DBD::Excel
433           have lots of CPAN dependencies.  The actual list if DBD::* modules you
434           need to exclude depends on your system.  Here's a short command that will
435           reveal all DBD::* modules on a unix-like system:
436
437             perl -MModule::ScanDeps -le'print for map {"DBD/".$_->{name}} Module::ScanDeps::_glob_in_inc("DBD")'
438
439           Another smaller example is SOAP::Transport::* where most installations
440           only need SOAP::Transport::HTTP.
441           [...]
442
443       Similar techniques can be applied when a module makes use of
444       Module::Pluggable for plugins.
445
446       Finally, there is a PAR filter available as a separate distribution on
447       CPAN which compresses the source code as much as possible by first
448       parsing it using PPI and then spitting out a reduced functional
449       equivalent: PAR::Filter::Squish.
450
451       -- Steffen Mueller, August 2006
452
453   How do I use Win32::GUI::SplashScreen with PAR?
454       When using pp to package an application that uses
455       Win32::GUI::SplashScreen, try adding the splashscreen bitmap manually
456       as suggested in the Win32::GUI::SplashScreen docs:
457
458         pp -a SPLASHFILE.bmp -o xxx.exe xxx.pl
459
460   The Perl Packager scripts says that it can create executable that runs in
461       same OS. Can I use it to create Win32 binary with linux machine? Or
462       what should I use to create Win32 executable binary on linux from my
463       script?
464       It is not possible to create stand-alone binaries for different
465       platform than what you are currently running on. This is a generally
466       hard problem since you would have to cross-compile all XS modules and
467       perl itself. Not nice.
468
469       For example, if you would like to develop an application on Linux and
470       ship it for both Linux/x86 and Win32/x86, it works well to set up a
471       Virtual Machine with a Windows (XP or 2000 or whatever) and a Perl
472       installation. On that machine, use PAR/pp to package your application
473       for Win32.
474
475       See also the question "On what platforms can I run PAR? On what
476       platforms will the resulting executable run?".
477
478       -- Steffen Mueller, 2 November 2006
479

SEE ALSO

481       PAR, PAR::Tutorial
482

AUTHORS

484       Audrey Tang <cpan@audreyt.org>, Steffen Mueller <smueller@cpan.org>
485
486       You can write to the mailing list at <par@perl.org>, or send an empty
487       mail to <par-subscribe@perl.org> to participate in the discussion.
488
489       Please submit bug reports to <bug-par@rt.cpan.org>.
490
492       Copyright 2003-2008 by Audrey Tang <cpan@audreyt.org>.
493
494       This document is free documentation; you can redistribute it and/or
495       modify it under the same terms as Perl itself.
496
497       See LICENSE.
498
499
500
501perl v5.30.1                      2020-01-30                       PAR::FAQ(3)
Impressum