packaging up the solution into a module and uploading it to CPAN so that
others can benefit.
+You should also take a look at L<perlmodstyle> for best practices in
+making a module.
+
=head2 Warning
We're going to primarily concentrate on Perl-only modules here, rather
Dig into a bunch of modules to see how they're written. I'd suggest
starting with L<Text::Tabs|Text::Tabs>, since it's in the standard
-library and is nice and simple, and then looking at something like
-L<Time::Zone|Time::Zone>, L<File::Copy|File::Copy> and then some of the
-C<Mail::*> modules if you're planning on writing object oriented code.
+library and is nice and simple, and then looking at something a little
+more complex like L<File::Copy|File::Copy>. For object oriented
+code, L<WWW::Mechanize> or the C<Email::*> modules provide some good
+examples.
These should give you an overall feel for how modules are laid out and
written.
There are a lot of modules on CPAN, and it's easy to miss one that's
similar to what you're planning on contributing. Have a good plough
-through the modules list and the F<by-module> directories, and make sure
-you're not the one reinventing the wheel!
+through L<http://metacpan.org> and make sure you're not the one
+reinventing the wheel!
=item Discuss the need
You might love it. You might feel that everyone else needs it. But there
might not actually be any real demand for it out there. If you're unsure
-about the demand you're module will have, consider sending out feelers
-on the C<comp.lang.perl.modules> newsgroup, or as a last resort, ask the
-modules list at C<modules@perl.org>. Remember that this is a closed list
-with a very long turn-around time - be prepared to wait a good while for
-a response from them.
+about the demand your module will have, consider asking the
+C<module-authors@perl.org> mailing list (send an email to
+C<module-authors-subscribe@perl.org> to subscribe; see
+L<https://lists.perl.org/list/module-authors.html> for more information
+and a link to the archives).
=item Choose a name
=over 3
-=item Start with F<h2xs>
+=item Start with F<module-starter> or F<h2xs>
+
+The F<module-starter> utility is distributed as part of the
+L<Module::Starter|Module::Starter> CPAN package. It creates a directory
+with stubs of all the necessary files to start a new module, according
+to recent "best practice" for module development, and is invoked from
+the command line, thus:
+
+ module-starter --module=Foo::Bar \
+ --author="Your Name" --email=yourname@cpan.org
+
+If you do not wish to install the L<Module::Starter|Module::Starter>
+package from CPAN, F<h2xs> is an older tool, originally intended for the
+development of XS modules, which comes packaged with the Perl
+distribution.
-Originally a utility to convert C header files into XS modules,
-L<h2xs|h2xs> has become a useful utility for churning out skeletons for
-Perl-only modules as well. If you don't want to use the
-L<Autoloader|Autoloader> which splits up big modules into smaller
-subroutine-sized chunks, you'll say something like this:
+A typical invocation of L<h2xs|h2xs> for a pure Perl module is:
- h2xs -AX -n Net::Acme
+ h2xs -AX --skip-exporter --use-new-tests -n Foo::Bar
-The C<-A> omits the Autoloader code, C<-X> omits XS elements, and C<-n>
-specifies the name of the module.
+The C<-A> omits the Autoloader code, C<-X> omits XS elements,
+C<--skip-exporter> omits the Exporter code, C<--use-new-tests> sets up a
+modern testing environment, and C<-n> specifies the name of the module.
=item Use L<strict|strict> and L<warnings|warnings>
the user will see something like this:
- No hostname given at /usr/local/lib/perl5/site_perl/5.6.0/Net/Acme.pm
- line 123.
+ No hostname given at
+ /usr/local/lib/perl5/site_perl/5.6.0/Net/Acme.pm line 123.
which looks like your module is doing something wrong. Instead, you want
to put the blame on the user, and say this:
=item Use L<Exporter|Exporter> - wisely!
-C<h2xs> provides stubs for L<Exporter|Exporter>, which gives you a
-standard way of exporting symbols and subroutines from your module into
-the caller's namespace. For instance, saying C<use Net::Acme qw(&frob)>
-would import the C<frob> subroutine.
+L<Exporter|Exporter> gives you a standard way of exporting symbols and
+subroutines from your module into the caller's namespace. For instance,
+saying C<use Net::Acme qw(&frob)> would import the C<frob> subroutine.
The package variable C<@EXPORT> will determine which symbols will get
exported when the caller simply says C<use Net::Acme> - you will hardly
The work isn't over until the paperwork is done, and you're going to
need to put in some time writing some documentation for your module.
-C<h2xs> will provide a stub for you to fill in; if you're not sure about
-the format, look at L<perlpod> for an introduction. Provide a good
-synopsis of how your module is used in code, a description, and then
-notes on the syntax and function of the individual subroutines or
-methods. Use Perl comments for developer notes and POD for end-user
-notes.
+C<module-starter> or C<h2xs> will provide a stub for you to fill in; if
+you're not sure about the format, look at L<perlpod> for an
+introduction. Provide a good synopsis of how your module is used in
+code, a description, and then notes on the syntax and function of the
+individual subroutines or methods. Use Perl comments for developer notes
+and POD for end-user notes.
=item Write tests
You're encouraged to create self-tests for your module to ensure it's
working as intended on the myriad platforms Perl supports; if you upload
your module to CPAN, a host of testers will build your module and send
-you the results of the tests. Again, C<h2xs> provides a test framework
-which you can extend - you should do something more than just checking
-your module will compile.
+you the results of the tests. Again, C<module-starter> and C<h2xs>
+provide a test framework which you can extend - you should do something
+more than just checking your module will compile.
+L<Test::Simple|Test::Simple> and L<Test::More|Test::More> are good
+places to start when writing a test suite.
-=item Write the README
+=item Write the F<README>
If you're uploading to CPAN, the automated gremlins will extract the
README file and place that in your CPAN directory. It'll also appear in
the main F<by-module> and F<by-category> directories if you make it onto
the modules list. It's a good idea to put here what the module actually
-does in detail, and the user-visible changes since the last release.
+does in detail.
+
+=item Write F<Changes>
+
+Add any user-visible changes since the last release to your F<Changes>
+file.
=back
=item Get a CPAN user ID
-Every developer publishing modules on CPAN needs a CPAN ID. See the
-instructions at C<http://www.cpan.org/modules/04pause.html> (or
-equivalent on your nearest mirror) to find out how to do this.
+Every developer publishing modules on CPAN needs a CPAN ID. Visit
+C<L<http://pause.perl.org/>>, select "Request PAUSE Account", and wait for
+your request to be approved by the PAUSE administrators.
-=item C<perl Makefile.PL; make test; make dist>
+=item C<perl Makefile.PL; make test; make distcheck; make dist>
-Once again, C<h2xs> has done all the work for you. It produces the
-standard C<Makefile.PL> you'll have seen when you downloaded and
-installs modules, and this produces a Makefile with a C<dist> target.
+Once again, C<module-starter> or C<h2xs> has done all the work for you.
+They produce the standard C<Makefile.PL> you see when you download and
+install modules, and this produces a Makefile with a C<dist> target.
Once you've ensured that your module passes its own tests - always a
-good thing to make sure - you can C<make dist>, and the Makefile will
+good thing to make sure - you can C<make distcheck> to make sure
+everything looks OK, followed by C<make dist>, and the Makefile will
hopefully produce you a nice tarball of your module, ready for upload.
=item Upload the tarball
log in to PAUSE, the Perl Authors Upload SErver. From the menus there,
you can upload your module to CPAN.
-=item Announce to the modules list
-
-Once uploaded, it'll sit unnoticed in your author directory. If you want
-it connected to the rest of the CPAN, you'll need to tell the modules
-list about it. The best way to do this is to email them a line in the
-style of the modules list, like this:
-
- Net::Acme bdpOP Interface to Acme Frobnicator servers FOOBAR
- ^ ^^^^^ ^ ^
- | ||||| Module description Your ID
- | |||||
- | ||||\-Public Licence: (p)standard Perl, (g)GPL, (b)BSD,
- | |||| (l)LGPL, (a)rtistic, (o)ther
- | ||||
- | |||\- Interface: (O)OP, (r)eferences, (h)ybrid, (f)unctions
- | |||
- | ||\-- Language: (p)ure Perl, C(+)+, (h)ybrid, (C), (o)ther
- | ||
- Module |\--- Support: (d)eveloper, (m)ailing list, (u)senet, (n)one
- Name |
- \---- Development: (i)dea, (c)onstructions, (a)lpha, (b)eta,
- (R)eleased, (M)ature, (S)tandard
-
-plus a description of the module and why you think it should be
-included. If you hear nothing back, that means your module will
-probably appear on the modules list at the next update. Don't try
-subscribing to C<modules@perl.org>; it's not another mailing list. Just
-have patience.
-
-=item Announce to clpa
-
-If you have a burning desire to tell the world about your release, post
-an announcement to the moderated C<comp.lang.perl.announce> newsgroup.
+Alternatively you can use the F<cpan-upload> script, part of the
+L<CPAN::Uploader> distribution on CPAN.
=item Fix bugs!
Simon Cozens, C<simon@cpan.org>
+Updated by Kirrily "Skud" Robert, C<skud@cpan.org>
+
=head1 SEE ALSO
L<perlmod>, L<perlmodlib>, L<perlmodinstall>, L<h2xs>, L<strict>,
-L<Carp>, L<Exporter>, L<perlpod>, L<Test>, L<ExtUtils::MakeMaker>,
-http://www.cpan.org/, Ken Williams' tutorial on building your own
-module at http://mathforum.org/~ken/perl_modules.html
+L<Carp>, L<Exporter>, L<perlpod>, L<Test::Simple>, L<Test::More>
+L<ExtUtils::MakeMaker>, L<Module::Build>, L<Module::Starter>
+L<http://www.cpan.org/>, Ken Williams' tutorial on building your own
+module at L<http://mathforum.org/~ken/perl_modules.html>
https://perl5.git.perl.org / perl5.git / blobdiff