This is the README file for PAR-Packer, a part of the PAR toolkit.
PAR-Packer is the PAR component that can generate stand-alone executables
and ".par" archives.

The main front-end for PAR-Packer is the "pp" utility.

Please type "perldoc PAR::FAQ" for frequently answered questions.

For packing scripts with prerequisite modules into stand-alone scripts
or executables (aka PerlApp, Perl2exe, or 'perlcc that works'), see
"perldoc pp" and "perldoc tkpp".

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

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

An extensive "Cross-Platform Packaging and Deployment with PAR" tutorial
is available as "perldoc PAR::Tutorial" from the PAR distribution which is
a prerequisite for this distribution.

* Installation

PAR-Packer uses the standard perl module install process:

    cpansign -v         # optional; see SIGNATURE for details
    perl Makefile.PL
    make                # or 'nmake' on Win32
    make test
    make install

If your system has a C compiler, or if somebody has built a PAR-Packer
package for your architecture, the 'pp' tool and a stand-alone binary
version of par.pl will be installed, so you can generate self-executable
binaries like this:

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

* Binary installation with pre-built PAR-Packer files

This distribution uses the Module::Install framework to offer
pre-compiled, architecture-dependent PAR-Packer packages to save your
compilation time.  This process is completely automatic -- no
actions are required on your part.

However, if nobody has generated such a package for your architecture,
you will see a short messages like this:

    Fetching 'PAR-Packer0.97-i386-freebsd-5.8.0.par' from www.cpan.org...
    *** No installation package available for your architecture.
    However, you may wish to generate one with 'make par' and send
    it to <SMUELLER@cpan.org>, so other people on the same platform
    can benefit from it.
    *** Proceeding with normal installation...

If you are on a platform where normal users do not have a C compiler
installed (MSWin32, darwin, etc.), please follow the instruction above
and mail the generated PAR-Packer package (or more preferably, a URL
to download that package) to me.  Thanks!

* Notes for Windows users

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

    http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/nmake15.exe

If you are connected to the internet, "perl Makefile.PL" is capable
of automatically fetch it, and install into your Perl/bin directory.
You will see a message like this:

    The required 'nmake' executable not found, fetching it...

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.

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. MinGW, GCC on Cygwin, or Microsoft Visual C++ for ActivePerl),
and nobody has generated a Windows-specific PAR-Packer yet, you will not
be able to generate binary executables using 'pp'.

Microsoft Visual C++ users: Do not forget to run "vcvars32.bat" (or equivalent)
before "perl Makefile.PL"!

* 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. (Note: This might not
apply any more.)

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

* Source Repository

You can check out the most recent revision from PAR's Subversion repository:

    http://svn.openfoundry.org/par/PAR-Packer

Same applies to the main PAR distribution:

    http://svn.openfoundry.org/par/trunk

There is anonymous access to all. Commit access is handed out liberally;
contact the mailing list for details.

* Contact

<http://par.perl.org/> is the official PAR website.  You can write
to the mailing list at <par@perl.org>, or send an empty mail to
<par-subscribe@perl.org> to participate in the discussion.

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

* Copyright

Copyright 2002-2010 by Audrey Tang <cpan@audreyt.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>.
