RE: creating a standard Perl module

Orton, Yves Thu, 02 Oct 2003 03:04:04 -0700

Title: RE: creating a standard Perl module

> My Perl Cookbook says I should use this command to initialize
> my project:
>
> h2xs -XA -n MyLibrary
>
> Fine, but I never expect to have an actual package named MyLibrary.pm.
> Instead, I suspect I will have various sub-packages such as
> MyLibrary::Librarian, MyLibrary::Resource, and MyLibrary::Patron.
> Consequently, I could do this:
>
> h2xs -XA -n MyLibrary::Librarian
>
> Unfortunately, this invocation creates a Librarian directory with all the
> necessary files, and if I were to do this for each of my packages, then I
> would have bunches o' MANIFESTs to keep up with. Non-standard.

Actually not necessarily. ExtUtils::MakeMaker has considerable support for this model of distribution.

Personally its not my favorite way to go, but it is doable and it is CPAN compliant.

Have a look at the libwin distro.

> Assuming my MyLibrary module is going to have many
> sub-packages, how do I create the skeleton of my module with the h2xs command?

h2xs contrary to appearances (insofar as pure perl projects go) isnt really intended to set up a skeleton of your _module_. Its there to set up a skeleton of the _distribution_ package.

> On the other hand, maybe I should have a file named MyLibrary.pm and all it
> contains is a version number, abstract, and pointers to the
> sub-packages?

Ok. Heres how I would procede (im assuming from what I could find on Google (your links didnt resolve for me) that the module really should be called CGI::MyLibrary, adjust accordingly :-) so we start with h2xs....

h2xs -XA -n CGI::MyLibrary

This will produce the files:

Writing CGI/MyLibrary/MyLibrary.pm
Writing CGI/MyLibrary/Makefile.PL
Writing CGI/MyLibrary/README
Writing CGI/MyLibrary/test.pl
Writing CGI/MyLibrary/Changes
Writing CGI/MyLibrary/MANIFEST

Now go in to the MyLibrary directory and create a ./t directory. Move and rename test.pl to ./t/MyLibrary.t (this is useful for later and you might as well do it now. I would also edit MyLibrary.t to use Test::More and use_ok instead of the normal test template)

Now you have two choices, you can either create a directory called CGI or create a directory called lib/CGI. You can and I do on occasion use both. I prefer to use the lib directory to store modules that I _need_ for the rest of my code (such as cpan modules) but arent by me (dont do this for a CPAN released module, but for internal use only it can be useful), and use the named subdriectory (CGI in this case) for the main modules in the distribution. Having made your decisions move MyLibrary.pm into the newly created directory.

So now things should look like this:

Now edit makefile.pl youll want to put your name in there and any prereqs youll need. Now here is where you need to start making some decisions. Do you want to have a root module that brings the rest into play? (probably yes, in which case this should probably be CGI::MyLibrary) If it is yes then you dont have to change anything in makefile.pl but your name and the values for VERSION_FROM (if you have it) and ABSTRACT_FROM to other values. Most likely you'll want them to point at 'CGI/MyLibrary.pm'. However you may want to have a distribution specific version, in which case edit the call to WriteMakefile to contain a VERSION entry instead of a VERSION_FROM entry.

Now, delete MANIFEST and invoke the following:

(perl Makefile.PL) && (nmake manifest) && nmake dist

This will rebuild your MANIFEST to respect the new structure and a new file CGI-MyLibrary-0.01.tar.gz which contains your distribution skeleton. Unpack this somewhere sensible. When I say sensible I mean somewhere where you plan to do your work. For instance I have a directory called D:\Perl\Build\ which is where I would unpack it. Now edit your PERL5LIB enviornment to variable to point at the new directory for instance on my system it would be

D:\Perl\Build\CGI-MyLibrary-0.01

(I actually often remove the version number at this point.)

Now you can delete the original stuff created by h2xs. (Note that you could just as easily move the entire tree created by h2xs from /CGI/MyLibrary/ on over or whatever. I find the pack/unpack catches bugs. Also i suppose you dont need to do this step at all, I prefer it as i like to have all the distributions I work on rooted in a single directory and I find it less confusing and annoying to work on

D:\Perl\Build\CGI-MyLibrary\CGI\Mylibrary.pm

than on

D:\Perl\Build\CGI\MyLibrary\CGI\MyLibrary.pm

)

Now you are ready to develop your modules in the newly created directory. The root of which is treated akin to perl/site/lib and perl/lib meaning you can run your test scripts without using test harness, or with them, they will work equally well.

As you need to add new modules simply put them in the ./CGI subdir as required (if you know in advance what you intend to have you could just copy the MyLibrary.pm to the appropriate names and places and then edit as required). For instance with the modules you mentioned above the following might be the scenario:

So long as you update MANIFEST before you build a new distro (delete it and run nmake manifest, dont forget to delete .bak files or other crud that may get in the directory first)

So the result is that you can work on your distro without using (n)make as your modules are implicitly already in your perl library tree. You can also add and extend modules easily as you go.

I hope this helps you on your way and isnt too confusing.

Regards,
Yves

RE: creating a standard Perl module

Reply via email to