Beefy Boxes and Bandwidth Generously Provided by pair Networks
Just another Perl shrine

Starting the development of a module : thoughts

by Masem (Monsignor)
on Jun 28, 2001 at 23:20 UTC ( #92423=perlmeditation: print w/replies, xml ) Need Help??

I've been wrangling with the lack of documentation on how to start a module that one would expect CPAN inclusion at some point. Not that the docs aren't there, but there's nothing coherent to them and are spread throughout time and space, at least in the standard perl documentation space (including info from CPAN and PAUSE). While learning by example (other CPAN modules) works, it's not always intuitive. So I am considering at least putting a tutorial or a howto together on how to go about doing this, partially for myself, and partially for the community as a whole.
Note that if you have a better reference already, please let me know, I'd rather not reinvent the wheel.

The steps, as I see it (and will be trying in the very near future) appear to go along these lines:

  • Use "h2xs" to create a 'new' perl project within a new directory; if not using any lib stubs, the -X will only create perl files. This includes Makefile.PL, README, and
  • Create/move the library files into place in this new directory, making sure to define $VERSION
  • If tests are desired, either create them in, or delete, create a directory 't', and within 't', name any scripts that are part of the test suite as '*.t'.
  • use "perl Makefile.PL" to create a unix-compat makefile.
  • Edit README and other document files to liking.
  • At this point, one has a nearly complete package; at this point, a program like CVS can be used to maintain version control.
  • Use "make; make build; make test" to make sure everything works as expected, and edit as necessary.
  • Use "make clean" to return to a distribution-ready directory structure.
  • Distribute as necessary.
Obviously, this doesn't cover a large number of possible situations, but from what I can tell from the docs, this is sufficiently adequete for perl-only modules. Am I missing any key steps, paying too little or too much attention to certain steps, or just am thinking completely wrong about this?

Dr. Michael K. Neylon - || "You've left the lens cap of your mind on again, Pinky" - The Brain
  • Comment on Starting the development of a module : thoughts

Replies are listed 'Best First'.
Re: Starting the development of a module : thoughts
by btrott (Parson) on Jun 29, 2001 at 03:27 UTC
    Here are some additional thoughts/steps.

    • h2xs automatically creates a MANIFEST file. I don't use it; I delete it. I like using 'make manifest', because it automatically generates a MANIFEST file for me when I want it. To do this, set up a MANIFEST.SKIP file. Here's an example of a standard one I use:
      \bCVS\b ^MANIFEST\. ^Makefile$ ~$ \.old$ ^blib/ ^pm_to_blib$ \.tar\.gz$
      With this in place, I don't have to maintain a list of all my files; 'make manifest' will start at the current directory and assemble a list of all files not matching the patterns in MANIFEST.SKIP, then write the names of those files to MANIFEST.

      So, to create a new distribution, I can do:

      perl Makefile.PL make manifest make dist
      I keep my MANIFEST.SKIP under source control but that's not really necessary.

    • What is 'make build'? My Makefiles don't have a 'build' target.

    • You might also want to get into some of the interesting things you can do with a Makefile.PL. You can make it sort of a 'configure' for your distribution.

      As an example, the Makefile.PL for Net::SSH::Perl lets the user choose whether to install the prereqs for SSH-1 or SSH-2 (or both), which means that if the user really only wants SSH-1 support, he/she doesn't have to install a bunch of modules he/she doesn't need. Of course, this also means you have to learn to love using require in your code, for runtime loading of modules. :)

      Another useful Makefile.PL "trick" is to a "does user have this module installed?" function:

      sub have_mod { my($mod, $ver) = @_; eval("use $mod" . ($ver ? " $ver;" : ";")); !$@; }
      This allows you to do your own prerequisite checking in Makefile.PL, because unfortunately, the prereq checking in the CPAN module depends on having an explicit list of args to PREREQ_PM; it actually parses your Makefile.PL to look for such a list. If you have, for example, this:
      PREREQ_PM => \%prereq,
      then it won't pick up the list of prereqs correctly. So if that list is dynamic, then you may need to do your own checking.
Re: Starting the development of a module : thoughts
by VSarkiss (Monsignor) on Jun 28, 2001 at 23:38 UTC
    The best source I've found for this is the chapter called "Writing Packages and Modules" in my favorite Perl book, Effective Perl Programming by Hall and Schwartz. I recommend it highly (the chapter as well as the rest of the book).

    Your list contains many of the same items in the chapter, with some differences. For example, I don't think it makes any reference to using version control, although that would be a logical and useful addition. (I'm not certain whether it refers to version control or not -- I don't have the book with me right now.) They do include more specifics on PAUSE and registration, along with URLs to use to check for newer information.

Re: Starting the development of a module : thoughts
by blakem (Monsignor) on Jun 29, 2001 at 02:09 UTC
Re: Starting the development of a module : thoughts
by lhoward (Vicar) on Jun 28, 2001 at 23:23 UTC
    You're missing one of my favorites:
    make tardist
    Builds the .tar.gz for distribution.
      Unless you add some parameters to Makefile.PL (see ExtUtils::MakeMaker), the default (at least where I am) is 'compress' instead of 'gzip' so you end up with a .tar.Z file.
Re: Starting the development of a module : thoughts
by dragonchild (Archbishop) on Jun 28, 2001 at 23:26 UTC
    Are there examples anywhere of what goes into a test suite? How should one build it? Are there any gimmes&gotchas to building test suites? I think it would be neat just for maintenance of personal packages...
      What goes into tests is easy: this is the same concept as unit testing for object-oriented languages (C++ and Java). Basically you want to test every 'reasonable' object and function to make sure they work in every 'reasonable' test case that you can think of. While this can be a pain to add after your main program is said and done, the concept of unit testing is that these types of short codebits would be developed while you are developing the classes and functions, so inclusion into the test portions is trivial. Tests should basically make sure you are getting expected results from functions and code, such as:
      sub add { my ($a,$b) = @_; return $a+$b; } # Test code: print "not ok" if add(2,2) != 4;

      Now, what you actually print out is still a bit of a quandry for me; I know that there's info about it (that I happened upon luckily) at perldoc Test and perldoc Test::Harness. From my understanding (please correct me) is that the testing process sits at the end of STDOUT and intercepts everything. The first thing that the test scripts (as a whole) must print out is a "1..N\n" string, indicating the number of tests (=N). Each test then should print out "ok M\n" or "not ok M\n", where M is the specific test number. The test code runs all tests regardless of failures of previous ones, and reports the fraction of tests that failed at the end of the test cycle. When you install from CPAN, you'll see those test modules in action.

      And again, from the docs and other module examples, you either want one full, comprehensive test in the ./ file, or several small test files in ./t/*.t. In the latter case, tests are run in sorted order, which is why many people name files like "01test.t" as to have the specific tests executed in a logical order while still having the name printed out when CPAN-installing.

      Dr. Michael K. Neylon - || "You've left the lens cap of your mind on again, Pinky" - The Brain

Log In?

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: perlmeditation [id://92423]
Approved by root
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others surveying the Monastery: (3)
As of 2023-12-10 14:36 GMT
Find Nodes?
    Voting Booth?
    What's your preferred 'use VERSION' for new CPAN modules in 2023?

    Results (40 votes). Check out past polls.