PAR(3pm) - f14

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

NAME

6       PAR - Perl Archive Toolkit
7

SYNOPSIS

9       (If you want to make an executable that contains all module, scripts
10       and data files, please consult the pp utility instead. pp used to be
11       part of the PAR distribution but is now shipped as part of the
12       PAR::Packer distribution instead.)
13
14       Following examples assume a foo.par file in Zip format.
15
16       To use Hello.pm from ./foo.par:
17
18           % perl -MPAR=./foo.par -MHello
19           % perl -MPAR=./foo -MHello          # the .par part is optional
20
21       Same thing, but search foo.par in the @INC;
22
23           % perl -MPAR -Ifoo.par -MHello
24           % perl -MPAR -Ifoo -MHello          # ditto
25
26       Following paths inside the PAR file are searched:
27
28           /lib/
29           /arch/
30           /i386-freebsd/              # i.e. $Config{archname}
31           /5.8.0/                     # i.e. $Config{version}
32           /5.8.0/i386-freebsd/        # both of the above
33           /
34
35       PAR files may also (recursively) contain other PAR files.  All files
36       under following paths will be considered as PAR files and searched as
37       well:
38
39           /par/i386-freebsd/          # i.e. $Config{archname}
40           /par/5.8.0/                 # i.e. $Config{version}
41           /par/5.8.0/i386-freebsd/    # both of the above
42           /par/
43
44       Run script/test.pl or test.pl from foo.par:
45
46           % perl -MPAR foo.par test.pl        # only when $0 ends in '.par'
47
48       However, if the .par archive contains either script/main.pl or main.pl,
49       then it is used instead:
50
51           % perl -MPAR foo.par test.pl        # runs main.pl; @ARGV is 'test.pl'
52
53       Use in a program:
54
55           use PAR 'foo.par';
56           use Hello; # reads within foo.par
57
58           # PAR::read_file() returns a file inside any loaded PARs
59           my $conf = PAR::read_file('data/MyConfig.yaml');
60
61           # PAR::par_handle() returns an Archive::Zip handle
62           my $zip = PAR::par_handle('foo.par')
63           my $src = $zip->memberNamed('lib/Hello.pm')->contents;
64
65       You can also use wildcard characters:
66
67           use PAR '/home/foo/*.par';  # loads all PAR files in that directory
68
69       Since version 0.950, you can also use a different syntax for loading
70       .par archives:
71
72           use PAR { file => 'foo.par' }, { file => 'otherfile.par' };
73
74       Why? Because you can also do this:
75
76           use PAR { file => 'foo.par, fallback => 1 };
77           use Foo::Bar;
78
79       Foo::Bar will be searched in the system libs first and loaded from
80       foo.par if it wasn't found!
81
82           use PAR { file => 'foo.par', run => 'myscript' };
83
84       This will load foo.par as usual and then execute the script/myscript
85       file from the archive. Note that your program will not regain control.
86       When script/myscript exits, so does your main program. To make this
87       more useful, you can defer this to runtime: (otherwise equivalent)
88
89           require PAR;
90           PAR->import( { file => 'foo.par', run => 'myscript' } );
91
92       If you have PAR::Repository::Client installed, you can do this:
93
94           use PAR { repository => 'http://foo/bar/' };
95           use Module; # not locally installed!
96
97       And PAR will fetch any modules you don't have from the specified PAR
98       repository. For details on how this works, have a look at the SEE ALSO
99       section below. Instead of an URL or local path, you can construct an
100       PAR::Repository::Client object manually and pass that to PAR.  If you
101       specify the "install => 1" option in the "use PAR" line above, the
102       distribution containing "Module" will be permanently installed on your
103       system. ("use PAR { repository => 'http://foo/bar', install => 1 };")
104
105       Furthermore, there is an "upgrade => 1" option that checks for upgrades
106       in the repository in addition to installing. Please note that an
107       upgraded version of a module is only loaded on the next run of your
108       application.
109
110       Adding the "dependencies => 1" option will enable
111       PAR::Repository::Client's static dependency resolution
112       (PAR::Repository::Client 0.23 and up).
113
114       Finally, you can combine the "run" and "repository" options to run an
115       application directly from a repository! (And you can add the "install"
116       option, too.)
117
118         use PAR { repository => 'http://foo/bar/', run => 'my_app' };
119         # Will not reach this point as we executed my_app,
120

DESCRIPTION

122       This module lets you use special zip files, called Perl Archives, as
123       libraries from which Perl modules can be loaded.
124
125       It supports loading XS modules by overriding DynaLoader bootstrapping
126       methods; it writes shared object file to a temporary file at the time
127       it is needed.
128
129       A .par file is mostly a zip of the blib/ directory after the build
130       process of a CPAN distribution. To generate a .par file yourself, all
131       you have to do is compress the modules under arch/ and lib/, e.g.:
132
133           % perl Makefile.PL
134           % make
135           % cd blib
136           % zip -r mymodule.par arch/ lib/
137
138       Afterward, you can just use mymodule.par anywhere in your @INC, use
139       PAR, and it will Just Work. Support for generating .par files is going
140       to be in the next (beyond 0.2805) release of Module::Build.
141
142       For convenience, you can set the "PERL5OPT" environment variable to
143       "-MPAR" to enable "PAR" processing globally (the overhead is small if
144       not used); setting it to "-MPAR=/path/to/mylib.par" will load a
145       specific PAR file.  Alternatively, consider using the par.pl utility
146       bundled with the PAR::Packer distribution, or using the self-contained
147       parl utility which is also distributed with PAR::Packer on machines
148       without PAR.pm installed.
149
150       Note that self-containing scripts and executables created with par.pl
151       and pp may also be used as .par archives:
152
153           % pp -o packed.exe source.pl        # generate packed.exe (see PAR::Packer)
154           % perl -MPAR=packed.exe other.pl    # this also works
155           % perl -MPAR -Ipacked.exe other.pl  # ditto
156
157       Please see "SYNOPSIS" for most typical use cases.
158

NOTES

160       Settings in META.yml packed inside the PAR file may affect PAR's
161       operation.  For example, pp provides the "-C" ("--clean") option to
162       control the default behavior of temporary file creation.
163
164       Currently, pp-generated PAR files may attach four PAR-specific
165       attributes in META.yml:
166
167           par:
168             clean: 0          # default value of PAR_CLEAN
169             signature: ''     # key ID of the SIGNATURE file
170             verbatim: 0       # was packed prerequisite's PODs preserved?
171             version: x.xx     # PAR.pm version that generated this PAR
172
173       User-defined environment variables, like PAR_GLOBAL_CLEAN, always
174       overrides the ones set in META.yml.  The algorithm for generating
175       caching/temporary directory is as follows:
176
177       ·   If PAR_GLOBAL_TEMP is specified, use it as the cache directory for
178           extracted libraries, and do not clean it up after execution.
179
180       ·   If PAR_GLOBAL_TEMP is not set, but PAR_CLEAN is specified, set
181           PAR_GLOBAL_TEMP to "TEMP/par-USER/temp-PID/", cleaning it after
182           execution.
183
184       ·   If both are not set,  use "TEMP/par-USER/cache-HASH/" as the
185           PAR_GLOBAL_TEMP, reusing any existing files inside.
186
187       Here is a description of the variables the previous paths.
188
189       ·   TEMP is a temporary directory, which can be set via
190           $ENV{PAR_GLOBAL_TMPDIR}, $ENV{TMPDIR}, $ENV{TEMPDIR}, $ENV{TEMP} or
191           $ENV{TMP}, in that order of priority.  If none of those are set,
192           C:\TEMP, /tmp are checked.  If neither of them exists, . is used.
193
194       ·   USER is the user name, or SYSTEM if none can be found.  On Win32,
195           this is $Win32::LoginName.  On Unix, this is $ENV{USERNAME} or
196           $ENV{USER}.
197
198       ·   PID is the process ID.  Forked children use the parent's PID.
199
200       ·   HASH is a crypto-hash of the entire par file or executable,
201           calculated at creation time.  This value can be overloaded with
202           "pp"'s --tempdir parameter.
203
204       By default, PAR strips POD sections from bundled modules. In case that
205       causes trouble, you can turn this off by setting the environment
206       variable "PAR_VERBATIM" to 1.
207
208   import options
209       When you "use PAR {...}" or call PAR->import({...}), the following
210       options are available.
211
212         PAR->import({ file => 'foo.par' });
213         # or
214         PAR->import({ repository => 'http://foo/bar/' });
215
216       file
217           The par filename.
218
219           You must pass one option of either 'file' or 'repository'.
220
221       repository
222           A par repository (exclusive of file)
223
224       fallback
225           Search the system @INC before the par.
226
227           Off by default for loading .par files via "file =" ...>.  On by
228           default for PAR repositories.
229
230           To prefer loading modules from a repository over the locally
231           installed modules, you can load the repository as follows:
232
233             use PAR { repository => 'http://foo/bar/', fallback => 0 };
234
235       run The name of a script to run in the par.  Exits when done.
236
237       no_shlib_unpack
238           Skip unpacking bundled dynamic libraries from shlib/$archname.  The
239           client may have them installed, or you may wish to cache them
240           yourself.  In either case, they must end up in the standard install
241           location (such as /usr/local/lib/) or in $ENV{PAR_TEMP} before you
242           require the module which needs them.  If they are not accessible
243           before you require the dependent module, perl will die with a
244           message such as "cannot open shared object file..."
245

ACKNOWLEDGMENTS

273       Nicholas Clark for pointing out the mad source filter hook within the
274       (also mad) coderef @INC hook, as well as (even madder) tricks one can
275       play with PerlIO to avoid source filtering.
276
277       Ton Hospel for convincing me to ditch the "Filter::Simple"
278       implementation.
279
280       Uri Guttman for suggesting "read_file" and "par_handle" interfaces.
281
282       Antti Lankila for making me implement the self-contained executable
283       options via "par.pl -O".
284
285       See the AUTHORS file in the distribution for a list of people who have
286       sent helpful patches, ideas or comments.
287

AUTHORS

289       Audrey Tang <cpan@audreyt.org>
290
291       Steffen Mueller <smueller@cpan.org>
292
293       <http://par.perl.org/> is the official PAR website.  You can write to
294       the mailing list at <par@perl.org>, or send an empty mail to
295       <par-subscribe@perl.org> to participate in the discussion.
296
297       Please submit bug reports to <bug-par@rt.cpan.org>. If you need
298       support, however, joining the <par@perl.org> mailing list is preferred.
299

COPYRIGHT

301       Copyright 2002-2010 by Audrey Tang <cpan@audreyt.org>.  Copyright
302       2005-2010 by Steffen Mueller <smueller@cpan.org>
303
304       This program is free software; you can redistribute it and/or modify it
305       under the same terms as Perl itself.
306
307       See <http://www.perl.com/perl/misc/Artistic.html>
308
309
310
311perl v5.12.1                      2010-04-10                            PAR(3)