.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.30) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "PAR::Environment 3" .TH PAR::Environment 3 "2011-12-28" "perl v5.20.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" PAR::Environment \- Index and reference of PAR environment variables .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\s-1PAR\s0 uses various environment variables both during the building process of executables or \s-1PAR\s0 archives and the \fIuse\fR 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 \s-1PAR\s0 uses. .PP Wherever I want to refer to the \f(CW$ENV{FOO}\fR environment hash entry, I will usually talk about the \f(CW\*(C`FOO\*(C'\fR variable for brevity. .SH "INDEX OF ENVIRONMENT VARIABLES" .IX Header "INDEX OF ENVIRONMENT VARIABLES" \&\fBPlease note that this is still very, very incomplete! Contributions welcome!\fR .PP 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. .PP Of course, the description may use examples. .SS "\s-1PAR_0\s0" .IX Subsection "PAR_0" If the running program is run from within a \s-1PAR\s0 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. .PP For example, if you package a file \fIfoo.pl\fR into \&\fIbar.par\fR and run \fIfoo.pl\fR with this command .PP .Vb 1 \& par.pl foo.par bar.pl .Ve .PP then the \f(CW\*(C`PAR_0\*(C'\fR variable will contain something like \&\f(CW\*(C`/tmp/par\-youser/cache\-b175f53eb731da9594e0dde337d66013ddf25a44/495829f0.pl\*(C'\fR where \f(CW\*(C`youser\*(C'\fR is your username and \&\f(CW\*(C`/tmp/par\-youser/cache\-b175f53eb731da9594e0dde337d66013ddf25a44/\*(C'\fR is the \&\s-1PAR\s0 cache directory (\f(CW\*(C`PAR_TEMP\*(C'\fR). .PP The name of the \s-1PAR\s0 cache directory can take a number of different forms, so use \f(CW\*(C`PAR_0\*(C'\fR 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 \f(CW\*(C`PAR_0\*(C'\fR. .PP This works the same for executable binaries (\fI.exe\fR, ...). .PP If you are looking for the name and path of the pp-ed binary file, please refer to the \f(CW\*(C`PAR_PROGNAME\*(C'\fR variable. .SS "\s-1PAR_ARGC, PAR_ARGV_0, PAR_ARGV_...\s0" .IX Subsection "PAR_ARGC, PAR_ARGV_0, PAR_ARGV_..." You should not rely on these variables outside of the \s-1PAR\s0 binary loader code. .PP These variables are set when a non-dependent pp-ed binary executable runs. The initially executed process extracts another binary and runs it as a child process. In order to pass its command line arguments to the child, the parent process sets \f(CW\*(C`PAR_ARG*\*(C'\fR as they would be used in C programs: \f(CW\*(C`PAR_ARGC\*(C'\fR has the number of arguments, \f(CW\*(C`PAR_ARGV_0\*(C'\fR has the name of the executable, \f(CW\*(C`PAR_ARGV_*\*(C'\fR are the command line arguments. .PP If you would like to access the name of the running program (script or binary), please refer to \f(CW\*(C`PAR_0\*(C'\fR and \f(CW\*(C`PAR_PROGNAME\*(C'\fR instead! .PP Related: \f(CW\*(C`PAR_SPAWNED\*(C'\fR, \f(CW\*(C`PAR_0\*(C'\fR, \f(CW\*(C`PAR_PROGNAME\*(C'\fR .SS "\s-1PAR_CLEAN\s0" .IX Subsection "PAR_CLEAN" Users should set \f(CW\*(C`PAR_GLOBAL_CLEAN\*(C'\fR instead. Recreated from \f(CW\*(C`PAR_GLOBAL_CLEAN\*(C'\fR and the value of \f(CW\*(C`\-C\*(C'\fR from the \s-1YAML\s0 file by the \s-1PAR\s0 loader, and used within loader to control the initial behavior of extraction, and the final behavior of cleanup. The user can reference \&\f(CW\*(C`PAR_CLEAN\*(C'\fR in the application to determine which of these behaviors is being used for this run of the application. .SS "\s-1PAR_DEBUG\s0" .IX Subsection "PAR_DEBUG" Users should set \f(CW\*(C`PAR_GLOBAL_DEBUG\*(C'\fR instead. .PP If this variable is set to a true value and \fIpar.pl\fR is run, verbose output is sent to \s-1STDOUT\s0 or the logging filehandle. This is overridden by the \f(CW\*(C`\-q\*(C'\fR option to \fIpar.pl\fR, for steps after argument parsing occurs. .PP This currently only influences \fIpar.pl\fR. Whether this is the intended behaviour remains to be verified. .SS "\s-1PAR_GLOBAL_CLEAN\s0" .IX Subsection "PAR_GLOBAL_CLEAN" Setting \f(CW\*(C`PAR_GLOBAL_CLEAN\*(C'\fR alters the behavior of par applications which see that environment variable at launch. \&\f(CW\*(C`PAR_GLOBAL_CLEAN\*(C'\fR overrides the \f(CW\*(C`\-C\*(C'\fR option. Settings of 0 and 1 are supported. 0 corresponds to not using \f(CW\*(C`\-C\*(C'\fR on the pp command line; 1 corresponds to using \f(CW\*(C`\-C\*(C'\fR on the pp command line. \&\f(CW\*(C`PAR_GLOBAL_CLEAN\*(C'\fR is ignored if \f(CW\*(C`PAR_GLOBAL_TEMP\*(C'\fR is set, yet it controls the form of \f(CW\*(C`PAR_TEMP\*(C'\fR when \f(CW\*(C`PAR_GLOBAL_TEMP\*(C'\fR is not set. .SS "\s-1PAR_GLOBAL_DEBUG\s0" .IX Subsection "PAR_GLOBAL_DEBUG" The \s-1PAR\s0 loader becomes more verbose when \f(CW\*(C`PAR_DEBUG\*(C'\fR is set. Setting \f(CW\*(C`PAR_GLOBAL_DEBUG\*(C'\fR guarantees that \f(CW\*(C`PAR_DEBUG\*(C'\fR will be set internally, initially. See \f(CW\*(C`PAR_DEBUG\*(C'\fR for more details. .SS "\s-1PAR_GLOBAL_TEMP\s0" .IX Subsection "PAR_GLOBAL_TEMP" Contributes to the calculation of \f(CW\*(C`PAR_TEMP\*(C'\fR, and is further explained there. .SS "\s-1PAR_GLOBAL_TMPDIR\s0" .IX Subsection "PAR_GLOBAL_TMPDIR" Contributes to the calculation of \f(CW\*(C`PAR_TEMP\*(C'\fR, and is further explained there. .SS "\s-1PAR_INITIALIZED\s0" .IX Subsection "PAR_INITIALIZED" This environment variable is for internal use by the \s-1PAR\s0 binary loader only. Documented only to avoid surprises if spawned applications expect to see a value initialized by the user. .SS "\s-1PAR_PROGNAME\s0" .IX Subsection "PAR_PROGNAME" \&\f(CW\*(C`PAR_PROGNAME\*(C'\fR is set to the fully-qualified path name of the executable program. On Windows, this is reliably obtained from the \f(CW\*(C`GetModuleFileName\*(C'\fR \s-1API.\s0 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. .SS "\s-1PAR_APP_REUSE\s0" .IX Subsection "PAR_APP_REUSE" Strictly internal. Skip this section if you're not a \s-1PAR\s0 developer. .PP The variable shouldn't ever be exposed to user code and packaged applications should not depend on it being set or not. .PP If an application has been packaged with the \f(CW\*(C`\-\-reusable\*(C'\fR 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 \fImain.pl\fR loader script fetches the file name, deletes the environment variable, and then runs the given program. .SS "\s-1PAR_RUN\s0" .IX Subsection "PAR_RUN" This environment variable was set during constructions of \f(CW\*(C`PAR::Packer\*(C'\fR objects (usually during \fIpp\fR runs only) by versions of \s-1PAR\s0 up to 0.957. Since \s-1PAR 0.958,\s0 this variable is unused. .SS "\s-1PAR_SPAWNED\s0" .IX Subsection "PAR_SPAWNED" This variable is used internally by the \fIparl\fR binary loader to signal the child process that it's the child. .PP You should not rely on this variable outside of the \s-1PAR\s0 binary loader code. For a slightly more detailed discussion, please refer to the \&\fIwho_am_i.txt\fR documentation file in the \s-1PAR\s0 source distribution which was contributed by Alan Stewart. Related: \f(CW\*(C`PAR_ARGC\*(C'\fR, \f(CW\*(C`PAR_ARGV_*\*(C'\fR .PP Documented only to avoid surprises if spawned applications expect to see a value initialized by the user. .SS "\s-1PAR_TEMP\s0" .IX Subsection "PAR_TEMP" Users should set \f(CW\*(C`PAR_GLOBAL_TEMP\*(C'\fR instead. \&\f(CW\*(C`PAR_TEMP\*(C'\fR is calculated from a variety of other variables. See the \f(CW\*(C`NOTES\*(C'\fR section in the pod for \s-1PAR\s0.pm for a complete description of how the calculation proceeds. \&\f(CW\*(C`PAR_TEMP\*(C'\fR, once calculated, is used as the location where \s-1PAR\s0 stores its extracted, temporary file cache. .SS "\s-1PAR_TMPDIR\s0" .IX Subsection "PAR_TMPDIR" Contributes to the calculation of \f(CW\*(C`PAR_TEMP\*(C'\fR, and is further explained there. Users should set \f(CW\*(C`PAR_GLOBAL_TMPDIR\*(C'\fR instead. .SS "\s-1PAR_VERBATIM\s0" .IX Subsection "PAR_VERBATIM" The \f(CW\*(C`PAR_VERBATIM\*(C'\fR variable controls the way Perl code is packaged into a \s-1PAR\s0 archive or binary executable. If it is set to a true value during the packaging process, modules (and scripts) are \&\fBnot\fR passed through the default \f(CW\*(C`PAR::Filter::PodStrip\*(C'\fR filter which removes all \s-1POD\s0 documentation from the code. Note that the \&\f(CW\*(C`PAR::Filter::PatchContent\*(C'\fR filter is still applied. .PP The \f(CW\*(C`\-F\*(C'\fR option to the \fIpp\fR tool overrides the \f(CW\*(C`PAR_VERBATIM\*(C'\fR setting. That means if you set \f(CW\*(C`PAR_VERBATIM=1\*(C'\fR but specify \&\f(CW\*(C`\-F PodStrip\*(C'\fR on the \f(CW\*(C`pp\*(C'\fR command line, the \f(CW\*(C`PodStrip\*(C'\fR filter will be applied. .PP \&\f(CW\*(C`PAR_VERBATIM\*(C'\fR is not used by the \s-1PAR\s0 application. .SS "\s-1PAR_VERBOSE\s0" .IX Subsection "PAR_VERBOSE" Setting this environment variable to a positive integer has the same effect as using the \f(CW\*(C`\-verbose\*(C'\fR switch to \fIpp\fR. .SS "\s-1PP_OPTS\s0" .IX Subsection "PP_OPTS" During a \fIpp\fR run, the contents of the \f(CW\*(C`PP_OPTS\*(C'\fR variable are treated as if they were part of the command line. In newer versions of \s-1PAR,\s0 you can also write options to a file and execute \fIpp\fR as follows to read the options from the file: .PP .Vb 1 \& pp @FILENAME .Ve .PP That can, of course, be combined with other command line arguments to \fIpp\fR or the \f(CW\*(C`PP_OPTS\*(C'\fR variable. .SS "\s-1TMP, TEMP, TMPDIR, TEMPDIR\s0" .IX Subsection "TMP, TEMP, TMPDIR, TEMPDIR" Please refer to \f(CW\*(C`PAR_TMPDIR\*(C'\fR. .SH "SEE ALSO" .IX Header "SEE ALSO" The \s-1PAR\s0 homepage at . .PP \&\s-1PAR\s0, PAR::Tutorial, \s-1PAR::FAQ\s0 (For a more current \s-1FAQ,\s0 refer to the homepage.) .PP par.pl, parl, pp .PP PAR::Dist for details on \s-1PAR\s0 distributions. .SH "AUTHORS" .IX Header "AUTHORS" Steffen Mueller .PP is the official \s-1PAR\s0 website. You can write to the mailing list at , or send an empty mail to to participate in the discussion. .PP Please submit bug reports to . If you need support, however, joining the mailing list is preferred. .SH "COPYRIGHT" .IX Header "COPYRIGHT" \&\s-1PAR:\s0 Copyright 2003\-2010 by Audrey Tang, . .PP This document: Copyright 2006\-2010 by Steffen Mueller, .PP Some information has been taken from Alan Stewart's extra documentation in the \&\fIcontrib/\fR folder of the \s-1PAR\s0 distribution. .PP This program or documentation is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP See