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_CLEAN
56 Users should set "PAR_GLOBAL_CLEAN" instead.
57 Recreated from "PAR_GLOBAL_CLEAN" and the value of "-C" from the YAML
59 file by the PAR loader, and used within loader to control the initial
60 behavior of extraction, and the final behavior of cleanup. The user
61 can reference "PAR_CLEAN" in the application to determine which of
62 these behaviors is being used for this run of the application.
63 PAR_DEBUG
65 Users should set "PAR_GLOBAL_DEBUG" instead.
66 If this variable is set to a true value and par.pl is run, verbose
68 output is sent to STDOUT or the logging filehandle. This is overridden
69 by the "-q" option to par.pl, for steps after argument parsing occurs.
70 This currently only influences par.pl. Whether this is the intended
72 behaviour remains to be verified.
73 PAR_GLOBAL_CLEAN
75 Setting "PAR_GLOBAL_CLEAN" alters the behavior of par applications
76 which see that environment variable at launch. "PAR_GLOBAL_CLEAN"
77 overrides the "-C" option. Settings of 0 and 1 are supported. 0
78 corresponds to not using "-C" on the pp command line; 1 corresponds to
79 using "-C" on the pp command line. "PAR_GLOBAL_CLEAN" is ignored if
80 "PAR_GLOBAL_TEMP" is set, yet it controls the form of "PAR_TEMP" when
81 "PAR_GLOBAL_TEMP" is not set.
82 PAR_GLOBAL_DEBUG
84 The PAR loader becomes more verbose when "PAR_DEBUG" is set. Setting
85 "PAR_GLOBAL_DEBUG" guarantees that "PAR_DEBUG" will be set internally,
86 initially. See "PAR_DEBUG" for more details.
87 PAR_GLOBAL_TEMP
89 Contributes to the calculation of "PAR_TEMP", and is further explained
90 there.
91 PAR_GLOBAL_TMPDIR
93 Contributes to the calculation of "PAR_TEMP", and is further explained
94 there.
95 PAR_INITIALIZED
97 This environment variable is for internal use by the PAR binary loader
98 only. Documented only to avoid surprises if spawned applications
99 expect to see a value initialized by the user.
100 PAR_PROGNAME
102 "PAR_PROGNAME" is set to the fully-qualified path name of the
103 executable program. On Windows, this is reliably obtained from the
104 "GetModuleFileName" API. On other OSes, if the C runtime is given a
105 qualified path name, it is used, or the unqualified file name given is
106 qualified by walking the path. This is reasonably reliable given
107 normal program spawning conventions, but cannot be guaranteed to be
108 correct in all circumstances.
109 PAR_APP_REUSE
111 Strictly internal. Skip this section if you're not a PAR developer.
112 The variable shouldn't ever be exposed to user code and packaged
114 applications should not depend on it being set or not.
115 If an application has been packaged with the "--reusable" option, the
117 bootstrapping code will set this environment variable to the name of
118 the program that is to be run instead of the packaged program. The
119 main.pl loader script fetches the file name, deletes the environment
120 variable, and then runs the given program.
121 PAR_RUN
123 This environment variable was set during constructions of "PAR::Packer"
124 objects (usually during pp runs only) by versions of PAR up to 0.957.
125 Since PAR 0.958, this variable is unused.
126 PAR_SPAWNED
128 This variable is used internally by the parl binary loader to signal
129 the child process that it's the child.
130 You should not rely on this variable outside of the PAR binary loader
132 code. For a slightly more detailed discussion, please refer to the
133 who_am_i.txt documentation file in the PAR source distribution which
134 was contributed by Alan Stewart.
135 Documented only to avoid surprises if spawned applications expect to
137 see a value initialized by the user.
138 PAR_TEMP
140 Users should set "PAR_GLOBAL_TEMP" instead. "PAR_TEMP" is calculated
141 from a variety of other variables. See the "NOTES" section in the pod
142 for PAR.pm for a complete description of how the calculation proceeds.
143 "PAR_TEMP", once calculated, is used as the location where PAR stores
144 its extracted, temporary file cache.
145 PAR_TMPDIR
147 Contributes to the calculation of "PAR_TEMP", and is further explained
148 there. Users should set "PAR_GLOBAL_TMPDIR" instead.
149 PAR_VERBATIM
151 The "PAR_VERBATIM" variable controls the way Perl code is packaged into
152 a PAR archive or binary executable. If it is set to a true value during
153 the packaging process, modules (and scripts) are not passed through the
154 default "PAR::Filter::PodStrip" filter which removes all POD
155 documentation from the code. Note that the "PAR::Filter::PatchContent"
156 filter is still applied.
157 The "-F" option to the pp tool overrides the "PAR_VERBATIM" setting.
159 That means if you set "PAR_VERBATIM=1" but specify "-F PodStrip" on the
160 "pp" command line, the "PodStrip" filter will be applied.
161 "PAR_VERBATIM" is not used by the PAR application.
163 PAR_VERBOSE
165 Setting this environment variable to a positive integer has the same
166 effect as using the "-verbose" switch to pp.
167 PP_OPTS
169 During a pp run, the contents of the "PP_OPTS" variable are treated as
170 if they were part of the command line. In newer versions of PAR, you
171 can also write options to a file and execute pp as follows to read the
172 options from the file:
173 pp @FILENAME
175 That can, of course, be combined with other command line arguments to
177 pp or the "PP_OPTS" variable.
178 TMP, TEMP, TMPDIR, TEMPDIR
180 Please refer to "PAR_TMPDIR".
181
183 PAR, PAR::Tutorial, PAR::FAQ
184 par.pl, parl, pp
186 PAR::Dist for details on PAR distributions.
188
190 Steffen Mueller <smueller@cpan.org>
191 You can write to the mailing list at <par@perl.org>, or send an empty
193 mail to <par-subscribe@perl.org> to participate in the discussion.
194 Please submit bug reports to <bug-par@rt.cpan.org>. If you need
196 support, however, joining the <par@perl.org> mailing list is preferred.
197
199 PAR: Copyright 2003-2010 by Audrey Tang, <cpan@audreyt.org>.
200 This document: Copyright 2006-2010 by Steffen Mueller,
202 <smueller@cpan.org>
203 Some information has been taken from Alan Stewart's extra documentation
205 in the contrib/ folder of the PAR distribution.
206 This program or documentation is free software; you can redistribute it
208 and/or modify it under the same terms as Perl itself.
209 See LICENSE.
211perl v5.32.0 2021-01-13 PAR::Environment(3)