Difference between revisions of "Creating a Perl Module"

From Organic Design wiki
(Templates added for creating perl modules including using Exporter for short names)
m
 
(5 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
{{procedure
 
{{procedure
−
|description = This procedure defines the steps required to package up a collection of subroutines and other official packages into proper Perl modules which can be installed from a script with ''use OrganicDesign::Wiki'' for example. These modules can then be installed into the Perl environment as part of the [[Debian Post Install]].
+
|description = This procedure defines the steps required to package up a collection of subroutines and other official packages into proper Perl modules which can be installed from a script with ''use OrganicDesign::Wiki'' for example. These modules can then be installed into the Perl environment as part of the [[Debian Post Install]].
−
|role = dev
+
| role = dev
 +
| status = in use
 
}}
 
}}
 +
A Perl module is essentially just a ''.pm'' file which has a specific structure allowing it to extend the native Perl runtime environment to add new namespaces, objects and subroutines etc. The ''.pm'' structure also allows for automatically generated documentation.
  
−
==Package template==
+
== Create package skeleton ==
−
Creating a perl package requires a namespace to be specified, and an exit signal of 1 after reading a perl module.
+
To ensure that the module is added to the operating system environment properly, it should be wrapped into a ''package'' so that it can be installed with ''make'' and ''make install'' in the usual way. We use the [http://linux.about.com/library/cmd/blcmdl1_h2xs.htm h2xs] utility to create an initial functional package template.
−
{{code|<perl>
+
h2xs -XAn OrganicDesign::Example
−
#!/usr/bin/perl
+
This will create a working structure which can be installed and then included in a Perl script with ''use OrganicDesign::Wiki''.
  
−
use strict;
+
== Modify the module file ==
−
use warnings;
+
In the directory structure created by ''h2xs'' is a subdirectory called ''lib'' which contains a template ''.pm'' module file which can be refined and extended to your needs. Generally the first thing to do would be to add comments at the beginning describing the module, and edit the documentation section at the end. Then create a constructor and other required methods. See [[:OrganicDesign::Wiki.pm]] for an example of one of our modules.
  
−
# Convention: Package namespace is capitalized
+
== Install the package ==
−
package MyModule;
+
Change into the directory generated by ''h2xs'', then install as usual:
−
# Some perl functions
+
cd OrganicDesign-Example
 +
perl Makefile.PL
 +
make
 +
make install
 +
To test that it has installed into the environment correctly, you can see if you can bring up its manual page:
 +
man OrganicDesign::Example
 +
Then create a test script to see if it can be used from within the Perl environment properly.
  
−
# Library returns true when read in
+
== See also ==
−
1;
 
−
</perl>}}
 
−
 
 
−
===Exporting names===
 
−
The ''Exporter'' package allows convenient short names with the tradeoff of polluting your namespace. See <code>perldoc Exporter</code>
 
−
 
 
−
{{code|<perl>
 
−
#!/usr/bin/perl
 
−
 
 
−
use strict;
 
−
use warnings;
 
−
 
 
−
# Convention: Package namespace is capitalized
 
−
package MyModule;
 
−
require Exporter;
 
−
@ISA = qw(Exporter);
 
−
 
 
−
# Provide a list of function names to export
 
−
@EXPORT_OK = qw(...);
 
−
 
 
−
# Some perl functions
 
−
 
 
−
# Library returns true when read in
 
−
1;
 
−
</perl>}}
 
−
===Defining the path===
 
−
The package needs to be located in the @INC path where a perl script can load and use it.
 
−
{{code|<perl>
 
−
perl -e 'BEGIN{$"="\n"}; print "@INC\n"';
 
−
/etc/perl
 
−
/usr/local/lib/perl/5.8.8
 
−
/usr/local/share/perl/5.8.8
 
−
/usr/lib/perl5
 
−
/usr/share/perl5
 
−
/usr/lib/perl/5.8
 
−
/usr/share/perl/5.8
 
−
/usr/local/lib/site_perl
 
−
.              # <-- Current working directory
 
−
 
 
−
</perl>}}
 
−
You can add a new path to @INC with;
 
−
{{code|<perl>
 
−
use lib "/full/path/to/file";
 
−
</perl>}}
 
−
inside perl scripts. However, this is hardcoded into the program itself. If you want to specify aditional @INC path information, they environment variable PERL5LIB can be used, e.g. 
 
−
{{code|<perl>
 
−
# Direct assignment
 
−
setenv PERL5LIB /my/perl/modules
 
−
 
 
−
# Appending path
 
−
PERL5LIB = $PERL5LIB:/my/perl/modules
 
−
</perl>}}
 
−
 
 
−
{{todo|
 
−
We need to make a general package first which:
 
−
*Collects a bunch of functions we use into one includable module
 
−
*Makes the module installable as one of potentially many modules within ''OrganicDesign::''
 
−
*Adds the installation of it into the [[Debian Post Install]]
 
−
*Ensure easy upgradability (maybe by packaging into a debian package), see [[Creating a Debian package]]
 
−
}}
 
−
== Example ==
 
−
<perl>
 
−
 
 
−
 
 
−
use OD::Wiki;
 
−
$odwiki = OD::Wiki->new(
 
−
url  => 'http://www.organicdesign.co.nz',
 
−
user => 'foo',
 
−
pass => 'bar'
 
−
);
 
−
 
 
−
$odwiki->edit(
 
−
title  => 'MyArticle',
 
−
content => '[[foo]]',
 
−
summary => 'testing',
 
−
minor  => 1
 
−
);
 
−
</perl>
 
−
 
 
−
==See also==
 
 
*[http://www.perlmonks.org/index.pl?node_id=431702 José's Guide for creating Perl modules]
 
*[http://www.perlmonks.org/index.pl?node_id=431702 José's Guide for creating Perl modules]
 
*[http://www.perl.com/lpt/a/995 Making Perl Reusable with Modules - users Module::starter]
 
*[http://www.perl.com/lpt/a/995 Making Perl Reusable with Modules - users Module::starter]
Line 104: Line 32:
 
*[http://world.std.com/~swmcd/steven/perl/module_mechanics.html Perl Module Mechanics]
 
*[http://world.std.com/~swmcd/steven/perl/module_mechanics.html Perl Module Mechanics]
 
*[http://www.perlmonks.org/index.pl?node_id=431702 José's Guide for creating Perl modules]
 
*[http://www.perlmonks.org/index.pl?node_id=431702 José's Guide for creating Perl modules]
 +
*[http://www.vromans.org/johan/articles/makemaker.html Makemaker made easy]

Latest revision as of 08:51, 31 August 2008

Procedure.svg Creating a Perl Module
Organic Design procedure

A Perl module is essentially just a .pm file which has a specific structure allowing it to extend the native Perl runtime environment to add new namespaces, objects and subroutines etc. The .pm structure also allows for automatically generated documentation.

Create package skeleton

To ensure that the module is added to the operating system environment properly, it should be wrapped into a package so that it can be installed with make and make install in the usual way. We use the h2xs utility to create an initial functional package template. 

h2xs -XAn OrganicDesign::Example

This will create a working structure which can be installed and then included in a Perl script with use OrganicDesign::Wiki.

Modify the module file

In the directory structure created by h2xs is a subdirectory called lib which contains a template .pm module file which can be refined and extended to your needs. Generally the first thing to do would be to add comments at the beginning describing the module, and edit the documentation section at the end. Then create a constructor and other required methods. See OrganicDesign::Wiki.pm for an example of one of our modules.

Install the package

Change into the directory generated by h2xs, then install as usual: 

cd OrganicDesign-Example
perl Makefile.PL
make
make install

To test that it has installed into the environment correctly, you can see if you can bring up its manual page: 

man OrganicDesign::Example

Then create a test script to see if it can be used from within the Perl environment properly.

See also

Retrieved from "https://organicdesign.nz/wiki/index.php?title=Creating_a_Perl_Module&oldid=86814"