PAR::Tutorial - Cross-Platform Packaging and Deployment with PAR This is a tutorial on PAR, first appeared at the 7th Perl Conference. The HTML version of this tutorial is available online as <http://aut.dyndns.org/par-tutorial/>.

On Deploying Perl Applications
% sshnuke.pl 10.2.2.2 -rootpw="Z1ON0101" Perl v5.6.1 required--this is only v5.6.0, stopped at sshnuke.pl line 1. BEGIN failed--compilation aborted at sshnuke.pl line 1.

PAR, the Perl Archive Toolkit
% pp -o sshnuke.exe sshnuke.pl # stand-alone executable!

Simple Packaging
% zip foo.par Hello.pm World.pm # pack two modules % zip -r bar.par lib/ # grab all modules in lib/ use PAR; use lib "foo.par"; # the .par part is optional use Hello; use PAR "/home/mylibs/*.par"; # put all of them into @INC use Hello;

PAR Loaders
% par.pl foo.par # looks for 'main.pl' by default % par.pl foo.par test.pl # runs script/test.pl in foo.par % parl foo.par # no perl or PAR.pm needed! % parl foo.par test.pl # ditto % par.pl -b -O./foo.pl foo.par # self-contained script % parl -B -O./foo.exe foo.par # self-contained binary

Dependency Scanning
% scandeps.pl sshnuke.pl # Legend: [C]ore [X]ternal [S]ubmodule [?]NotOnCPAN 'Crypt::SSLeay' => '0', # X # 'Net::HTTP' => '0', # # 'Crypt::SSLeay::X509' => '0', # S # Crypt::SSLeay 'Net::HTTP::Methods' => '0', # S # Net::HTTP 'Compress::Zlib' => '0', # X # Net::HTTP::Methods % scandeps.pl -V -e "use Dynaloader;" ... # auto/DynaLoader/dl_findfile.al [autoload] # auto/DynaLoader/extralibs.ld [autoload] # auto/File/Glob/Glob.bs [data] # auto/File/Glob/Glob.so [shared] ...

Perl Packager: "pp"
% pp -o out.exe src.pl # self-contained .exe % out.exe # runs anywhere on the same OS % pp -o out.exe -M CGI src.pl # pack CGI + its dependencies, too % pp -o out.exe -e 'print "Hi!"' # turns one-liner into executable % pp -p src.pl # makes 'source.par' % pp -B -p src.pl # include core modules

How it works
% pp --gui --verbose --output=out.exe src.pl

Aggregating multiple programs
> I have used pp to make several standalone applications which work > great, the only problem is that for each executable that I make, I am > assuming the parl.exe is somehow bundled into the resulting exe. You can ship parl.exe by itself, along with .par files built by "pp -p", and run those PAR files by associating them to parl.exe. % pp --output=a.out a.pl b.pl # two scripts in one! % ln a.out b.out # symlink also works % ./a.out # runs a.pl % ./b.out # runs b.pl

Cross-platform Packages
C:\> pp --multiarch --output=out.par src.pl ...copy src.pl and out.par to a Finix machine... % pp --multiarch --output=out.par src.pl % parl out.par # runs src.pl % perl -MPAR=out.par -e '...' # uses modules inside out.par

The Anatomy of a PAR file
/ # casual packaging only /lib/ # standard location /arch/ # for creating from blib/ /i386-freebsd/ # i.e. $Config{archname} /5.8.0/ # i.e. Perl version number /5.8.0/i386-freebsd/ # combination of the two above / # casual packaging only /script/ # standard location /shlib/(5.8.0/)?(i386-freebsd/)? /par/(5.8.0/)?(i386-freebsd/)?

Special files

Advantages over perlcc, PerlApp and Perl2exe

MANIFEST: Best viewed with Mozilla
jar:file:///home/autrijus/foo.par!/MANIFEST

META.yml: Metadata galore
build_requires: {} conflicts: {} dist_name: out.par distribution_type: par dynamic_config: 0 generated_by: 'Perl Packager version 0.03' license: unknown par: clean: 0 signature: '' verbatim: 0 version: 0.68

SIGNATURE: Signing and verifying packages
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 SHA1 8a014cd6d0f6775552a01d1e6354a69eb6826046 AUTHORS ... -----BEGIN PGP SIGNATURE----- ... -----END PGP SIGNATURE----- % pp -s -o foo.par bar.pl # make and sign foo.par from bar.pl % cpansign -s foo.par # sign this PAR file % cpansign -v foo.par # verify this PAR file

Perl Servlets with Apache::PAR
Alias /myapp/cgi-perl/ ##PARFILE##/ <Location /myapp/cgi-perl> Options +ExecCGI SetHandler perl-script PerlHandler Apache::PAR::Registry </Location>

Hon Dah, A-par-che!
# use the "web.conf" from the previous slide % pp -p -o hondah.par -e 'print "Hon Dah!\n"' \ --add web.conf % chmod a+x hondah.par <IfDefine MODPERL2> PerlModule Apache2 </IfDefine> PerlAddVar PARInclude /home/autrijus/hondah.par PerlModule Apache::PAR % GET http://localhost/myapp/cgi-perl/main.pl Hon Dah!

On-demand library fetching
use PAR; use lib 'http://aut.dyndns.org/par/DBI-latest.par'; use DBI; # always up to date!

Code Obfuscation

Accessing packed files
my $zip = PAR::par_handle($0); # an Archive::Zip object my $content = $zip->contents('MANIFEST'); my $content = PAR::read_file('MANIFEST'); use PAR '/home/mylibs/*.par'; while (my ($filename, $zip) = each %PAR::LibCache) { print "[$filename - MANIFEST]\n"; print $zip->contents('MANIFEST'); }

Packing GUI applications
# search for libncurses under library paths and pack it % pp -l ncurses curses_app.pl # same for Tk, Wx, Gtk, Qt... # pack 'src.pl' into a console-less 'out.exe' (Win32 only) % pp --gui -o out.exe src.pl

Precompiled CPAN distributions
# same old Makefile.PL, with a few changes use inc::Module::Install; # was "use ExtUtils::MakeMaker;" WriteMakefile( ... ); # same as the original check_nmake(); # make sure the user have nmake par_base('AUTRIJUS'); # your CPAN ID or a URL fetch_par() unless can_cc(); # use precompiled PAR only if necessary

Platform-specific Tips

Thank you!

Bonus Slides: PAR Internals

Overview of PAR.pm's Implementation

Code References in @INC
push @INC, sub { my ($coderef, $filename) = @_; # $coderef is \&my_sub open my $fh, "wget ftp://example.com/$filename |"; return $fh; # using remote modules, indeed! }; open my $fh, '<', \($zip->memberNamed($filename)->contents); return $fh;

Source Filtering without Filter::* Modules
# Force all modules used to use strict and warnings open my $fh, "<", $filename or return; my @lines = ("use strict; use warnings;\n", "#line 1 \"$full\"\n"); return ($fh, sub { return 0 unless @lines; push @lines, $_; $_ = shift @lines; return length $_; });

Source Filtering without Filter::* Modules (cont.)
# Return all contents line-by-line from the file inside PAR my @lines = split( /(?<=\n)/, $zip->memberNamed($filename)->contents ); return (sub { $_ = shift(@lines); return length $_; });

Overriding DynaLoader::bootstrap

Anatomy of a Self-Contained PAR executable

Self-Bootstrapping Tricks

Thank you (again)!
<http://www.autrijus.org/par-tutorial/> <http://www.autrijus.org/par-intro/> (English version) <http://www.autrijus.org/par-intro.zh/> (Chinese version) PAR, pp, par.pl, parl ex::lib::zip, Acme::use::strict::with::pride App::Packer, Apache::PAR, CPANPLUS, Module::Install Autrijus Tang <autrijus@autrijus.org> <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 2003, 2004, 2005 by Autrijus Tang <autrijus@autrijus.org>. This document is free documentation; you can redistribute it and/or modify it under the same terms as Perl itself. See <http://www.perl.com/perl/misc/Artistic.html>