view release on metacpan or  search on metacpan

lib/Acme/CreatingCPANModules.pm  view on Meta::CPAN

and not have the final step of creating the distribution include those
files.

If you're thinking "why would I put things in that directory if they
weren't part of the distribution", think, for instance, in a test file
that only runs in your machine.

One of my modules has tests with two files that take almost 200M each.
I don't think the users wouldn't want to download a 400M distribution
when they can do with a 20K one.

Hence, those files of mine are in that directory but not listed in the
MANIFEST.

The drawback on this is that whenever you add a file to the
distribution you have to remember to update the MANIFEST.

[slide] Next up, we have Makefile.PL

Now, you really don't need to understand what's in here, but it's
still quite self-explanatory.

There's the name of the of the distribution, the author, etc. Do note
the C<PREREQ_PM> parameter. If your distribution requires another
module to be installed, that's where you defined that. Just add the
name of the module to that hash and put the minimum version number of
the module that you require.

[slide] Next we have the README. What you put in the README is, once
again, up to you. I always put the same documentation from the main
module, some people just put a template README in all their
distributions.

Whatever you do, don't forget to update the README at least once, as
it's the file many users look at and the default documentation can be
kind of... embarassing ;-)

[slide] And now we finally have our module!

The module is comprised of two things: code and documentation.

Both are equally important.

I can't stress how much.

Whether you put your documentation at the beginning or at the end of
the file, or perhaps entwined with the code, is, again, up to you.

We're not staying for a long time at this slide because we'll have the
time to do so in the demo, right after this.

[slide] And now we're at the first test file.

Currently, through C<Test::More>, it checks to see if the module loads
correctly. It also diagnoses what it's doing.

[slide] Then we have another test file, which was recently introduced,
to check if files like README and Changes have content written by you
or are just the default templates.

[slide] The next one is checks if you're documenting all your public
functions. It assumes that if you have a private function (that is, a
function that's not meant for the public but rather to be used by your
other functions) you will name it something commencing with an
underscore.

This means that you need a section with the name of each function that
doesn't begin with an underscore.

[slide] And this one over here ensures that your POD is valid.

[slide] So let's go through it one more time: Changes for the list
of changes, MANIFEST with the list of files, Makefile.PL to be used
for installation, README, your module, and a bunch of tests.

[slide] Very well, then. Time for the live demo!

[I change to the next workspace and we're set] You know what they say
about live demos? They say "Don't!" O:-)

OK, then, first we'll create our module. [I type `module-starter
--module=Acme::CreatingCPANModules --author='Jose Castro'
--email=cog@cpan.org`]

There, done.

Now, the first I'm gonna do is get rid of C<boilerplate.t>. Well, not
really getting rid of it, I'll just put it aside for the time being
and I'll explain you later why I'm doing it. [`cd
Acme-CreatingCPANModules` and `mv t/boilerplate .`]

Now we're set.

Suppose we were installing this module.

The first thing to do it `perl Makefile.PL` [`perl Makefile.PL` and ls
-al]. As you can see, this has created C<Makefile>.

This now allows us to do things like this [`make`]. And now we can
test our distribution [`make test`].

As you can see, all our tests have passed... but that's simply because
we still don't have anything interesting in our module...

Let's add some code. [I add the code for new(), set() and get(), as
follows:

  sub new {
    my $self = shift;
    my $foo = shift;
    bless \$foo, $self;
  }

  sub set {
    my $self = shift;
    my $newfoo = shift;
    defined $newfoo or return undef;
    $$self = $newfoo;
    return $self->get();
  }

  sub get {
    my $self = shift;