# $File: //member/autrijus/PAR/README $ $Author: autrijus $
# $Revision: #16 $ $Change: 4504 $ $DateTime: 2003/03/01 15:50:24 $

This is the README file for PAR, a toolkit to use perl scripts and
modules stored inside compressed .par files.

Please type "perldoc PAR" after installation to see the module usage
information, and "perldoc PAR::FAQ" for a number of frequently-asked
questions.

For bundling prerequisite modules of scripts into a PAR file (ala
PerlApp, Perl2exe, or 'perlcc that works'), see "perldoc pp".

For running ".par" files directly, see "perldoc parl".

To generate/execute self-contained perl scripts, see "perldoc par.pl".

You may also want to read the 'ChangeLog' file, which describes new
features, bugfixes and additional notes for this release.

There is also a presentation "Introduction to PAR", available as
<http://www.autrijus.org/par-intro/>; a Chinese version is at
<http://www.autrijus.org/par-intro.zh/>.

* Installation

PAR uses the standard perl module install process:

cpansign -v		# see SIGNATURE for details
perl Makefile.PL
make
make test
make install

If your system has a C compiler, the 'pp' tool and a stand-alone binary
version of par.pl will be compiled and installed automatically.
You can generate self-executable binaries by:

    % pp -o foo.exe /home/test.pl

* Notes for Windows users

If you are using Microsoft Windows, you will probably need the 'nmake'
utility before installation. It's available at:

    ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe

If you are connected to the internet, "perl Makefile.PL" is capable
of automatically fetch it, and install into your windows directory;
all you have to do is to answer 'y' to this question:

    Required executable 'nmake' not found. Install it? [Y/n]:

However, if you are not yet online, or wish to install 'nmake' into
another directory, then please download the file manually, save it to
a directory in %PATH (e.g. C:\WINDOWS\COMMAND), then launch the MS-DOS
command line shell, "cd" to that directory, and run "nmake15.exe" from
there; that will create the 'nmake.exe' file needed by CPANPLUS.

You may then resume the installation process above, but replace 'make'
with 'nmake' in the last three lines.

Also, if you do not have the compiler used to compile your version or
Perl (e.g. Microsoft Visual C++ for ActivePerl -- do not forget to run
"vcvars32.bat" or equivalent before "perl Makefile.PL"!), you will not
be able to generate binary executables using 'pp'.  However, ActiveState
is known to make PPM-installable PAR versions quite frequently, so your
best bet may still be "ppm install PAR".

* Typical Usage

Here are some recipes showing how to utilize pp to bundle source.pl with
all its dependencies, on target machines with different expected
settings:

- Stand-alone setup

    % pp -o packed.exe source.pl	# makes packed.exe
    # Now, deploy 'packed.exe' to target machine...
    $ packed.exe			# run it

- Perl interpreter only, without core modules:

    % pp -B -p source.pl		# makes source.par
    % par.pl -B -Opacked.pl source.par  # makes packed.pl
    # Now, deploy 'packed.pl' to target machine...
    $ perl packed.pl			# run it

- Perl with core module installed:

    % pp -p source.pl			# makes source.par
    % par.pl -b -Opacked.pl source.par	# makes packed.pl
    # Now, deploy 'packed.pl' to target machine...
    $ perl packed.pl			# run it

- Perl with PAR.pm and its dependencies installed:

    % pp -p source.pl                   # makes source.par
    % echo "use PAR 'source.par';" > packed.pl;
    % cat source.pl >> packed.pl;       # makes packed.pl
    # Now, deploy 'source.par' and 'packed.pl' to target machine...
    $ perl packed.pl                    # run it

Note that if your perl was built with a shared library, the
'Stand-alone setup' above will still need a separate perl5x.dll or
libperl.so to function correctly.  Patches to include a copy
of libperl with the executable are most welcome.

Please consult the documentation of 'pp' for more information.

* Contact

PAR has a mailing list, <par@perl.org>, that you can write to;
send an empty mail to <par-subscribe@perl.org> to join the list
and participate in the discussion.

Please send bug reports to <bug-par@rt.cpan.org>.

* Copyright

Copyright 2002, 2003 by Autrijus Tang <autrijus@autrijus.org>.

All rights reserved.  You can redistribute and/or modify
this bundle under the same terms as Perl itself.

See <http://www.perl.com/perl/misc/Artistic.html>.