File Coverage

blib/lib/Acme/CreatingCPANModules.pm
Criterion Covered Total %
statement 16 16 100.0
branch 1 2 50.0
condition n/a
subroutine 5 5 100.0
pod 3 3 100.0
total 25 26 96.1


line stmt bran cond sub pod time code
1             package Acme::CreatingCPANModules;
2              
3 2     2   47451 use warnings;
  2         5  
  2         70  
4 2     2   14 use strict;
  2         5  
  2         569  
5              
6             =head1 NAME
7              
8             Acme::CreatingCPANModules - Created during a talk in London
9              
10             =head1 VERSION
11              
12             Version 0.01
13              
14             =cut
15              
16             our $VERSION = '0.01';
17              
18             =head1 SYNOPSIS
19              
20             This module doesn't actually *do* anything...
21              
22             It does have a new constructor, and a set and a get method, just so
23             you can do some tests.
24              
25             use Acme::CreatingCPANModules;
26              
27             my $foo = Acme::CreatingCPANModules->new();
28              
29             $foo->set( 3 );
30              
31             my $bar = $foo->get();
32              
33             =head1 THE TALK
34              
35             [give or take a word]
36              
37             [the slides that accompanied this talk are available through
38             http://jose-castro.org]
39              
40             [we start at the first slide and you'll see a slide tag each time the
41             slide is supposed to change (just press enter for that)]
42              
43             Hello!
44              
45             First of all... [slide]
46              
47             Good :-)
48              
49             My name is José and I'm here to take you along the creation of a CPAN
50             module.
51              
52             The first thing I'l like to tell you is this: do not bother taking
53             notes!
54              
55             These slides are already online, and so is my speech (give or take a
56             word), and by the end of this talk I'll be giving you the link you can
57             use to get them.
58              
59             Also, don't bother noting down links... apart from the last one, of
60             course, because with that one you'll get to the slides and you'll be
61             able to get the other links from there.
62              
63             [slide] And now we're going to create a CPAN module.
64              
65             [slide] We assume you're here either because [slide] you want to be a
66             CPAN contributor, [slide] you want to be a better CPAN contributor, or
67             [slide] you have absolutely no idea what a lexical attribute is and
68             couldn't care less [at the same time, Abigail was giving his talk on
69             Lexical Attributes in the advanced room].
70              
71             [slide] So let's get started, with [slide] C.
72              
73             Now, you should know that there are other ways to create a CPAN
74             module, and no way is the true way. They all have some advantages and
75             some disadvantages. Anyway, for the purpose of this talk, we'll be
76             using C, and if there's time by the end I'll talk a
77             bit about the other alternatives.
78              
79             So let's get started!
80              
81             Just install C (if you don't know how to do that you
82             can talk to me later on) and you'll be provided the C
83             command.
84              
85             Type it and you'll see [slide] WHOAA!!!
86              
87             [slide] OK, relax :-)
88              
89             C has a bunch of options you can use, but the most
90             important three ones are these: --module for the module name, --author
91             for the author's name (you) and --email for the author's email address
92             (it's always good to allow users to contact you).
93              
94             [slide] So let's exemplify this (we'll do this in the slides and then
95             we'll move on to a terminal and try all this again).
96              
97             [slide] I'm going to create the module C,
98             [slide] with the author "Jose Castro" (that's me, in case you didn't
99             notice... my name is also in the bottom right corner of the slides...
100             :-) ) [slide] and my email address: cog at cpan dot org.
101              
102             [slide] There. Module created!
103              
104             No, it doesn't do anything yet, but it already exists!
105              
106             [slide] So let's see what happened and exactly what was created.
107              
108             With the `tree` command [If your system doesn't provide the `tree`
109             command tool you can try installing C]!
110              
111             [slide] OK, then...
112              
113             OK, let's go through this step by step...
114              
115             Here on the bottom we have a t/ directory, which is the directory
116             where you put your test files (it's a convention). Inside it are a few
117             .t files (that's also a convention for test files). We'll get to these
118             in a while.
119              
120             You'll also notice the .pm file. That's your module!
121              
122             Everybody knows what a README is, but we'll also get to that.
123              
124             The Makefile.PL is what's going to be used to install your module, and
125             MANIFEST contains the list of files the distribution includes... don't
126             try to think to hard about all this, we'll get to all this in a
127             moment.
128              
129             And then there's the Changes file, where you're supposed to write down
130             the changes you made to your module each new version.
131              
132             Let's look at the files in detail.
133              
134             [slide] Here's a Changes file.
135              
136             Note that the order of the changes is chronologically inversed. Why?
137             Because the purporse of a changes file is (among others) to let the
138             user know what you changed from the last version, so that he can
139             decide if he wants to install your module.
140              
141             Hence, and since browsers and editors usually open files in their
142             beginning, it's only reasonable that you put the most recent changes
143             on the top of the file.
144              
145             As for what you put in here, it's kind of up to you, but you don't
146             need to be too technical. If you added some tests, just say "added
147             some tests". You don't really need to specify which ones and the
148             purpose of each of them.
149              
150             [slide] Next up we have the MANIFEST. This is the file that lists
151             everything that goes into your distribution.
152              
153             Why? Because this way you're able to put more stuff in the directory
154             and not have the final step of creating the distribution include those
155             files.
156              
157             If you're thinking "why would I put things in that directory if they
158             weren't part of the distribution", think, for instance, in a test file
159             that only runs in your machine.
160              
161             One of my modules has tests with two files that take almost 200M each.
162             I don't think the users wouldn't want to download a 400M distribution
163             when they can do with a 20K one.
164              
165             Hence, those files of mine are in that directory but not listed in the
166             MANIFEST.
167              
168             The drawback on this is that whenever you add a file to the
169             distribution you have to remember to update the MANIFEST.
170              
171             [slide] Next up, we have Makefile.PL
172              
173             Now, you really don't need to understand what's in here, but it's
174             still quite self-explanatory.
175              
176             There's the name of the of the distribution, the author, etc. Do note
177             the C parameter. If your distribution requires another
178             module to be installed, that's where you defined that. Just add the
179             name of the module to that hash and put the minimum version number of
180             the module that you require.
181              
182             [slide] Next we have the README. What you put in the README is, once
183             again, up to you. I always put the same documentation from the main
184             module, some people just put a template README in all their
185             distributions.
186              
187             Whatever you do, don't forget to update the README at least once, as
188             it's the file many users look at and the default documentation can be
189             kind of... embarassing ;-)
190              
191             [slide] And now we finally have our module!
192              
193             The module is comprised of two things: code and documentation.
194              
195             Both are equally important.
196              
197             I can't stress how much.
198              
199             Whether you put your documentation at the beginning or at the end of
200             the file, or perhaps entwined with the code, is, again, up to you.
201              
202             We're not staying for a long time at this slide because we'll have the
203             time to do so in the demo, right after this.
204              
205             [slide] And now we're at the first test file.
206              
207             Currently, through C, it checks to see if the module loads
208             correctly. It also diagnoses what it's doing.
209              
210             [slide] Then we have another test file, which was recently introduced,
211             to check if files like README and Changes have content written by you
212             or are just the default templates.
213              
214             [slide] The next one is checks if you're documenting all your public
215             functions. It assumes that if you have a private function (that is, a
216             function that's not meant for the public but rather to be used by your
217             other functions) you will name it something commencing with an
218             underscore.
219              
220             This means that you need a section with the name of each function that
221             doesn't begin with an underscore.
222              
223             [slide] And this one over here ensures that your POD is valid.
224              
225             [slide] So let's go through it one more time: Changes for the list
226             of changes, MANIFEST with the list of files, Makefile.PL to be used
227             for installation, README, your module, and a bunch of tests.
228              
229             [slide] Very well, then. Time for the live demo!
230              
231             [I change to the next workspace and we're set] You know what they say
232             about live demos? They say "Don't!" O:-)
233              
234             OK, then, first we'll create our module. [I type `module-starter
235             --module=Acme::CreatingCPANModules --author='Jose Castro'
236             --email=cog@cpan.org`]
237              
238             There, done.
239              
240             Now, the first I'm gonna do is get rid of C. Well, not
241             really getting rid of it, I'll just put it aside for the time being
242             and I'll explain you later why I'm doing it. [`cd
243             Acme-CreatingCPANModules` and `mv t/boilerplate .`]
244              
245             Now we're set.
246              
247             Suppose we were installing this module.
248              
249             The first thing to do it `perl Makefile.PL` [`perl Makefile.PL` and ls
250             -al]. As you can see, this has created C.
251              
252             This now allows us to do things like this [`make`]. And now we can
253             test our distribution [`make test`].
254              
255             As you can see, all our tests have passed... but that's simply because
256             we still don't have anything interesting in our module...
257              
258             Let's add some code. [I add the code for new(), set() and get(), as
259             follows:
260              
261             sub new {
262             my $self = shift;
263             my $foo = shift;
264             bless \$foo, $self;
265             }
266              
267             sub set {
268             my $self = shift;
269             my $newfoo = shift;
270             defined $newfoo or return undef;
271             $$self = $newfoo;
272             return $self->get();
273             }
274              
275             sub get {
276             my $self = shift;
277             return $$self;
278             }
279              
280             and some documentation for these methods]
281              
282             Now, let's run the tests again. [`make test`]
283              
284             OK, so we haven't broken anything yet, good :-)
285              
286             Now, let's add some more tests [`cp t/00-load.t t/01-basic.t`].
287              
288             As you can see, [`make test`] running the tests again runs this new file.
289              
290             Now let's change a few things in this new file of ours. [`vim
291             t/01-basic.t`, remove the last line and add instead:
292              
293             my $object = Acme::CreatingCPANModules->new();
294              
295             isa_ok( $object, 'Acme::CreatingCPANModules' );
296             ]
297              
298             This is going to ensure that creating a new Acme::CreatingCPANModules
299             object actually creates one.
300              
301             Now, what do you think will happen if I run the tests again?
302              
303             [`make test`] See? If complains that you ran one more test than
304             expected. Have a look to the test file again.
305              
306             See right over there? You're saying that you're going to run one test
307             [point to third line], but you actually run two [point to use_ok and
308             to isa_ok].
309              
310             What you'd have to do is to change that 1 to a 2, but I'll tell you a
311             little secret of mine: just use C with 'no_plan' [change
312             the third line in the test file to:
313              
314             use Test::More 'no_plan';#tests => 1;
315             ].
316              
317             OK, so let's add some more tests.
318              
319             [add, at the bottom of the file:
320              
321             $object->set( 5 );
322              
323             is( $object->get(), 5 );
324             ]
325              
326             Now let's run the tests [`make test`].
327              
328             See? Just like that!
329              
330             What do we have to now? We have to update the MANIFEST and the Changes
331             file. [`vim MANIFEST` and remove the boilerplate.t line and add
332             t/01-basic.t`, `vim Changes`, in Changes, add the date/time]
333              
334             Now let's create our distribution. How do you do that? With `make
335             dist` [`perl Makefile.PL`, `make`, `make test`, `make dist`, `ls -al`]
336              
337             Now, you have to create your Makefile again, because you change the
338             files. When in doubt, you can always run these four steps.
339              
340             As you can see, we now have a distribution, ready to be uploaded.
341              
342             How do you upload something to CPAN? [cut to screenshots of
343             pause.perl.org]
344              
345             [first picture]
346              
347             This is the PAUSE. The Perl Authors Upload Server.
348              
349             This is what we use to upload distributions.
350              
351             First, you need an account. You can request one here [point to
352             "Request PAUSE account"].
353              
354             [second picture]
355              
356             To be given a PAUSE account you have to fill in your name, email
357             address, the desired ID and one or two more things. You also have to
358             explain what you're planning to contribute.
359              
360             This is not so someone judges whether your contribution is worth it or
361             not. It's just so you can tell the real people from the trolls.
362              
363             You have a few days (because the PAUSE administrators aren't many and
364             they might be busy) and eventually you'll get an answer. There's a
365             slight chance (just slight) that your request doesn't get looked at.
366             If you don't get an answer, try again about a week later, but this is
367             really not common, I'm just warning you :-)
368              
369             [third picture]
370              
371             Once you're in, you get a lot to choose from.
372              
373             [fourth picture]
374              
375             Uploading a distribution, for instance, is really simple. Just press
376             the button [point to "Upload a file to CPAN"],
377              
378             [fifth picture]
379              
380             Select your tgz file and press the button [point to "Upload this file
381             from my disk"]
382              
383             This pretty much sums up the important things you need to know, but,
384             of course, there's a lot more [back to slides].
385              
386             [slide]
387              
388             There's a lot of basic and advanced stuff we didn't cover in this
389             talk.
390              
391             [slide]
392              
393             What next?
394              
395             I'd like to point you to another article I wrote a while ago, which is
396             available on Perlmonks.
397              
398             There's also a very good book on the subject, which covers a lot more
399             than what we talked about here. The book is "Writing Perl Modules for
400             CPAN", by Sam Tregar, and it's free, as in "you can download it".
401              
402             You can subscribe the C mailing list if you
403             need more help (you can also contact me).
404              
405             If you need to contact a PAUSE admin, send an email to
406             C (you can't subscribe that list, you can only send
407             mail to it).
408              
409             The slides for this talk are inside a module called
410             C, available on CPAN. You can get to this
411             module from my homepage, http://jose-castro.org/
412              
413             It's really simple because it's my name and it's been in every slide
414             so far! :-) Bottom right corner, Jose Castro, can't miss it! :-)
415              
416             Somewhere on that page you'll be able to find these slides. I think
417             currently their at the top right corner. That might change in the
418             future, and they may go under the "Talks" section, but they'll be
419             there and they'll be easy to find.
420              
421             So thank you very much for your time, get C on your
422             machine and start a module today.
423              
424             Don't be afraid of uploading it to CPAN. People will help you when you
425             do something wrong :-)
426              
427             [slide]
428              
429             Thank you.
430              
431             Any questions? [email me at cog@cpan.org if you have any :-) ]
432              
433             I'll leave the previous slide with the links while I answer questions.
434             [and back to the previous slide]
435              
436             =head1 EXPORT
437              
438             This module is OO, so it doesn't export anything...
439              
440             =head1 FUNCTIONS
441              
442             =head2 new
443              
444             Creates a new Acme::CreatingCPANModules object.
445              
446             =cut
447              
448             sub new {
449 1     1 1 14 my $self = shift;
450 1         2 my $foo = shift;
451 1         6 bless \$foo, $self;
452             }
453              
454             =head2 set
455              
456             Sets the new value of the object.
457              
458             =cut
459              
460             sub set {
461 1     1 1 778 my $self = shift;
462 1         3 my $newfoo = shift;
463 1 50       5 defined $newfoo or return undef;
464 1         5 $$self = $newfoo;
465 1         7 return $self->get();
466             }
467              
468             =head2 get
469              
470             Gets the current value of the object.
471              
472             =cut
473              
474             sub get {
475 2     2 1 5 my $self = shift;
476 2         9 return $$self;
477             }
478              
479             =head1 AUTHOR
480              
481             Jose Castro, C<< >>
482              
483             =head1 BUGS
484              
485             Please report any bugs or feature requests to
486             C, or through the web interface at
487             L.
488             I will be notified, and then you'll automatically be notified of progress on
489             your bug as I make changes.
490              
491             =head1 SUPPORT
492              
493             You can find documentation for this module with the perldoc command.
494              
495             perldoc Acme::CreatingCPANModules
496              
497             You can also look for information at:
498              
499             =over 4
500              
501             =item * AnnoCPAN: Annotated CPAN documentation
502              
503             L
504              
505             =item * CPAN Ratings
506              
507             L
508              
509             =item * RT: CPAN's request tracker
510              
511             L
512              
513             =item * Search CPAN
514              
515             L
516              
517             =back
518              
519             =head1 SEE ALSO
520              
521             http://jose-castro.org for the slides that accompany this talk.
522              
523             =head1 ACKNOWLEDGEMENTS
524              
525             The audience at the London Perl Workshop 2005.
526              
527             =head1 COPYRIGHT & LICENSE
528              
529             Copyright 2005 Jose Castro, all rights reserved.
530              
531             This program is free software; you can redistribute it and/or modify it
532             under the same terms as Perl itself.
533              
534             =cut
535              
536             1; # End of Acme::CreatingCPANModules