The document provides guidance on how to create and distribute Perl modules. It discusses what Perl modules are, why they are useful, and how to structure, write, test, and package a module for distribution. Key steps include using the h2xs tool to generate module scaffolding, writing the module code in the .pm file with best practices like strict and warnings, testing the module, and creating a compressed archive for distribution.

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

2. Agenda 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

3. 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

4. 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 array @INC) 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 !!

5. 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

6. 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

7. 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)

8. 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; $VERSION=’1.03’; @EXPORT = qw(ping_it); sub ping_it {… … …} 1; __END__

9. How to use a PM in a Perl program Another way is to use @EXPORT_OK in the Perl Module: @EXPORT_OK = 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);

10. 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. Recipe: use Carp; warn carp die croak

11. Example: the beginning of IEPM::PingER package IEPM::PingER; use 5.008; use strict; use warnings; use Carp; require Exporter; our @ISA = qw(Exporter); use Time::CTime; use DB_File; our @EXPORT = qw(log_it ping_it); our $VERSION = '1.03';

12. 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, \@seqno, \@pingtimes) ; } 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);

13. 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

14. References Perl Module Mechanics http:// world.std.com/~swmcd/steven/perl/module_mechanics.html The Perl Module Library http://search.cpan.org/author/JHI/perl-5.8.0/pod/perlmodlib.pod Perl Modules http://search.cpan.org/author/JHI/perl-5.8.0/pod/perlmod.pod The Perl 5 Modules List http://www.cpan.org/modules/00modlist.long.html Practical Perl Programming http://www.cs.cf.ac.uk/Dave/PERL/node131.html Perlnewmod - preparing a new module for distribution http://www.perlpod.com/5.6.1/perlnewmod.html