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

NAME

par.pl - Run Perl Archives

SYNOPSIS

To use Hello.pm, lib/Hello.pm or arch/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

You can also 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 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		# takes care of XS dependencies

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.

The main purpose of this utility is to be feed to perlcc:

% perlcc -o par par.pl

and use the resulting stand-alone executable par to run .par files:

# runs script/run.pl in archive, uses its lib/* as libraries
% par 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 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 -Omyapp myapp.par	# makes a stand-alone executable
% ./myapp run.pl		# same as above
% ./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 shared objects

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

    Finally there must be a 8-bytes magic string: "\012PAR.pm\012".

NOTES

After installation, if you want to enable stand-alone binary support, please apply the included patch to the B::C module first (5.8.0 only, 5.6.1 does not need this):

% patch `perl -MB::C -e'print $INC{"B/C.pm"}'` < patches/perl580.diff

and then:

% perlcc -o /usr/local/bin/par script/par.pl

Afterwards, you can generate self-executable PAR files 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, perlcc

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