1PAR::Environment(3) User Contributed Perl Documentation PAR::Environment(3)
2
6 PAR::Environment - Index and reference of PAR environment variables
7
9 PAR uses various environment variables both during the building process
10 of executables or PAR archives and the use of them. Since the wealth of
11 combinations and settings might confuse one or the other (like me),
12 this document is intended to document all environment variables which
13 PAR uses.
14 Wherever I want to refer to the $ENV{FOO} environment hash entry, I
16 will usually talk about the "FOO" variable for brevity.
17
19 Please note that this is still very, very incomplete! Contributions
20 welcome!
21 For each variable, there should be a description what it contains, when
23 it can be expected to exist (and contain meaningful information), when
24 it is sensible to define it yourself, and what effect this has.
25 Of course, the description may use examples.
27 PAR_0
29 If the running program is run from within a PAR archive or pp-produced
30 executable, this variable contains the name of the extracted program
31 (i.e. .pl file). This is useful of you want to open the source code
32 file of the running program.
33 For example, if you package a file foo.pl into bar.par and run foo.pl
35 with this command
36 par.pl foo.par bar.pl
38 then the "PAR_0" variable will contain something like
40 "/tmp/par-youser/cache-b175f53eb731da9594e0dde337d66013ddf25a44/495829f0.pl"
41 where "youser" is your username and
42 "/tmp/par-youser/cache-b175f53eb731da9594e0dde337d66013ddf25a44/" is
43 the PAR cache directory ("PAR_TEMP").
44 The name of the PAR cache directory can take a number of different
46 forms, so use "PAR_0" if you want to find the extracted program's .pl
47 file -- attempting to construct the name yourself requires complex
48 logic that has already produced the value in "PAR_0".
49 This works the same for executable binaries (.exe, ...).
51 If you are looking for the name and path of the pp-ed binary file,
53 please refer to the "PAR_PROGNAME" variable.
54 PAR_ARGC, PAR_ARGV_0, PAR_ARGV_...
56 You should not rely on these variables outside of the PAR binary loader
57 code.
58 These variables are set when a non-dependent pp-ed binary executable
60 runs. The initially executed process extracts another binary and runs
61 it as a child process. In order to pass its command line arguments to
62 the child, the parent process sets "PAR_ARG*" as they would be used in
63 C programs: "PAR_ARGC" has the number of arguments, "PAR_ARGV_0" has
64 the name of the executable, "PAR_ARGV_*" are the command line
65 arguments.
66 If you would like to access the name of the running program (script or
68 binary), please refer to "PAR_0" and "PAR_PROGNAME" instead!
69 Related: "PAR_SPAWNED", "PAR_0", "PAR_PROGNAME"
71 PAR_CLEAN
73 Users should set "PAR_GLOBAL_CLEAN" instead. Recreated from
74 "PAR_GLOBAL_CLEAN" and the value of "-C" from the YAML file by the PAR
75 loader, and used within loader to control the initial behavior of
76 extraction, and the final behavior of cleanup. The user can reference
77 "PAR_CLEAN" in the application to determine which of these behaviors is
78 being used for this run of the application.
79 PAR_DEBUG
81 Users should set "PAR_GLOBAL_DEBUG" instead.
82 If this variable is set to a true value and par.pl is run, verbose
84 output is sent to STDOUT or the logging filehandle. This is overridden
85 by the "-q" option to par.pl, for steps after argument parsing occurs.
86 This currently only influences par.pl. Whether this is the intended
88 behaviour remains to be verified.
89 PAR_GLOBAL_CLEAN
91 Setting "PAR_GLOBAL_CLEAN" alters the behavior of par applications
92 which see that environment variable at launch. "PAR_GLOBAL_CLEAN"
93 overrides the "-C" option. Settings of 0 and 1 are supported. 0
94 corresponds to not using "-C" on the pp command line; 1 corresponds to
95 using "-C" on the pp command line. "PAR_GLOBAL_CLEAN" is ignored if
96 "PAR_GLOBAL_TEMP" is set, yet it controls the form of "PAR_TEMP" when
97 "PAR_GLOBAL_TEMP" is not set.
98 PAR_GLOBAL_DEBUG
100 The PAR loader becomes more verbose when "PAR_DEBUG" is set. Setting
101 "PAR_GLOBAL_DEBUG" guarantees that "PAR_DEBUG" will be set internally,
102 initially. See "PAR_DEBUG" for more details.
103 PAR_GLOBAL_TEMP
105 Contributes to the calculation of "PAR_TEMP", and is further explained
106 there.
107 PAR_GLOBAL_TMPDIR
109 Contributes to the calculation of "PAR_TEMP", and is further explained
110 there.
111 PAR_INITIALIZED
113 This environment variable is for internal use by the PAR binary loader
114 only. Documented only to avoid surprises if spawned applications
115 expect to see a value initialized by the user.
116 PAR_PROGNAME
118 "PAR_PROGNAME" is set to the fully-qualified path name of the
119 executable program. On Windows, this is reliably obtained from the
120 "GetModuleFileName" API. On other OSes, if the C runtime is given a
121 qualified path name, it is used, or the unqualified file name given is
122 qualified by walking the path. This is reasonably reliable given
123 normal program spawning conventions, but cannot be guaranteed to be
124 correct in all circumstances.
125 PAR_APP_REUSE
127 Strictly internal. Skip this section if you're not a PAR developer.
128 The variable shouldn't ever be exposed to user code and packaged
130 applications should not depend on it being set or not.
131 If an application has been packaged with the "--reusable" option, the
133 bootstrapping code will set this environment variable to the name of
134 the program that is to be run instead of the packaged program. The
135 main.pl loader script fetches the file name, deletes the environment
136 variable, and then runs the given program.
137 PAR_RUN
139 This environment variable was set during constructions of "PAR::Packer"
140 objects (usually during pp runs only) by versions of PAR up to 0.957.
141 Since PAR 0.958, this variable is unused.
142 PAR_SPAWNED
144 This variable is used internally by the parl binary loader to signal
145 the child process that it's the child.
146 You should not rely on this variable outside of the PAR binary loader
148 code. For a slightly more detailed discussion, please refer to the
149 who_am_i.txt documentation file in the PAR source distribution which
150 was contributed by Alan Stewart. Related: "PAR_ARGC", "PAR_ARGV_*"
151 Documented only to avoid surprises if spawned applications expect to
153 see a value initialized by the user.
154 PAR_TEMP
156 Users should set "PAR_GLOBAL_TEMP" instead. "PAR_TEMP" is calculated
157 from a variety of other variables. See the "NOTES" section in the pod
158 for PAR.pm for a complete description of how the calculation proceeds.
159 "PAR_TEMP", once calculated, is used as the location where PAR stores
160 its extracted, temporary file cache.
161 PAR_TMPDIR
163 Contributes to the calculation of "PAR_TEMP", and is further explained
164 there. Users should set "PAR_GLOBAL_TMPDIR" instead.
165 PAR_VERBATIM
167 The "PAR_VERBATIM" variable controls the way Perl code is packaged into
168 a PAR archive or binary executable. If it is set to a true value during
169 the packaging process, modules (and scripts) are not passed through the
170 default "PAR::Filter::PodStrip" filter which removes all POD
171 documentation from the code. Note that the "PAR::Filter::PatchContent"
172 filter is still applied.
173 The "-F" option to the pp tool overrides the "PAR_VERBATIM" setting.
175 That means if you set "PAR_VERBATIM=1" but specify "-F PodStrip" on the
176 "pp" command line, the "PodStrip" filter will be applied.
177 "PAR_VERBATIM" is not used by the PAR application.
179 PAR_VERBOSE
181 Setting this environment variable to a positive integer has the same
182 effect as using the "-verbose" switch to pp.
183 PP_OPTS
185 During a pp run, the contents of the "PP_OPTS" variable are treated as
186 if they were part of the command line. In newer versions of PAR, you
187 can also write options to a file and execute pp as follows to read the
188 options from the file:
189 pp @FILENAME
191 That can, of course, be combined with other command line arguments to
193 pp or the "PP_OPTS" variable.
194 TMP, TEMP, TMPDIR, TEMPDIR
196 Please refer to "PAR_TMPDIR".
197
199 The PAR homepage at <http://par.perl.org>.
200 PAR, PAR::Tutorial, PAR::FAQ (For a more current FAQ, refer to the
202 homepage.)
203 par.pl, parl, pp
205 PAR::Dist for details on PAR distributions.
207
209 Steffen Mueller <smueller@cpan.org>
210 <http://par.perl.org/> is the official PAR website. You can write to
212 the mailing list at <par@perl.org>, or send an empty mail to
213 <par-subscribe@perl.org> to participate in the discussion.
214 Please submit bug reports to <bug-par@rt.cpan.org>. If you need
216 support, however, joining the <par@perl.org> mailing list is preferred.
217
219 PAR: Copyright 2003-2010 by Audrey Tang, <cpan@audreyt.org>.
220 This document: Copyright 2006-2010 by Steffen Mueller,
222 <smueller@cpan.org>
223 Some information has been taken from Alan Stewart's extra documentation
225 in the contrib/ folder of the PAR distribution.
226 This program or documentation is free software; you can redistribute it
228 and/or modify it under the same terms as Perl itself.
229 See <http://www.perl.com/perl/misc/Artistic.html>
231perl v5.12.1 2010-04-10 PAR::Environment(3)