Who am I? What am I? Where am I? What else is there?

#####################################################################
This is a description of how a Perl program packaged with pp can find it's
name, what kind of PAR package it is, where it's temp directories are, and
what else there is in a PAR environment.

Caveats up front: The following screens snips are from WinXP, ActiveState
Perl 5.8.4 (build 810) and PAR 0.85. There are only a few Windows specifics,
like the prompt and .exe file extensions, but the rest should apply to Linux as
well. The program listings are shown at the bottom of this doc and will run
anywhere.

4 August 2004 - Revision 1
#####################################################################

The PAR packager "pp" can produce four kinds of PAR packages: PAR files (a
modified zip file), standalone Perl files (plain text), standalone binaries
with the Perl lib bundled, and binaries without the Perl lib. In addition, a
developer may be testing the original Perl program before packaging, but with
PAR related code included. And lastly, each version might be running "clean"
or not.

----------

Let's package program1.pl in each of those ways and see what it shows about
itself. In each case, I'll produce a package called "demo.xxx", where only the
extension is different. I'll start running "clean":

        C:\Par>set PAR_GLOBAL_CLEAN=1

and I'll give three dummy args "a", "b", and "c" just to see them pass thru.

----------

First the original program1.pl unpackaged:

        C:\Par>copy program1.pl demo.pl
                1 file(s) copied.

        C:\Par>perl demo.pl a b c
        My basename is demo
        $0 = demo.pl
        My args are: a b c
        My @INC is: c:/Perl/lib c:/Perl/site/lib .

        I am NOT a PAR package
        I am running as '$^X $0 @ARGV'
                c:\Perl\bin\perl.exe demo.pl a b c

        PAR environment:
        PAR_GLOBAL_CLEAN=1

        C:\Par>

The only thing not typical Perl here is the PAR environment variable I set, but
it has no effect, since this is not a PAR package.

----------

Next is program1.pl packaged as a standalone binary executable, Perl lib not
bundled:

        C:\Par>pp -d -o demo.exe program1.pl

        C:\Par>demo.exe a b c
        My basename is demo
        $0 = demo.exe
        My args are: a b c
        My @INC is: CODE(0xdb6a80) c:/Perl/lib c:/Perl/site/lib .

        I am a PAR package
        I am a binary file
        I am running as '$0 @ARGV'
                demo.exe a b c

        My temp dir is
                c:\temp\par-astewart\temp-1560
                and it will be deleted after the script finishes
        A copy of this script was extracted as
                C:\temp\par-astewart\temp-1560\QY7snBlZYa

        PAR environment:
        PAR_0=C:\temp\par-astewart\temp-1560\QY7snBlZYa
        PAR_CLEAN=1
        PAR_GLOBAL_CLEAN=1
        PAR_INITIALIZED=2
        PAR_PROGNAME=.\demo.exe
        PAR_TEMP=c:\temp\par-astewart\temp-1560

        C:\Par>

What's new? The basename is the same (demo), but $0 is now the executable name
and there is a PAR environment variable PAR_PROGNAME that is almost the same
as $0. If I had run it as "c:\Par\demo.exe", they would have been exactly the
same.

There is a code ref in @INC. That's the PAR hook to load the bundled modules
from the temp dir, instead of the installed Perl lib dirs. It comes first, but
if a module failed to get bundled into demo.exe, it might still be found thru
the remaining installed lib dirs.

Demo.exe knows it's a PAR package because there is a %PAR::LibCache and it
contains a key that matches it's own name. That's the line:

        { no warnings; $is_a_PAR = defined $PAR::LibCache{$ENV{PAR_PROGNAME}}}

in program1.pl. The "no warnings" avoids undef complaints if it's not a PAR
package. The value of $PAR::LibCache{$ENV{PAR_PROGNAME}} is a zip handle and
could be used to directly access the PAR inside demo.exe with Archive::Zip
functions.

There is a PAR temp dir created, made up of the environment variable TEMP plus
"par-" plus my login name plus "temp-" plus the pid of demo.exe. And the whole
string is in PAR_TEMP. Because it's based on the pid, it will be different
each time demo.exe runs.

We get this style of temp dir because PAR_CLEAN=1 during demo.exe and that's
because PAR_GLOBAL_CLEAN=1. It would also have been so if we packaged demo.exe
with "pp -C". And because it's "clean", the temp dir will be deleted when
demo.exe successfully finishes. If demo.exe crashes, it won't be deleted.

PAR_0 gives us the name of a copy of program1.pl that was extracted into the
temp dir. That's useful for a program that wants to open itself as a file,
perhaps to read __DATA__ sections.

PAR_INITIALIZED is an internal state variable that is of no use to the
program. It's used by the binary frontend. It should always equal 2.

----------

Let's run the same demo.exe again except, not "clean":

        C:\Par>set PAR_GLOBAL_CLEAN=0

        C:\Par>demo.exe
        My basename is demo
        $0 = demo.exe
        My args are: a b c
        My @INC is: c:\temp\par-astewart\cache-1d17637b82735e7e0e52c193b4fdd54e
        7ddba73c/inc/lib c:\temp\par-astewart\cache-1d17637b82735e7e0e52c193b4f
        dd54e7ddba73c/inc CODE(0xdd1968) c:/Perl/lib c:/Perl/site/lib .

        I am a PAR package
        I am a binary file
        I am running as '$0 @ARGV'
                demo.exe a b c

        My temp dir is
                c:\temp\par-astewart\cache-1d17637b82735e7e0e52c193b4fdd54e7ddb
        a73c
                and it will NOT be deleted after the script finishes
        A copy of this script was extracted as
                C:\temp\par-astewart\cache-1d17637b82735e7e0e52c193b4fdd54e7ddb
        a73c\d2f130a4.pl

        PAR environment:
        PAR_0=C:\temp\par-astewart\cache-1d17637b82735e7e0e52c193b4fdd54e7ddba7
        3c\d2f130a4.pl
        PAR_CLEAN=0
        PAR_GLOBAL_CLEAN=0
        PAR_INITIALIZED=2
        PAR_PROGNAME=.\demo.exe
        PAR_TEMP=c:\temp\par-astewart\cache-1d17637b82735e7e0e52c193b4fdd54e7dd
        ba73c

        C:\Par>

Three things happened. First, the temp dir is really long! It's
made up of TEMP plus "par-" plus my login name plus "cache-" plus an SHA1 160
bit hash of the demo.exe file. And it won't be deleted at the end of demo.exe.
The next time demo.exe runs, it will be re-used and extraction will not be
re-done. All because PAR_CLEAN=0 while demo.exe is running. The temp dir will
only change if demo.exe is modified and re-packaged, creating a new SHA1 hash
value.

@INC also has two new values in it. Because demo.exe is not running "clean",
all of the source files were extracted from the PAR into an "inc/" dir
inside the temp dir. This is to facilitate modules that parse other modules.
If you use such parsing modules, you can't run "clean". Shared libs are not
extracted here - they are in the base temp dir, whether "clean" or not
"clean".

I set PAR_GLOBAL_CLEAN=0 which will force not "clean" even if I had packaged
demo.exe with "pp -C". If I had undefined PAR_GLOBAL_CLEAN, then it would
depend on the use of "-C" to set PAR_CLEAN.

----------

Let's go "clean" again, to avoid those long dir names, and bundle the Perl lib
into the package:

        C:\Par>set PAR_GLOBAL_CLEAN=1

        C:\Par>pp -o demo.exe program1.pl

        C:\Par>demo.exe a b c
        My basename is demo
        $0 = C:\Par\demo.exe
        My args are: a b c
        My @INC is: CODE(0xdb6d44) .

        I am a PAR package
        I am a binary file
        I am running as '$0 @ARGV'
                C:\Par\demo.exe a b c

        My temp dir is
                c:\temp\par-astewart\temp-1668
                and it will be deleted after the script finishes
        A copy of this script was extracted as
                C:\temp\par-astewart\temp-1668\sXVehq3Yl0

        PAR environment:
        PAR_0=C:\temp\par-astewart\temp-1668\sXVehq3Yl0
        PAR_ARGC=4
        PAR_ARGV_0=demo.exe
        PAR_ARGV_1=a
        PAR_ARGV_2=b
        PAR_ARGV_3=c
        PAR_CLEAN=1
        PAR_GLOBAL_CLEAN=1
        PAR_INITIALIZED=2
        PAR_PROGNAME=C:\Par\demo.exe
        PAR_SPAWNED=1
        PAR_TEMP=c:\temp\par-astewart\temp-1668

A few more changes. $PAR_PROGNAME and $0 have full pathnames regardless of how
I launch them. When a non-dependant PAR package runs, there is a two stage
binary frontend: first the executable demo.exe that I ran, then a second
demo.exe that is extracted to the temp dir and run as a child of the first. If
you look at the process list while demo.exe runs, you'll see two processes
with the same name. In the previous example, there was only the second
process.

You can see the first process telling the second that is a child
(PAR_SPAWNED=1) and passing the command line args as environment variables
(PAR_ARGC and PAR_ARGV_x).

But what happened to the installed Perl lib paths in @INC ? This is a Windows
effect. Because perl58.dll was bundled, extracted into temp and loaded from
there, it could not find the installed lib dirs. In Linux, the lib dirs are
coded into the shared lib and would appear in @INC even after moving the
executable to another machine. So if all the modules you need are bundled in
the PAR package, invalid Linux lib paths in @INC might be a problem. If you
want to make sure that only bundled modules are used, add this to the top of
your program:

        BEGIN {
        my @refinc = grep { ref } @INC;
        @INC = @refinc if @refinc;
        }

If there is a PAR code hook in @INC, then the other fixed paths are removed.

----------

Now for a standalone Perl script.

        C:\Par>pp -P -o demo.pl program1.pl

        C:\Par>perl demo.pl a b c
        My basename is demo
        $0 = demo.pl
        My args are: a b c
        My @INC is: CODE(0x1cb4efc) c:/Perl/lib c:/Perl/site/lib .

        I am a PAR package
        I am a Perl script
        I am running as '$^X $0 @ARGV'
                c:\Perl\bin\perl.exe demo.pl a b c

        My temp dir is
                c:\temp\par-astewart\temp-1376
                and it will be deleted after the script finishes
        A copy of this script was extracted as
                C:\temp\par-astewart\temp-1376\GinF3AxRux

        PAR environment:
        PAR_0=C:\temp\par-astewart\temp-1376\GinF3AxRux
        PAR_CLEAN=1
        PAR_GLOBAL_CLEAN=1
        PAR_INITIALIZED=2
        PAR_PROGNAME=.\demo.pl
        PAR_TEMP=c:\temp\par-astewart\temp-1376

        C:\Par>

Looks a lot like "pp -d -o demo.exe program1.pl". The frontend is plain text
Perl, no shared lib bundled. Using "-T $0" works because it doesn't check far
enough into the file to see zip binary stuff in the back.

Since this is Perl script, it can be run as an argument to $^X, or rely on the
shebang line in Linux, or associate it with the perl.exe in Windows.

An advantage to standalone Perl scripts over binary executables is that they
can be made multi-arch and run on different OSes by packing the XS portions
for each architecture. A binary executable is unique to the OS.

----------

The last form of a PAR package is a PAR file.

        C:\Par>pp -p -o demo.par program1.pl

        C:\Par>perl -MPAR demo.par a b c
        My basename is demo
        $0 = demo.par
        My args are: a b c
        My @INC is: C:\temp\par-astewart\cache-7a335837542a9519464f5484d8b281dd
        f0a727ca/inc/lib C:\temp\par-astewart\cache-7a335837542a9519464f5484d8b
        281ddf0a727ca/inc CODE(0x1890848) c:/Perl/lib c:/Perl/site/lib .

        I am a PAR package
        I am a binary file
        I am running as '$^X -MPAR $0 @ARGV'
                c:\Perl\bin\perl.exe -MPAR demo.par a b c

        My temp dir is
                C:\temp\par-astewart\cache-7a335837542a9519464f5484d8b281ddf0a7
        27ca
                and it will NOT be deleted after the script finishes
        A copy of this script was extracted as
                C:\temp\par-astewart\cache-7a335837542a9519464f5484d8b281ddf0a7
        27ca\d2f130a4.pl

        PAR environment:
        PAR_0=C:\temp\par-astewart\cache-7a335837542a9519464f5484d8b281ddf0a727
        ca\d2f130a4.pl
        PAR_GLOBAL_CLEAN=1
        PAR_PROGNAME=demo.par
        PAR_TEMP=C:\temp\par-astewart\cache-7a335837542a9519464f5484d8b281ddf0a
        727ca

        C:\Par>

This ran much like the standalone script, except invoking "-MPAR". But why
didn't it run clean when PAR_GLOBAL_CLEAN=1 ? Because there is no frontend,
binary or Perl, and therefore no way to clean up when the script finishes. If
you need to run from a .par file and you need to clean up, you'll have to do
it yourself.

----------

So far the temp dir has been based on the current value of $ENV{TEMP}. What if
we want the temp dir to be some specific place for our application, regardless
of system values ?

        C:\Par>set PAR_GLOBAL_TEMP=c:\Par\temp

        C:\Par>demo.exe a b c
        My basename is demo
        $0 = C:\Par\demo.exe
        My args are: a b c
        My @INC is: c:\Par\temp/inc/lib c:\Par\temp/inc CODE(0xdb2718) .

        I am a PAR package
        I am a binary file
        I am running as '$0 @ARGV'
                C:\Par\demo.exe a b c

        My temp dir is
                c:\Par\temp
                and it will NOT be deleted after the script finishes
        A copy of this script was extracted as
                C:\Par\temp\d2f130a4.pl

        PAR environment:
        PAR_0=C:\Par\temp\d2f130a4.pl
        PAR_ARGC=4
        PAR_ARGV_0=demo.exe
        PAR_ARGV_1=a
        PAR_ARGV_2=b
        PAR_ARGV_3=c
        PAR_GLOBAL_CLEAN=1
        PAR_GLOBAL_TEMP=c:\Par\temp
        PAR_INITIALIZED=2
        PAR_PROGNAME=C:\Par\demo.exe
        PAR_SPAWNED=1
        PAR_TEMP=c:\Par\temp

        C:\Par>

PAR_TEMP is set to PAR_GLOBAL_TEMP, but PAR_GLOBAL_CLEAN is overidden. If you
chose a fixed temp dir, you also clean up after yourself. There is currently
no way to define a fixed temp dir inside the PAR package, and since temp dir
creation is done before the script runs, PAR_GLOBAL_TEMP must be set before
running the PAR package.

----------

What about PAR packages with multiple scripts inside? First, a binary
executable with two scripts inside. I'll package program2.pl and program3.pl
(see listings below).

        C:\Par>pp -o demo.exe program2.pl program3.pl

        C:\Par>demo.exe a b c
        Can't open perl script "demo": No such file or directory at script/main
        .pl line 5.

        C:\Par>

What went wrong ? If there had been only one script inside, demo.exe would
have run it. Since there is more than one, it determines the script name from
it's own name.

        C:\Par>copy demo.exe program2.exe
                1 file(s) copied.

        C:\Par>copy demo.exe program3.exe
                1 file(s) copied.

        C:\Par>program2.exe a b c
        This is program2
        My args are: a b c

        C:\Par>program3.exe a b c
        This is program3
        My args are: a b c

        C:\Par>

----------

And a PAR file with the same two programs:

        C:\Par>pp -p -o demo.par program2.pl program3.pl

        C:\Par>perl -MPAR demo.par program2 a b c
        This is program2
        My args are: a b c

        C:\Par>perl -MPAR demo.par program3 a b c
        This is program3
        My args are: a b c

        C:\Par>

The names "program2" and "program3" are not passed as args. The value of $0 is
"demo.par". I don't know of a way to get the command line script name.

----------

One last Windows user warning !! If you have a PAR package calling another PAR
package with system() or exec(), beware of mixing dependant packages made with
"pp -d" and non-dependant packages without "-d". One wants to use the
perl5x.dll from the installed path and the other wants to use the perl5x.dll
bundled in the package and loading from the temp dir. However, when one calls
the other, Windows wants to use the perl5x.dll already in memory for the
second one. Bad things can happen, since the Perl interpreter doesn't get
initialized as expected. If you must mix, then wipe out the local PAR
environment yourself before calling the other package, as program4.pl does.
You may still see some peculiarities, such as:

        C:\Par>set PAR_GLOBAL_TEMP=

        C:\Par>pp -o program4.exe program4.pl

        C:\Par>pp -d -o program5.exe program5.pl

        C:\Par>program4.exe
        This is program4
        My @INC = CODE(0xdb6380) .
        This is program5
        My @INC = CODE(0xdb7134) .

Even though program5.pl was packaged as "-d", it's @INC indicates that it is
using the perl5x.dll in memory from program4.pl and therefore can't locate the
installed lib dirs. I recommend not mixing package types !

----------

I hope all this helps. Package program1.pl in a variety of ways on your system
and see what you get. If you discover any errors in this doc or some
radically different behaviour on another OS, let me know :)

Alan Stewart
astewart1@cox.net

P.S. This doc is in the public domain.


#####################################################################
Listing: program1.pl
#####################################################################
#!perl
use strict;
use warnings;
use File::Basename;

my $basename = basename($0, qw( .par .pl .exe ));
print "My basename is $basename\n\$0 = $0\n";
print "My args are: @ARGV\n";
print "My \@INC is: @INC\n";
print "\n";

my $is_a_PAR;
{ no warnings; $is_a_PAR = defined $PAR::LibCache{$ENV{PAR_PROGNAME}}}

if ($is_a_PAR) {
    print "I am a PAR package\n";
    my $is_text = -T $0;
    print $is_text ? "I am a Perl script\n" : "I am a binary file\n";

    if ($0 =~ /\.par/) {
        print "I am running as '\$^X -MPAR \$0 \@ARGV'\n";
        print "\t$^X -MPAR $0 @ARGV\n"
    }
    elsif ($0 =~ /\.pl$/) {
        print "I am running as '\$^X \$0 \@ARGV'\n";
        print "\t$^X $0 @ARGV\n";
    }
    elsif ($0 =~ /\.exe/) {
        print "I am running as '\$0 \@ARGV'\n";
        print "\t$0 @ARGV\n";
    }
    else {
        if ($is_text) {
            print "I am running as '\$^X \$0 \@ARGV'\n";
            print "\t$^X $0 @ARGV\n";
        }
        else {
            print "I am running as '\$0 \@ARGV'/n";
            print "\t$0 @ARGV/n";
        }
    }
    print "\n";
    print "My temp dir is \n\t$ENV{PAR_TEMP}\n";
    print "\tand it will ", $ENV{PAR_CLEAN} ? "" : "NOT ";
    print "be deleted after the script finishes\n";
    print "A copy of this script was extracted as \n\t$ENV{PAR_0}\n";
}
else {
    print "I am NOT a PAR package\n";
    print "I am running as '\$^X \$0 \@ARGV'\n";
    print "\t$^X $0 @ARGV\n";
}

print "\n";
print "PAR environment:\n";
for (sort keys %ENV) {
   print "$_=$ENV{$_}\n" if /^PAR_/;
}


#####################################################################
## Listing: program2.pl
#####################################################################
#!perl

print "This is program2\n";
print "My args are: @ARGV\n";


#####################################################################
## Listing: program3.pl
#####################################################################
#!perl

print "This is program3\n";
print "My args are: @ARGV\n";


#####################################################################
## Listing: program4.pl
#####################################################################
#!perl

print "This is program4\n";
print "My \@INC = @INC\n";
for (keys %ENV) {delete $ENV{$_} if /^PAR_(?!GLOBAL)/}
system "program5.exe";


#####################################################################
## Listing: program5.pl
#####################################################################
#!perl

print "This is program5\n";
print "My \@INC = @INC\n";


#####################################################################