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

NAME

6       PAR::Environment - Index and reference of PAR environment variables
7

DESCRIPTION

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
15       Wherever I want to refer to the $ENV{FOO} environment hash entry, I
16       will usually talk about the "FOO" variable for brevity.
17

INDEX OF ENVIRONMENT VARIABLES

19       Please note that this is still very, very incomplete! Contributions
20       welcome!
21
22       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
26       Of course, the description may use examples.
27
28   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
34       For example, if you package a file foo.pl into bar.par and run foo.pl
35       with this command
36
37         par.pl foo.par bar.pl
38
39       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
45       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
50       This works the same for executable binaries (.exe, ...).
51
52       If you are looking for the name and path of the pp-ed binary file,
53       please refer to the "PAR_PROGNAME" variable.
54
55   PAR_CLEAN
56       Users should set "PAR_GLOBAL_CLEAN" instead.
57
58       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
64   PAR_DEBUG
65       Users should set "PAR_GLOBAL_DEBUG" instead.
66
67       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
71       This currently only influences par.pl. Whether this is the intended
72       behaviour remains to be verified.
73
74   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
83   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
88   PAR_GLOBAL_TEMP
89       Contributes to the calculation of "PAR_TEMP", and is further explained
90       there.
91
92   PAR_GLOBAL_TMPDIR
93       Contributes to the calculation of "PAR_TEMP", and is further explained
94       there.
95
96   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
101   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
110   PAR_APP_REUSE
111       Strictly internal. Skip this section if you're not a PAR developer.
112
113       The variable shouldn't ever be exposed to user code and packaged
114       applications should not depend on it being set or not.
115
116       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
122   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
127   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
131       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
136       Documented only to avoid surprises if spawned applications expect to
137       see a value initialized by the user.
138
139   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
146   PAR_TMPDIR
147       Contributes to the calculation of "PAR_TEMP", and is further explained
148       there.  Users should set "PAR_GLOBAL_TMPDIR" instead.
149
150   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
158       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
162       "PAR_VERBATIM" is not used by the PAR application.
163
164   PAR_VERBOSE
165       Setting this environment variable to a positive integer has the same
166       effect as using the "-verbose" switch to pp.
167
168   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
174         pp @FILENAME
175
176       That can, of course, be combined with other command line arguments to
177       pp or the "PP_OPTS" variable.
178
179   TMP, TEMP, TMPDIR, TEMPDIR
180       Please refer to "PAR_TMPDIR".
181

SEE ALSO

183       PAR, PAR::Tutorial, PAR::FAQ
184
185       par.pl, parl, pp
186
187       PAR::Dist for details on PAR distributions.
188

AUTHORS

190       Steffen Mueller <smueller@cpan.org>
191
192       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
195       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
201       This document: Copyright 2006-2010 by Steffen Mueller,
202       <smueller@cpan.org>
203
204       Some information has been taken from Alan Stewart's extra documentation
205       in the contrib/ folder of the PAR distribution.
206
207       This program or documentation is free software; you can redistribute it
208       and/or modify it under the same terms as Perl itself.
209
210       See LICENSE.
211
212
213
214perl v5.36.0                      2023-01-20               PAR::Environment(3)
Impressum