/ 
PAR-0.45
River stage two • 7 direct dependents • 14 total dependents
/ par.pl

NAME

par.pl - Make and Run Perl Archives

SYNOPSIS

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

To use Hello.pm from ./foo.par:

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

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

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

Run test.pl or script/test.pl from foo.par:

% par.pl foo.par test.pl	# only when $ARGV[0] ends in '.par'
% par.pl foo.par		# looks for 'main.pl' by default

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

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

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

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

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

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

This is particularly useful when making stand-alone binary executables; see makepar.pl for details.

DESCRIPTION

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

If you have a C compiler, a binary version of par.pl will also be automatically installed. You can use it to run .par files:

# runs script/run.pl in archive, uses its lib/* as libraries
% par.exe myapp.par run.pl	# runs run.pl or script/run.pl in myapp.par

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

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

Finally, as an alternative to Perl2exe or PerlApp, the -O option makes a stand-alone binary from a PAR file:

% par.exe -B -Omyapp myapp.par
% ./myapp			# run it anywhere without perl binaries
% ./myapp -Omyap2 myapp.par	# makes a ./myap2, identical to ./myapp
% ./myapp -Omyap3 myap3.par	# makes another app with different PAR

The format for the stand-alone executable is simply concatenating the following elements:

  • The executable itself

    Either in plain-text (par.pl) or native executable format (par or par.exe).

  • Any number of embedded files

    These are typically used for bootstrapping PAR's various XS dependencies. Each section begins with the magic string "FILE", length of file name in pack('N') format, file name (auto/.../), file length in pack('N'), and the file's content (not compressed).

  • One PAR file

    This is just a zip file beginning with the magic string "PK\003\004".

  • Ending section

    A pack('N') number of the total length of FILE and PAR sections, followed by a 8-bytes magic string: "\012PAR.pm\012".

NOTES

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

# put a main.pl inside myapp.par to run it automatically
% par -O./myapp myapp.par

The -B flag described earlier is particularly useful here, to build a truly self-containing executable:

# bundle all needed shared objects (or F<.dll>s)
% par -B -O./myapp myapp.par

SEE ALSO

PAR, pp

AUTHORS

Autrijus Tang <autrijus@autrijus.org>

COPYRIGHT

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

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

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