Acme-CreatingCPANModules

 view release on metacpan or  search on metacpan

META.yml  view on Meta::CPAN

# http://module-build.sourceforge.net/META-spec.html
#XXXXXXX This is a prototype!!!  It will change in the future!!! XXXXX#
name:         Acme-CreatingCPANModules
version:      0.01
version_from: lib/Acme/CreatingCPANModules.pm
installdirs:  site
requires:
    Test::More:                    0

distribution_type: module
generated_by: ExtUtils::MakeMaker version 6.17

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

    my $bar = $foo->get();

=head1 THE TALK

[give or take a word]

[the slides that accompanied this talk are available through
http://jose-castro.org]

[we start at the first slide and you'll see a slide tag each time the
slide is supposed to change (just press enter for that)]

Hello!

First of all... [slide]

Good :-)

My name is José and I'm here to take you along the creation of a CPAN
module.

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

You'll also notice the .pm file. That's your module!

Everybody knows what a README is, but we'll also get to that.

The Makefile.PL is what's going to be used to install your module, and
MANIFEST contains the list of files the distribution includes... don't
try to think to hard about all this, we'll get to all this in a
moment.

And then there's the Changes file, where you're supposed to write down
the changes you made to your module each new version.

Let's look at the files in detail.

[slide] Here's a Changes file.

Note that the order of the changes is chronologically inversed. Why?
Because the purporse of a changes file is (among others) to let the
user know what you changed from the last version, so that he can
decide if he wants to install your module.

Hence, and since browsers and editors usually open files in their
beginning, it's only reasonable that you put the most recent changes
on the top of the file.

As for what you put in here, it's kind of up to you, but you don't
need to be too technical. If you added some tests, just say "added
some tests". You don't really need to specify which ones and the
purpose of each of them.

[slide] Next up we have the MANIFEST. This is the file that lists
everything that goes into your distribution.

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

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

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

and some documentation for these methods]

Now, let's run the tests again. [`make test`]

OK, so we haven't broken anything yet, good :-)

Now, let's add some more tests [`cp t/00-load.t t/01-basic.t`].

As you can see, [`make test`] running the tests again runs this new file.

Now let's change a few things in this new file of ours. [`vim
t/01-basic.t`, remove the last line and add instead:

  my $object = Acme::CreatingCPANModules->new();

  isa_ok( $object, 'Acme::CreatingCPANModules' );
]

This is going to ensure that creating a new Acme::CreatingCPANModules
object actually creates one.

Now, what do you think will happen if I run the tests again?

[`make test`] See? If complains that you ran one more test than
expected. Have a look to the test file again.

See right over there? You're saying that you're going to run one test
[point to third line], but you actually run two [point to use_ok and
to isa_ok].

What you'd have to do is to change that 1 to a 2, but I'll tell you a
little secret of mine: just use C<Test::More> with 'no_plan' [change
the third line in the test file to:

  use Test::More 'no_plan';#tests => 1;
].

OK, so let's add some more tests.

[add, at the bottom of the file:

  $object->set( 5 );

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

See? Just like that!

What do we have to now? We have to update the MANIFEST and the Changes
file. [`vim MANIFEST` and remove the boilerplate.t line and add
t/01-basic.t`, `vim Changes`, in Changes, add the date/time]

Now let's create our distribution. How do you do that? With `make
dist` [`perl Makefile.PL`, `make`, `make test`, `make dist`, `ls -al`]

Now, you have to create your Makefile again, because you change the
files. When in doubt, you can always run these four steps.

As you can see, we now have a distribution, ready to be uploaded.

How do you upload something to CPAN? [cut to screenshots of
pause.perl.org]

[first picture]

This is the PAUSE. The Perl Authors Upload Server.

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

mail to it).

The slides for this talk are inside a module called
C<Acme::CreatingCPANModules>, available on CPAN. You can get to this
module from my homepage, http://jose-castro.org/

It's really simple because it's my name and it's been in every slide
so far! :-) Bottom right corner, Jose Castro, can't miss it! :-)

Somewhere on that page you'll be able to find these slides. I think
currently their at the top right corner. That might change in the
future, and they may go under the "Talks" section, but they'll be
there and they'll be easy to find.

So thank you very much for your time, get C<Module::Starter> on your
machine and start a module today.

Don't be afraid of uploading it to CPAN. People will help you when you
do something wrong :-)

[slide]

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

=head1 AUTHOR

Jose Castro, C<< <cog at cpan.org> >>

=head1 BUGS

Please report any bugs or feature requests to
C<bug-acme-creatingcpanmodules at rt.cpan.org>, or through the web interface at
L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Acme-CreatingCPANModules>.
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::CreatingCPANModules

You can also look for information at:

=over 4

slides/slide5c.html  view on Meta::CPAN

<div class="top_spacer"></div>
<img name="img" id="img" width="350" src="images/cpan.jpg" align=right>
<h2>Using Images</h2>
<ul>
<li>Hey Look. A picture!</li>
</ul>
<p>

</p>
<ul>
<li>Woah, it changed!</li>
</ul>
<p>

</p>
<ul>
<li>Images are cached locally</li>
</ul>

</div>
<!-- BEGIN bottom -->