# $File: //member/autrijus/PAR/README $ $Author: autrijus $
# $Revision: #14 $ $Change: 3652 $ $DateTime: 2003/01/19 14:54:34 $

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/slide001.html>; a Chinese version
is at <http://www.autrijus.org/par-intro.zh/slide001.html>.

* 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.

* 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:

- 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

- 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 interpreter only, without core module:

    % 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

- Clean setup

    % pp -Opacked.exe source.pl		# makes packed.exe
    (now deploy 'packed.exe' to target machine)
    $ packed.exe			# run it

Note that if your perl was built as a shared library, the
'Clean setup' above will still need a separate perl5x.dll or
libperl.so to function correctly.

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 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>.