=head1 NAME

parl - Binary PAR Loader

=head1 SYNOPSIS

(Please see L<pp> for convenient ways to make self-contained
executables, scripts or PAR archives from perl programs.)

To make a I<PAR distribution> from a CPAN module distribution:

    % parl -p                 # make a PAR dist under the current path
    % parl -p Foo-0.01        # assume unpacked CPAN dist in Foo-0.01/

To manipulate a I<PAR distribution>:

    % parl -i Foo-0.01-i386-freebsd-5.8.0.par	# install
    % parl -i http://foo.com/Foo-0.01		# auto-appends archname + perlver
    % parl -i cpan://AUTRIJUS/PAR-0.74		# uses CPAN author directory
    % parl -u Foo-0.01-i386-freebsd-5.8.0.par   # uninstall
    % parl -s Foo-0.01-i386-freebsd-5.8.0.par   # sign
    % parl -v Foo-0.01-i386-freebsd-5.8.0.par   # verify

To use F<Hello.pm> from F<./foo.par>:

    % parl -A./foo.par -MHello 
    % parl -A./foo -MHello	# the .par part is optional

Same thing, but search F<foo.par> in the F<@INC>;

    % parl -Ifoo.par -MHello 
    % parl -Ifoo -MHello 	# ditto

Run F<test.pl> or F<script/test.pl> from F<foo.par>:

    % parl foo.par test.pl	# looks for 'main.pl' by default,
				# otherwise run 'test.pl' 

To make a self-containing executable containing a PAR file :

    % parl -O./foo foo.par
    % ./foo test.pl		# same as above

To embed the necessary non-core modules and shared objects for PAR's
execution (like C<Zlib>, C<IO>, C<Cwd>, etc), use the B<-b> flag:

    % parl -b -O./foo foo.par
    % ./foo test.pl		# runs anywhere with core modules installed

If you also wish to embed I<core> modules along, use the B<-B> flag
instead:

    % parl -B -O./foo foo.par
    % ./foo test.pl		# runs anywhere with the perl interpreter

This is particularly useful when making stand-alone binary
executables; see L<pp> for details.

=head1 DESCRIPTION

This stand-alone command offers roughly the same feature as C<perl
-MPAR>, except that it takes the pre-loaded F<.par> files via
C<-Afoo.par> instead of C<-MPAR=foo.par>.

Additionally, it lets you convert a CPAN distribution to a PAR
distribution, as well as manipulate such distributions.  For more
information about PAR distributions, see L<PAR::Dist>.

You can use it to run F<.par> files:

    # runs script/run.pl in archive, uses its lib/* as libraries
    % parl myapp.par run.pl	# runs run.pl or script/run.pl in myapp.par
    % parl otherapp.pl		# also runs normal perl scripts

However, if the F<.par> archive contains either F<main.pl> or
F<script/main.pl>, it is used instead:

    % parl myapp.par run.pl	# runs main.pl, with 'run.pl' as @ARGV

Finally, the C<-O> option makes a stand-alone binary executable from a
PAR file:

    % parl -B -Omyapp myapp.par
    % ./myapp			# run it anywhere without perl binaries

With the C<--par-options> flag, generated binaries can act as C<parl>
to pack new binaries: 

    % ./myapp --par-options -Omyap2 myapp.par	# identical to ./myapp
    % ./myapp --par-options -Omyap3 myap3.par	# now with different PAR

For an explanation of stand-alone executable format, please see L<par.pl>.

=head1 SEE ALSO

L<PAR>, L<PAR::Dist>, L<par.pl>, L<pp>

=head1 AUTHORS

Audrey Tang E<lt>cpan@audreyt.orgE<gt>

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

Please submit bug reports to E<lt>bug-par@rt.cpan.orgE<gt>.

=head1 COPYRIGHT

Copyright 2002, 2003, 2004, 2005, 2006 by Audrey Tang
E<lt>cpan@audreyt.orgE<gt>.

Neither this program nor the associated L<pp> program impose any
licensing restrictions on files generated by their execution, in
accordance with the 8th article of the Artistic License:

    "Aggregation of this Package with a commercial distribution is
    always permitted provided that the use of this Package is embedded;
    that is, when no overt attempt is made to make this Package's
    interfaces visible to the end user of the commercial distribution.
    Such use shall not be construed as a distribution of this Package."

Therefore, you are absolutely free to place any license on the resulting
executable, as long as the packed 3rd-party libraries are also available
under the Artistic License.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

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

=cut