March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center1 How to write Perl Modules Some practical advice about how to build a perl module March 21, 2003 – Stanford Linear Accelerator Center Fabrizio Coccetti

March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center2Agenda What a Perl Module is Why it is convenient to use Perl Modules How to make Perl Modules An example of a Perl Module Preparing the package for shipping Perl Module are easy to make and handy to use

March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center3 What a Perl Module is A Perl Module is a self-contained piece of [Perl] code that can be used by a Perl program (or by other Perl modules) It is conceptually similar to: a C link library a C++/Java class

March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center4 Why it is convenient to use PMs Installation is straightforward: perl Makefile.PL; make; make install The Perl interpreter has a list of directories in which it searches for modules (global Installation is platform independent (Solaris, Linux, Windows, …) Easy to use in Perl Programs: use IPEM::PingER Easy to update both for the maintainers of a Perl Module and system administrators at remote sites Time saving technique !!

March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center5 Before making a PM Chose an appropriate name for the PM Each Perl Module has an unique name. Perl provides a hierarchal name space for modules, similar to the name space for Java classes. Components of a module name are separated by double colons “::”. i.e. IEPM::PingER

March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center6 Let’s start to make a Perl Module Create the Perl Module Tree: -A omits the Autoloader code (best used by modules that define a large number of infrequently used subroutines) -X omits XS elements (eXternal Subroutine, where eXternal means external to Perl, i.e. C) -n specifies the name of the module $ h2xs -AX -n IEPM::PingER

March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center7 What h2xs does for the developer Creates subdirs:./IEPM/PingER/ Creates the following files and the t/ dir: Changes Makefile.PL MANIFEST (contains the list of all files in the package ) README t/ (test files) PingER.pm (perl code goes here)

March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center8 Some advice on writing the code of a PM A PM can use other PMs use strict; (i.e. $IEPM::PingER::var) use 5.6.1; = qw(ping_it); sub ping_it {… … …} 1; __END__

March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center9 How to use a PM in a Perl program Another way is to in the Perl = qw(ping_it log_it); And in the Perl Program use IEPM::PingER qw(log_it) use IEPM::PingER; $answer = ping_it (host.domain.edu);

March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center10 Use Carp in Perl Modules The Carp module allows to present error messages from the caller's perspective warn "No hostname given"; No hostname given at /usr/local/lib/perl5/site_perl/5.6/IEPM/PingER.pm line 143. carp "No hostname given"; No hostname given at perl_script.pl line 5. use Carp; warn carp die croak Recipe:

March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center11 Example: the beginning of IEPM::PingER package IEPM::PingER; use 5.008; use strict; use warnings; use Carp; require Exporter; = qw(Exporter); use Time::CTime; use DB_File; = qw(log_it ping_it); our $VERSION = '1.03';

March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center12 Example: the subroutine ping_it PingER.PM sub ping_it { my ($ping_cmd,$dest_name,$dest_ip, $ping_interval, $ping_size, $ping_count) … … … … return ($time, $packets_sent, $packets_rcvd, $min, $avg, $max, } timeping.pl use IEPM::PingER; ($time, $packets_sent, $packets_rcvd, $min, $avg, $max, $seqno, $pingtimes) = ping_it($ping_cmd,$dest_name,$dest_ip, $ping_interval, 1000, $ping_count);

March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center13 Preparing the package for shipping Prepare the package for shipping is straightforward: $ perl Makefile.PL; make; make dist; The commands above create the compressed archive: IEPM-PingER-1.03.tar.gz

March 21, 2003 Fabrizio Coccetti - Stanford Linear Accelerator Center14References Perl Module Mechanics The Perl Module Library Perl Modules The Perl 5 Modules List Practical Perl Programming Perlnewmod - preparing a new module for distribution