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 added a directory to my PAR file using "zip -r" or winzip, and then
178       generated an executable from this PAR file, and the executable failed
179       to run (IO error: reading header signature :..). What's wrong?
180       As pointed out by Alan Stewart, zip adds a directory entry for the new
181       directory, and it causes the PAR executable to fail. Just use :
182
183         zip -r -D hello.par my_dir/
184
185       or the Archive::Zip::addTree as follows :
186
187         $zip->addTree( $root, $dest, sub { -f } )
188
189   On what platforms can I run PAR? On what platforms will the resulting
190       executable run?
191       Win32 (95/98/ME/NT4/2K/XP), FreeBSD, Linux, AIX, Solaris, Darwin and
192       Cygwin.
193
194       The resulting executable will run on any platforms that supports the
195       binary format of the generating platform.
196
197   How do I extract my script out of packed executable?
198       In other words, "I did a `pp foo.pl' and I lost foo.pl, how do I get it
199       back?".
200
201       The answer is to just use unzip/winzip/winrar/whatever to decompress
202       the executable, treating it like a normal Zip file. You may need to
203       rename the executable into a .zip extension first.
204
205   Can PAR completely hide my source code?
206       Not completely, but possible to a degree. Starting from version 0.76,
207       PAR supports an input filter mechanism, which can be used to implement
208       source obfuscators (or even product activation schemes).
209
210       But if you are looking for 100% bulletproof way of hiding source code,
211       it is not possible with any language. Learning Perl, 3rd Edition has
212       this answer to offer (quoted with permission from Randal Schwartz):
213
214       If you're wishing for an opaque binary, though, we have to tell you
215       that they don't exist. If someone can install and run your program,
216       they can turn it back into source code. Granted, this won't necessarily
217       be the same source that you started with, but it will be some kind of
218       source code. The real way to keep your secret algorithm a secret is,
219       alas, to apply the proper number of attorneys; they can write a license
220       that says "you can do this with the code, but you can't do that. And if
221       you break our rules, we've got the proper number of attorneys to ensure
222       that you'll regret it."
223
224       Other than that, I would point you at PAR::Filter::Crypto. Be sure to
225       read the CAVEATS and WARNINGS sections of the documentation.
226
227   On Windows XP, pp crashes saying that "par.exe has encountered a problem"
228       This is believed to be fixed by PAR 0.76_99. The following answer
229       applies to PAR 0.76 and earlier:
230
231       You may be able to escape this problem by setting some executables to
232       Windows 95 compatibility mode. Specifically, find "parl.exe" (probably
233       in "C:\perl\5.8.0\bin") using Windows Explorer, and right-click on it
234       and choose "Properties". Choose the "Compatibility" tab and tick the
235       box for "Run this program with compatibility mode for" and check that
236       the dropdown shows "Windows 95". Then click OK.
237
238       Now you can hopefully run pp as normal to generate an EXE. Before you
239       can run the generated EXE, you'll need to set its compatibility mode
240       too, in the same way as you did for parl.exe.
241
242       This workaround is known not to work in all cases, and the developers
243       are working on a solution to the problem. See these posts for more
244       info:
245
246       <http://www.mail-archive.com/par@perl.org/msg00423.html>,
247       <http://www.mail-archive.com/par@perl.org/msg00435.html>,
248       <http://www.mail-archive.com/par@perl.org/msg00573.html>,
249       <http://www.mail-archive.com/par@perl.org/msg00670.html>
250
251   Perl Tk tips
252       On Windows XP start your script with
253
254         use strict; use Encode::Unicode; use Tk;
255
256       Some widgets use xbm bitmaps which don't get picked up by PAR. The
257       error is:
258
259         couldn't read bitmap file "": No such file or directory
260         error reading bitmap file "" at Tk/Widget.pm line 205.
261         at Tk/Widget.pm line 203
262
263       Fix is to find the missing xbm files (perl -V tells you where to start
264       looking) and add them to the executable eg
265
266       copy missing xbm files to script directory then:
267
268           % pp --add cbxarrow.xbm --add arrowdownwin.xbm -o test test.pl
269
270   Problem with Win32::Perms and Perms.DLL
271       With a script my.pl using Win32::Perms, pp -o my.exe my.pl you may
272       have:
273
274         Can't locate loadable object for module Win32::Perms in @INC
275         (@INC contains: CODE(0xb97eec) CODE(0xc8a99c) .)
276         at ../blib/lib/PAR/Heavy.pm line 78
277
278       In fact the dll is Perms.DLL wit DLL in capital letters. That's the
279       problem. The bootstrap function of PAR in the Dynaloader module fails
280       looking for Perms.dll in the table of dlls which contains only
281       Perms.DLL. And so the solution is just rename Perms.DLL in Perms.dll
282       and do pp -o my.exe my.pl ... and everything goes right.
283
284   Under Win32, a pp packed executable has trouble executing other perl
285       scripts or pp packed executable
286       Note: Is this still current?
287
288       When running on a Win32 system, if a perl script is packed with pp and
289       invokes another Perl script or pp packed executable, either with
290       system() or backticks, the invoked program runs with the copy of
291       perl5x.dll already loaded into memory. If the calling executable was
292       packed with "pp -d", the perl5x.dll is the one from the installed perl
293       bin directory. Otherwise, it is the one packed with the executable. The
294       perl5x.dll from the bin dir knows the @INC paths for the installed
295       libraries; the one in the executable does not. Because of this, a
296       program packed without "-d" calling a program with packed with "-d" or
297       calling perl.exe to run a plain Perl script may fail. This is a Win32
298       limitation.
299
300   How can I make a .exe that runs with no console window under Windows?
301       Use the --gui switch, ie
302
303           % pp --gui -o file.exe file.pl
304
305       I found that this is not documented on all versions of pp ... Some
306       versions have a more complete doc than others when you type "pp -h"
307       etc. (This should be reasonably documented now.)
308
309       When searching for an answer to this myself, I found many references to
310       using "exetype" ... it comes as a .bat with ActivePerl, or you can find
311       an exetype.pl from several places. You run "exetype file.exe
312       [WINDOWS|CONSOLE]". This worked, I think, but still did not achieve the
313       desired result on my PAR executable. While the exe itself did not
314       generate a console window, par.exe (which was invoked in my exe
315       somewhere) DID generate a console window, with a titlebar saying
316       "par.exe <strange-looking path to file in temp dir>", whereas before
317       changing the console window title bar just displayed the path to my
318       .exe.
319
320   The command line parameters (@ARGV) of a pp-ed binary called from another
321       pp-ed binary are missing or broken. What the...?
322       This was a bug in releases up to and including PAR-0.90. Please upgrade
323       to PAR 0.91 or later and the problem will go away.
324
325   I want to include a pp-ed binary in an RPM package. How can I make this
326       work?
327       The binary executables outputted by pp (on Linux) are not valid ELF
328       binaries because it basically attaches a zip archive to the binary
329       loader and does not modify the ELF headers to reflect that. When
330       building an RPM archive, the validity of the ELF headers is checked by
331       default. This can result in problems when packaging pp-ed binaries in
332       RPM archives.
333
334       Scott McBrien helped track down what can be done to get this to work:
335
336         [I]t appears that the RPM archive that is generated gets a list of
337         the MD5 sums for components of the executable file calculated by
338         prelink.  By disabling prelink, it fixed the problem; in my RPM .spec
339         file:
340         %define         __prelink_undo_cmd     %{nil}
341
342       After quite some time, it seems like the smart folks at Redhat found
343       the culprit. I'm glad *they* did, because I wouldn't have:
344
345         It appears that we found a solution that works. It like the pp
346         executables are already stripped, so we don't want rpm stripping them
347         again, which, of course, renders them useless.
348
349         In this case, we added the following lines to the spec file to keep rpm
350         from running the strip process and not produce debuginfo packages:
351
352         %define __spec_install_post :
353         %define debug_package %{nil}
354
355         Don't forget to add the ":" character to __spec_install_post as above or
356         this won't work.
357
358       Much praise to all who helped track this down! The discussion can be
359       found in the following RT tickets:
360       <http://rt.cpan.org/Public/Bug/Display.html?id=18536|#18536> and
361       <http://rt.cpan.org/Public/Bug/Display.html?id=19609|#19609>.
362
363       -- Steffen Mueller, 22 July 2006
364
365   How can I package Wx applications?
366       Have a look at the separately maintained Wx::Perl::Packager module.
367
368       -- Steffen Mueller, 3 July 2006
369
370   How can I package Catalyst web applications?
371       Catalyst has some builtin PAR support. I found the following URL to be
372       very helpful:
373
374       <http://catalyst.infogami.com/cookbook/par>.
375
376       -- Steffen Mueller, 21 July 2006
377
378   The resulting files are huge! How can I reduce the size of the output file?
379       The executables generated by pp generally contain a copy of your Perl
380       shared libraries, the Perl core modules and any module dependencies
381       your packaged application may have. That is a lot. Sometimes, PAR
382       packages too much. It adheres to the philosophy of rather making the
383       application work than generating a streamlined executable. If you want
384       to optimize this, you will have to do so by excluding specific modules.
385
386       Chris Dolan's recent post to the PAR mailing list explains this well.
387       Quoting Chris: (<http://www.nntp.perl.org/group/perl.par/2490>)
388
389         [...]
390         I've found a few tricks that can help a lot:
391
392         * If you know the target platform has Perl pre-installed (e.g. Mac OS X)
393           then use the "--dependent" flag. This skips all of the core modules,
394           yielding a much smaller executable.
395
396           One significant caveat is moving to older systems.  For example,
397           Mac OS X 10.2 had Perl 5.6.0 which has 146 fewer core modules than
398           Perl 5.8.6 which shipped with Mac OS X 10.4, and (even more significantly)
399           is binary-incompatible with any extra XS modules added from CPAN.
400           Other platforms can be even harder to predict.
401
402         * Watch for modules that pull in lots of dependencies
403
404           A good example is DBI.  If your program uses DBI, then Module::ScanDeps
405           pulls in ALL of the DBD::* modules (some of which are large) installed on
406           your system, because it cannot realistically parse the DBI->connect()
407           arguments which specify which database drivers are actually needed.
408           In one of my MySQL-based applications, I use this invocation of PAR:
409
410             pp -X DBD::SQLite -X DBD::CSV -X DBD::File -X DBD::Excel
411
412           which saves quite a few bytes, because both DBD::SQLite and DBD::Excel
413           have lots of CPAN dependencies.  The actual list if DBD::* modules you
414           need to exclude depends on your system.  Here's a short command that will
415           reveal all DBD::* modules on a unix-like system:
416
417             perl -MModule::ScanDeps -le'print for map {"DBD/".$_->{name}} Module::ScanDeps::_glob_in_inc("DBD")'
418
419           Another smaller example is SOAP::Transport::* where most installations
420           only need SOAP::Transport::HTTP.
421           [...]
422
423       Similar techniques can be applied when a module makes use of
424       Module::Pluggable for plugins.
425
426       Finally, there is a PAR filter available as a separate distribution on
427       CPAN which compresses the source code as much as possible by first
428       parsing it using PPI and then spitting out a reduced functional
429       equivalent: PAR::Filter::Squish.
430
431       -- Steffen Mueller, August 2006
432
433   How do I use Win32::GUI::SplashScreen with PAR?
434       When using pp to package an application that uses
435       Win32::GUI::SplashScreen, try adding the splashscreen bitmap manually
436       as suggested in the Win32::GUI::SplashScreen docs:
437
438         pp -a SPLASHFILE.bmp -o xxx.exe xxx.pl
439
440   The Perl Packager scripts says that it can create executable that runs in
441       same OS. Can I use it to create Win32 binary with linux machine? Or
442       what should I use to create Win32 executable binary on linux from my
443       script?
444       It is not possible to create stand-alone binaries for different
445       platform than what you are currently running on. This is a generally
446       hard problem since you would have to cross-compile all XS modules and
447       perl itself. Not nice.
448
449       For example, if you would like to develop an application on Linux and
450       ship it for both Linux/x86 and Win32/x86, it works well to set up a
451       Virtual Machine with a Windows (XP or 2000 or whatever) and a Perl
452       installation. On that machine, use PAR/pp to package your application
453       for Win32.
454
455       See also the question "On what platforms can I run PAR? On what
456       platforms will the resulting executable run?".
457
458       -- Steffen Mueller, 2 November 2006
459

SEE ALSO

461       PAR, PAR::Tutorial
462

AUTHORS

464       Audrey Tang <cpan@audreyt.org>, Steffen Mueller <smueller@cpan.org>
465
466       You can write to the mailing list at <par@perl.org>, or send an empty
467       mail to <par-subscribe@perl.org> to participate in the discussion.
468
469       Please submit bug reports to <bug-par@rt.cpan.org>.
470
472       Copyright 2003-2008 by Audrey Tang <cpan@audreyt.org>.
473
474       This document is free documentation; you can redistribute it and/or
475       modify it under the same terms as Perl itself.
476
477       See LICENSE.
478
479
480
481perl v5.34.0                      2022-01-21                       PAR::FAQ(3)
Impressum