Re: Hello World for module writers

I wanted to also give a step by step guide on creating a minimal Hello World module. There are many ways to do it. And everyone has their own process. When first learning, I like the fact that the approach I'm about to outline gets you started rapidly, but doesn't hide the implementation details that are good to learn. When you move up the ladder of abstraction to a higher-level set of tools, it will still be valuable to have learned what's going on at this lower level.

Install Module::Starter.
$ module-starter --module=Acme::HelloWorld --author='David Oswald' --email='davido@cpan.org' --eumm
This will create a shell of a module for you to work on.
$ cd Acme-HelloWorld/t

Now open and edit 00-load.t:

use Test::More tests => 3;
BEGIN {
    use_ok( 'Acme::HelloWorld', 'greet' ) || print "Bail out!\n";
}

diag( "Testing Acme::HelloWorld $Acme::HelloWorld::VERSION, Perl $], $
+^X" );
can_ok( 'Acme::HelloWorld', 'greet' );
is( greet(), 'Hello, world!', 'greet() greets the world' );
[download]

Now cd to Acme-HelloWorld/lib/Acme/, and open HelloWorld.pm to edit:

package Acme::HelloWorld;

use 5.006;
use strict;
use warnings;

use parent 'Exporter';

our $VERSION = '0.01';
our ( @EXPORT_OK ) = qw(greet);

sub greet {
    return "Hello, world!";
}

=head1 NAME

Acme::HelloWorld - Greet the world in style!

=head1 VERSION

Version 0.01

=head1 SYNOPSIS

This module provides a function that returns a greeting to the world.

    use Acme::HelloWorld 'greet';

    my $greeting = greet();

=head1 EXPORT

Nothing is exported by default.  C<greet> will be exported if specifie
+d in the export list.

=head1 SUBROUTINES/METHODS

=head2 greet

    my $greeting = greet();
    print "$greeting\n";

C<greet> takes no parameters, and returns the text, 'C<Hello World!>'.

=head1 AUTHOR

David Oswald, C<< <davido at cpan.org> >>

=head1 BUGS

Please report any bugs or feature requests to C<bug-acme-helloworld at
+ rt.cpan.org>, or through
the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=
+Acme-HelloWorld>.  I will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.

=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Acme::HelloWorld

You can also look for information at:

=over 4

=item * RT: CPAN's request tracker (report bugs here)

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Acme-HelloWorld>

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/Acme-HelloWorld>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/Acme-HelloWorld>

=item * Search CPAN

L<http://search.cpan.org/dist/Acme-HelloWorld/>

=back

=head1 ACKNOWLEDGEMENTS

I'd like to thank the world for listening when I shout I<Hello!>

=head1 LICENSE AND COPYRIGHT

Copyright 2012 David Oswald.

This program is free software; you can redistribute it and/or modify i
+t
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

=cut

1; # End of Acme::HelloWorld
[download]

Check the contents of Makefile.PL. We haven't added any non-core dependencies to our module, so there really are no mandatory changes to make.
Let's test:
```
perl Makefile.PL
make
make test
[download]
```
...or after 'make' you can prove -b
We should edit our Changes and README files. I won't bother pasting here. Make sure to include a date/time in the Changes, along with a correct version number. README should have a brief description, and simple installation instructions, along with some contact information and a license. The version created by module-starter is 90% of what you should have.

Now let's test and finalize the distribution.

perl Makefile.PL
make
make test
make distcheck    (This confirms that your MANIFEST is complete).
make disttest     (This will build the dist in ./Acme-HelloWorld-0.01/
+)
cp Acme-HelloWorld-0.01/META.json ./META.json
cp Acme-HelloWorld-0.10/META.yml  ./META.yml
rm -rf Acme-HelloWorld-0.01/
[download]

Adding the META files into our distribution is just a convenient way of providing information that is useful to the CPAN indexer, as well as to utilities such as cpanm.

Add META.yml and META.json entries into MANIFEST. Look over the contents of the META.* files. And skim the Meta CPAN spec, as well as ExtUtils::MakeMaker.
make && make test (One more time for good luck.)
make dist
Now that you have a tarball of your module, you can log into your PAUSE account and upload it. Once uploaded you may not see it on the CPAN mirrors for several hours.
A couple days later, check the smoke tests that are linked-to from your distribution's CPAN page. If there are any failures, investigate and fix.
When uploading a new version, always bump the version number (even if it's a minor change), and don't forget to update your Changes file.

Do also familiarize yourself with what the other tests in the t/ folder do. For more elaborate modules your test suite should grow much larger. The test files will run in ascii-betical order. When tests fail, sometimes it's helpful to run one test file individually: $ perl -Mblib t/00-load.t. In particular, I find that sometimes prove jumbles the order of output when the test suite spits out messages both to STDERR and STDOUT. By invoking a test directly in the Perl interpreter, that problem goes away, and it becomes easier to figure out what's going wrong.

Get comfortable with a version control system, and start checking your modules into repos.

Remember; before uploading to CPAN again, always bump the version number. Even if you made no other changes; you should never upload the same version number twice, and version numbers should always be greater than the last number used.

Other useful documents: perlmodstyle, Test::More, CPAN Testers Author Notes, and the following books: Intermediate Perl, Test Driven Development: A Developer's Notebook

Have fun!

Dave

Comment on Re: Hello World for module writers Select or Download Code