PAR(3pm) - f38

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 @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_GLOBAL_CLEAN is specified,
181           set PAR_GLOBAL_TEMP to "TEMP/par-USERHEX/temp-PID/", cleaning it
182           after execution.
183
184       •   If both are not set,  use "TEMP/par-USERHEX/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       •   USERHEX is derived from the user name, or SYSTEM if none can be
195           found.  On Win32, this is $Win32::LoginName.  On Unix, this is
196           $ENV{USERNAME} or $ENV{USER}.  Encode the raw bytes of the user
197           name each as two hex digits to obtain USERHEX.
198
199       •   PID is the process ID.  Forked children use the parent's PID.
200
201       •   HASH is a crypto-hash of the entire par file or executable,
202           calculated at creation time.  This value can be overloaded with
203           "pp"'s --tempdir parameter.
204
205       By default, PAR strips POD sections from bundled modules. In case that
206       causes trouble, you can turn this off by setting the environment
207       variable "PAR_VERBATIM" to 1.
208
209   import options
210       When you "use PAR {...}" or call PAR->import({...}), the following
211       options are available.
212
213         PAR->import({ file => 'foo.par' });
214         # or
215         PAR->import({ repository => 'http://foo/bar/' });
216
217       file
218           The par filename.
219
220           You must pass one option of either 'file' or 'repository'.
221
222       repository
223           A par repository (exclusive of file)
224
225       fallback
226           Search the system @INC before the par.
227
228           Off by default for loading .par files via "file =" ...>.  On by
229           default for PAR repositories.
230
231           To prefer loading modules from a repository over the locally
232           installed modules, you can load the repository as follows:
233
234             use PAR { repository => 'http://foo/bar/', fallback => 0 };
235
236       run The name of a script to run in the par.  Exits when done.
237
238       no_shlib_unpack
239           Skip unpacking bundled dynamic libraries from shlib/$archname.  The
240           client may have them installed, or you may wish to cache them
241           yourself.  In either case, they must end up in the standard install
242           location (such as /usr/local/lib/) or in $ENV{PAR_TEMP} before you
243           require the module which needs them.  If they are not accessible
244           before you require the dependent module, perl will die with a
245           message such as "cannot open shared object file..."
246

ACKNOWLEDGMENTS

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

AUTHORS

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

COPYRIGHT

297       Copyright 2002-2010 by Audrey Tang <cpan@audreyt.org>.  Copyright
298       2005-2010 by Steffen Mueller <smueller@cpan.org>
299
300       This program is free software; you can redistribute it and/or modify it
301       under the same terms as Perl itself.
302
303       See LICENSE.
304
305
306
307perl v5.36.0                      2023-01-20                            PAR(3)