238 lines
8.1 KiB
Plaintext
238 lines
8.1 KiB
Plaintext
|
=head1 NAME
|
||
|
|
||
|
PAR::Environment - Index and reference of PAR environment variables
|
||
|
|
||
|
=head1 DESCRIPTION
|
||
|
|
||
|
PAR uses various environment variables both during the building process of
|
||
|
executables or PAR archives and the I<use> of them. Since the wealth of
|
||
|
combinations and settings might confuse one or the other (like me), this
|
||
|
document is intended to document all environment variables which PAR uses.
|
||
|
|
||
|
Wherever I want to refer to the C<$ENV{FOO}> environment hash entry, I will
|
||
|
usually talk about the C<FOO> variable for brevity.
|
||
|
|
||
|
=head1 INDEX OF ENVIRONMENT VARIABLES
|
||
|
|
||
|
B<Please note that this is still very, very incomplete! Contributions welcome!>
|
||
|
|
||
|
For each variable, there should be a description what it contains, when
|
||
|
it can be expected to exist (and contain meaningful information),
|
||
|
when it is sensible to define it yourself, and what effect this has.
|
||
|
|
||
|
Of course, the description may use examples.
|
||
|
|
||
|
=head2 PAR_0
|
||
|
|
||
|
If the running program is run from within a PAR archive or pp-produced
|
||
|
executable, this variable contains the name of the extracted program
|
||
|
(i.e. .pl file). This is useful of you want to open the source code
|
||
|
file of the running program.
|
||
|
|
||
|
For example, if you package a file F<foo.pl> into
|
||
|
F<bar.par> and run F<foo.pl> with this command
|
||
|
|
||
|
par.pl foo.par bar.pl
|
||
|
|
||
|
then the C<PAR_0> variable will contain something like
|
||
|
C</tmp/par-youser/cache-b175f53eb731da9594e0dde337d66013ddf25a44/495829f0.pl>
|
||
|
where C<youser> is your username and
|
||
|
C</tmp/par-youser/cache-b175f53eb731da9594e0dde337d66013ddf25a44/> is the
|
||
|
PAR cache directory (C<PAR_TEMP>).
|
||
|
|
||
|
The name of the PAR cache directory can take a number of different forms,
|
||
|
so use C<PAR_0> if you want to find the extracted program's .pl file --
|
||
|
attempting to construct the name yourself requires complex logic that
|
||
|
has already produced the value in C<PAR_0>.
|
||
|
|
||
|
This works the same for executable binaries (F<.exe>, ...).
|
||
|
|
||
|
If you are looking for the name and path of the pp-ed binary file,
|
||
|
please refer to the C<PAR_PROGNAME> variable.
|
||
|
|
||
|
=head2 PAR_CLEAN
|
||
|
|
||
|
Users should set C<PAR_GLOBAL_CLEAN> instead.
|
||
|
|
||
|
Recreated from C<PAR_GLOBAL_CLEAN> and the value of C<-C> from the YAML file
|
||
|
by the PAR loader, and used within loader to control the initial behavior
|
||
|
of extraction, and the final behavior of cleanup. The user can reference
|
||
|
C<PAR_CLEAN> in the application to determine which of these behaviors
|
||
|
is being used for this run of the application.
|
||
|
|
||
|
=head2 PAR_DEBUG
|
||
|
|
||
|
Users should set C<PAR_GLOBAL_DEBUG> instead.
|
||
|
|
||
|
If this variable is set to a true value and F<par.pl> is run,
|
||
|
verbose output is sent to STDOUT or the logging filehandle.
|
||
|
This is overridden by the C<-q> option to F<par.pl>,
|
||
|
for steps after argument parsing occurs.
|
||
|
|
||
|
This currently only influences F<par.pl>. Whether this is the intended
|
||
|
behaviour remains to be verified.
|
||
|
|
||
|
=head2 PAR_GLOBAL_CLEAN
|
||
|
|
||
|
Setting C<PAR_GLOBAL_CLEAN> alters the behavior of par applications
|
||
|
which see that environment variable at launch.
|
||
|
C<PAR_GLOBAL_CLEAN> overrides the C<-C> option.
|
||
|
Settings of 0 and 1 are supported. 0 corresponds to not using C<-C> on the
|
||
|
pp command line; 1 corresponds to using C<-C> on the pp command line.
|
||
|
C<PAR_GLOBAL_CLEAN> is ignored if C<PAR_GLOBAL_TEMP> is set, yet it
|
||
|
controls the form of C<PAR_TEMP> when C<PAR_GLOBAL_TEMP> is not set.
|
||
|
|
||
|
=head2 PAR_GLOBAL_DEBUG
|
||
|
|
||
|
The PAR loader becomes more verbose when C<PAR_DEBUG> is set.
|
||
|
Setting C<PAR_GLOBAL_DEBUG> guarantees that C<PAR_DEBUG> will be set
|
||
|
internally, initially. See C<PAR_DEBUG> for more details.
|
||
|
|
||
|
=head2 PAR_GLOBAL_TEMP
|
||
|
|
||
|
Contributes to the calculation of C<PAR_TEMP>, and is further explained
|
||
|
there.
|
||
|
|
||
|
=head2 PAR_GLOBAL_TMPDIR
|
||
|
|
||
|
Contributes to the calculation of C<PAR_TEMP>, and is further explained
|
||
|
there.
|
||
|
|
||
|
=head2 PAR_INITIALIZED
|
||
|
|
||
|
This environment variable is for internal use by the PAR binary loader
|
||
|
only.
|
||
|
Documented only to avoid surprises if spawned applications expect
|
||
|
to see a value initialized by the user.
|
||
|
|
||
|
=head2 PAR_PROGNAME
|
||
|
|
||
|
C<PAR_PROGNAME> is set to the fully-qualified path name of the executable
|
||
|
program.
|
||
|
On Windows, this is reliably obtained from the C<GetModuleFileName> API.
|
||
|
On other OSes, if the C runtime is given a qualified path name, it is used,
|
||
|
or the unqualified file name given is qualified by walking the path.
|
||
|
This is reasonably reliable given normal program spawning conventions,
|
||
|
but cannot be guaranteed to be correct in all circumstances.
|
||
|
|
||
|
=head2 PAR_APP_REUSE
|
||
|
|
||
|
Strictly internal. Skip this section if you're not a PAR developer.
|
||
|
|
||
|
The variable shouldn't ever be exposed to user code and packaged
|
||
|
applications should not depend on it being set or not.
|
||
|
|
||
|
If an application has been packaged with the C<--reusable> option, the
|
||
|
bootstrapping code will set this environment variable to the name of
|
||
|
the program that is to be run instead of the packaged program.
|
||
|
The F<main.pl> loader script fetches the file name, deletes the
|
||
|
environment variable, and then runs the given program.
|
||
|
|
||
|
=head2 PAR_RUN
|
||
|
|
||
|
This environment variable was set during constructions of C<PAR::Packer>
|
||
|
objects (usually during F<pp> runs only) by versions of PAR up to
|
||
|
0.957. Since PAR 0.958, this variable is unused.
|
||
|
|
||
|
=head2 PAR_SPAWNED
|
||
|
|
||
|
This variable is used internally by the F<parl> binary loader to signal
|
||
|
the child process that it's the child.
|
||
|
|
||
|
You should not rely on this variable outside of the PAR binary loader
|
||
|
code. For a slightly more detailed discussion, please refer to the
|
||
|
F<who_am_i.txt> documentation file in the PAR source distribution
|
||
|
which was contributed by Alan Stewart.
|
||
|
|
||
|
Documented only to avoid surprises if spawned applications expect
|
||
|
to see a value initialized by the user.
|
||
|
|
||
|
=head2 PAR_TEMP
|
||
|
|
||
|
Users should set C<PAR_GLOBAL_TEMP> instead.
|
||
|
C<PAR_TEMP> is calculated from a variety of other variables.
|
||
|
See the C<NOTES> section in the pod for PAR.pm for
|
||
|
a complete description of how the calculation proceeds.
|
||
|
C<PAR_TEMP>, once calculated, is used as the location
|
||
|
where PAR stores its extracted, temporary file cache.
|
||
|
|
||
|
=head2 PAR_TMPDIR
|
||
|
|
||
|
Contributes to the calculation of C<PAR_TEMP>, and is further explained
|
||
|
there. Users should set C<PAR_GLOBAL_TMPDIR> instead.
|
||
|
|
||
|
=head2 PAR_VERBATIM
|
||
|
|
||
|
The C<PAR_VERBATIM> variable controls the way Perl code is packaged
|
||
|
into a PAR archive or binary executable. If it is set to a true
|
||
|
value during the packaging process, modules (and scripts) are
|
||
|
B<not> passed through the default C<PAR::Filter::PodStrip> filter
|
||
|
which removes all POD documentation from the code. Note that the
|
||
|
C<PAR::Filter::PatchContent> filter is still applied.
|
||
|
|
||
|
The C<-F> option to the F<pp> tool overrides the C<PAR_VERBATIM>
|
||
|
setting. That means if you set C<PAR_VERBATIM=1> but specify
|
||
|
C<-F PodStrip> on the C<pp> command line, the C<PodStrip> filter
|
||
|
will be applied.
|
||
|
|
||
|
C<PAR_VERBATIM> is not used by the PAR application.
|
||
|
|
||
|
=head2 PAR_VERBOSE
|
||
|
|
||
|
Setting this environment variable to a positive integer
|
||
|
has the same effect as using the C<-verbose> switch to F<pp>.
|
||
|
|
||
|
=head2 PP_OPTS
|
||
|
|
||
|
During a F<pp> run, the contents of the C<PP_OPTS> variable are
|
||
|
treated as if they were part of the command line. In newer versions
|
||
|
of PAR, you can also write options to a file and execute F<pp>
|
||
|
as follows to read the options from the file:
|
||
|
|
||
|
pp @FILENAME
|
||
|
|
||
|
That can, of course, be combined with other command line arguments
|
||
|
to F<pp> or the C<PP_OPTS> variable.
|
||
|
|
||
|
=head2 TMP, TEMP, TMPDIR, TEMPDIR
|
||
|
|
||
|
Please refer to C<PAR_TMPDIR>.
|
||
|
|
||
|
=head1 SEE ALSO
|
||
|
|
||
|
L<PAR>, L<PAR::Tutorial>, L<PAR::FAQ>
|
||
|
|
||
|
L<par.pl>, L<parl>, L<pp>
|
||
|
|
||
|
L<PAR::Dist> for details on PAR distributions.
|
||
|
|
||
|
=head1 AUTHORS
|
||
|
|
||
|
Steffen Mueller E<lt>smueller@cpan.orgE<gt>
|
||
|
|
||
|
You can write
|
||
|
to the mailing list at E<lt>par@perl.orgE<gt>, or send an empty mail to
|
||
|
E<lt>par-subscribe@perl.orgE<gt> to participate in the discussion.
|
||
|
|
||
|
Please submit bug reports to E<lt>bug-par@rt.cpan.orgE<gt>. If you need
|
||
|
support, however, joining the E<lt>par@perl.orgE<gt> mailing list is
|
||
|
preferred.
|
||
|
|
||
|
=head1 COPYRIGHT
|
||
|
|
||
|
PAR: Copyright 2003-2010 by Audrey Tang,
|
||
|
E<lt>cpan@audreyt.orgE<gt>.
|
||
|
|
||
|
This document: Copyright 2006-2010 by Steffen Mueller,
|
||
|
E<lt>smueller@cpan.orgE<gt>
|
||
|
|
||
|
Some information has been taken from Alan Stewart's extra documentation in the
|
||
|
F<contrib/> folder of the PAR distribution.
|
||
|
|
||
|
This program or documentation is free software; you can redistribute it and/or modify it
|
||
|
under the same terms as Perl itself.
|
||
|
|
||
|
See F<LICENSE>.
|
||
|
|
||
|
=cut
|