This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
gcc -O3 and Storable in Linux do not like each other.
[perl5.git] / pod / perlmodlib.PL
CommitLineData
2e1d04bc
JH
1#!../miniperl
2
1fa7ca25
JH
3$ENV{LC_ALL} = 'C';
4
2e1d04bc 5open (OUT, ">perlmodlib.tmp") or die $!;
1fa7ca25 6my (@pragma, @mod, @MANIFEST);
4d671226 7
2e1d04bc 8open (MANIFEST, "../MANIFEST") or die $!;
4d671226 9@MANIFEST = grep !m</(?:t|demo)/>, <MANIFEST>;
7ef5744c
RGS
10push @MANIFEST, 'lib/Config.pod', 'lib/Errno.pm', 'lib/lib.pm',
11 'lib/DynaLoader.pm', 'lib/XSLoader.pm';
2e1d04bc 12
4d671226 13for (@MANIFEST) {
2e1d04bc
JH
14 my $filename;
15 next unless s|^lib/|| or m|^ext/|;
7ef5744c 16 my ($origfilename) = ($filename) = m|^(\S+)|;
2e1d04bc 17 $filename =~ s|^[^/]+/|| if $filename =~ s|^ext/||;
1fa7ca25 18 next unless $filename =~ m!\.p(m|od)$!;
7ef5744c
RGS
19 unless (open (MOD, "../lib/$filename")) {
20 unless (open (MOD, "../$origfilename")) {
21 warn "Couldn't open ../$origfilename: $!";
22 next;
23 }
24 $filename = $origfilename;
25 }
4e860d0a 26
1fa7ca25 27
2e1d04bc
JH
28 my ($name, $thing);
29 my $foundit=0;
4e860d0a
JH
30 {
31 local $/="";
32 while (<MOD>) {
33 next unless /^=head1 NAME/;
34 $foundit++;
35 last;
36 }
2e1d04bc 37 }
4e860d0a 38 unless ($foundit) {
1fa7ca25 39 warn "$filename missing =head1 NAME (okay if there is respective .pod)\n";
4e860d0a 40 next;
2e1d04bc 41 }
2e1d04bc
JH
42 my $title = <MOD>;
43 chomp($title);
44 close MOD;
45
46 my $perlname = $filename;
7ef5744c 47 $perlname =~ s!^.*\b(ext|lib)/!!;
4e860d0a 48 $perlname =~ s!\.p(m|od)$!!;
7ef5744c 49 $perlname =~ s!\b(\w+)/\1\b!$1!;
4e860d0a
JH
50 $perlname =~ s!/!::!g;
51
52 ($name, $thing) = split / --? /, $title, 2;
53
54 unless ($name and $thing) {
55 warn "$filename missing name\n" unless $name;
56 warn "$filename missing thing\n" unless $thing;
57 next;
58 }
2e1d04bc 59
1fa7ca25 60
4e860d0a
JH
61 $thing =~ s/^perl pragma to //i;
62 $thing = ucfirst($thing);
2e1d04bc
JH
63 $title = "=item $perlname\n\n$thing\n\n";
64
1fa7ca25 65 if ($filename =~ /[A-Z]/) {
2e1d04bc
JH
66 push @mod, $title;
67 } else {
68 push @pragma, $title;
69 }
70}
71
72print OUT <<'EOF';
c165c82a
JH
73=for maintainers
74Generated by perlmodlib.PL -- DO NOT EDIT!
843dbe26 75
2e1d04bc
JH
76=head1 NAME
77
78perlmodlib - constructing new Perl modules and finding existing ones
79
2e1d04bc
JH
80=head1 THE PERL MODULE LIBRARY
81
7ef5744c 82Many modules are included in the Perl distribution. These are described
2e1d04bc 83below, and all end in F<.pm>. You may discover compiled library
7ef5744c 84files (usually ending in F<.so>) or small pieces of modules to be
2e1d04bc
JH
85autoloaded (ending in F<.al>); these were automatically generated
86by the installation process. You may also discover files in the
87library directory that end in either F<.pl> or F<.ph>. These are
88old libraries supplied so that old programs that use them still
89run. The F<.pl> files will all eventually be converted into standard
90modules, and the F<.ph> files made by B<h2ph> will probably end up
91as extension modules made by B<h2xs>. (Some F<.ph> values may
92already be available through the POSIX, Errno, or Fcntl modules.)
93The B<pl2pm> file in the distribution may help in your conversion,
94but it's just a mechanical process and therefore far from bulletproof.
95
96=head2 Pragmatic Modules
97
98They work somewhat like compiler directives (pragmata) in that they
99tend to affect the compilation of your program, and thus will usually
100work well only when used within a C<use>, or C<no>. Most of these
101are lexically scoped, so an inner BLOCK may countermand them
102by saying:
103
104 no integer;
105 no strict 'refs';
106 no warnings;
107
108which lasts until the end of that BLOCK.
109
110Some pragmas are lexically scoped--typically those that affect the
111C<$^H> hints variable. Others affect the current package instead,
112like C<use vars> and C<use subs>, which allow you to predeclare a
113variables or subroutines within a particular I<file> rather than
114just a block. Such declarations are effective for the entire file
115for which they were declared. You cannot rescind them with C<no
116vars> or C<no subs>.
117
118The following pragmas are defined (and have their own documentation).
119
120=over 12
121
122EOF
123
124print OUT $_ for (sort @pragma);
125
126print OUT <<EOF;
127=back
128
129=head2 Standard Modules
130
131Standard, bundled modules are all expected to behave in a well-defined
132manner with respect to namespace pollution because they use the
133Exporter module. See their own documentation for details.
134
7ef5744c
RGS
135It's possible that not all modules listed below are installed on your
136system. For example, the GDBM_File module will not be installed if you
137don't have the gdbm library.
138
2e1d04bc
JH
139=over 12
140
141EOF
142
143print OUT $_ for (sort @mod);
144
145print OUT <<'EOF';
146=back
147
148To find out I<all> modules installed on your system, including
149those without documentation or outside the standard release,
a4373870
CW
150just use the following command (under the default win32 shell,
151double quotes should be used instead of single quotes).
2e1d04bc 152
a4373870
CW
153 % perl -MFile::Find=find -MFile::Spec::Functions -Tlwe \
154 'find { wanted => sub { print canonpath $_ if /\.pm\z/ },
155 no_chdir => 1 }, @INC'
2e1d04bc 156
8518420c 157(The -T is here to prevent '.' from being listed in @INC.)
2e1d04bc
JH
158They should all have their own documentation installed and accessible
159via your system man(1) command. If you do not have a B<find>
160program, you can use the Perl B<find2perl> program instead, which
161generates Perl code as output you can run through perl. If you
162have a B<man> program but it doesn't find your modules, you'll have
163to fix your manpath. See L<perl> for details. If you have no
164system B<man> command, you might try the B<perldoc> program.
165
8518420c
RGS
166Note also that the command C<perldoc perllocal> gives you a (possibly
167incomplete) list of the modules that have been further installed on
168your system. (The perllocal.pod file is updated by the standard MakeMaker
169install process.)
170
2e1d04bc
JH
171=head2 Extension Modules
172
173Extension modules are written in C (or a mix of Perl and C). They
174are usually dynamically loaded into Perl if and when you need them,
da75cd15 175but may also be linked in statically. Supported extension modules
2e1d04bc
JH
176include Socket, Fcntl, and POSIX.
177
178Many popular C extension modules do not come bundled (at least, not
179completely) due to their sizes, volatility, or simply lack of time
180for adequate testing and configuration across the multitude of
181platforms on which Perl was beta-tested. You are encouraged to
182look for them on CPAN (described below), or using web search engines
7ef5744c 183like Alta Vista or Google.
2e1d04bc
JH
184
185=head1 CPAN
186
187CPAN stands for Comprehensive Perl Archive Network; it's a globally
188replicated trove of Perl materials, including documentation, style
189guides, tricks and traps, alternate ports to non-Unix systems and
190occasional binary distributions for these. Search engines for
1577cd80 191CPAN can be found at http://www.cpan.org/
2e1d04bc
JH
192
193Most importantly, CPAN includes around a thousand unbundled modules,
194some of which require a C compiler to build. Major categories of
195modules are:
196
197=over
198
199=item *
ac634a9a 200
2e1d04bc
JH
201Language Extensions and Documentation Tools
202
203=item *
ac634a9a 204
2e1d04bc
JH
205Development Support
206
207=item *
ac634a9a 208
2e1d04bc
JH
209Operating System Interfaces
210
211=item *
ac634a9a 212
2e1d04bc
JH
213Networking, Device Control (modems) and InterProcess Communication
214
215=item *
ac634a9a 216
2e1d04bc
JH
217Data Types and Data Type Utilities
218
219=item *
ac634a9a 220
2e1d04bc
JH
221Database Interfaces
222
223=item *
ac634a9a 224
2e1d04bc
JH
225User Interfaces
226
227=item *
ac634a9a 228
2e1d04bc
JH
229Interfaces to / Emulations of Other Programming Languages
230
231=item *
ac634a9a 232
2e1d04bc
JH
233File Names, File Systems and File Locking (see also File Handles)
234
235=item *
ac634a9a 236
2e1d04bc
JH
237String Processing, Language Text Processing, Parsing, and Searching
238
239=item *
ac634a9a 240
2e1d04bc
JH
241Option, Argument, Parameter, and Configuration File Processing
242
243=item *
ac634a9a 244
2e1d04bc
JH
245Internationalization and Locale
246
247=item *
ac634a9a 248
2e1d04bc
JH
249Authentication, Security, and Encryption
250
251=item *
ac634a9a 252
2e1d04bc
JH
253World Wide Web, HTML, HTTP, CGI, MIME
254
255=item *
ac634a9a 256
2e1d04bc
JH
257Server and Daemon Utilities
258
259=item *
ac634a9a 260
2e1d04bc
JH
261Archiving and Compression
262
263=item *
ac634a9a 264
2e1d04bc
JH
265Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
266
267=item *
ac634a9a 268
2e1d04bc
JH
269Mail and Usenet News
270
271=item *
ac634a9a 272
2e1d04bc
JH
273Control Flow Utilities (callbacks and exceptions etc)
274
275=item *
ac634a9a 276
2e1d04bc
JH
277File Handle and Input/Output Stream Utilities
278
279=item *
ac634a9a 280
2e1d04bc
JH
281Miscellaneous Modules
282
283=back
284
5df44211
JH
285The list of the registered CPAN sites as of this writing follows.
286Please note that the sorting order is alphabetical on fields:
287
288Continent
289 |
290 |-->Country
291 |
292 |-->[state/province]
293 |
294 |-->ftp
295 |
296 |-->[http]
297
298and thus the North American servers happen to be listed between the
299European and the South American sites.
300
301You should try to choose one close to you.
2e1d04bc 302
4e860d0a
JH
303=head2 Africa
304
305=over 4
306
5df44211 307=item South Africa
4e860d0a 308
5c5c2539
JH
309 http://ftp.rucus.ru.ac.za/pub/perl/CPAN/
310 ftp://ftp.rucus.ru.ac.za/pub/perl/CPAN/
5df44211 311 ftp://ftp.is.co.za/programming/perl/CPAN/
5df44211
JH
312 ftp://ftp.saix.net/pub/CPAN/
313 ftp://ftp.sun.ac.za/CPAN/CPAN/
4e860d0a
JH
314
315=back
316
317=head2 Asia
318
319=over 4
320
5df44211 321=item China
4e860d0a 322
5c5c2539 323 http://cpan.linuxforum.net/
5df44211
JH
324 http://cpan.shellhung.org/
325 ftp://ftp.shellhung.org/pub/CPAN
5c5c2539 326 ftp://mirrors.hknet.com/CPAN
c165c82a 327
5df44211 328=item Indonesia
c165c82a 329
5c5c2539 330 http://mirrors.tf.itb.ac.id/cpan/
5df44211
JH
331 http://cpan.cbn.net.id/
332 ftp://ftp.cbn.net.id/mirror/CPAN
c165c82a 333
5df44211 334=item Israel
c165c82a 335
5df44211
JH
336 ftp://ftp.iglu.org.il/pub/CPAN/
337 http://cpan.lerner.co.il/
338 http://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
339 ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
c165c82a 340
5df44211 341=item Japan
c165c82a 342
5df44211
JH
343 ftp://ftp.u-aizu.ac.jp/pub/CPAN
344 ftp://ftp.kddlabs.co.jp/CPAN/
345 http://mirror.nucba.ac.jp/mirror/Perl/
346 ftp://mirror.nucba.ac.jp/mirror/Perl/
5df44211
JH
347 ftp://ftp.ayamura.org/pub/CPAN/
348 ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
349 ftp://ftp.dti.ad.jp/pub/lang/CPAN/
350 ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
c165c82a 351
5c5c2539 352=item Malaysia
c165c82a 353
5c5c2539
JH
354 http://cpan.MyBSD.org.my
355 http://mirror.leafbug.org/pub/CPAN
356 http://ossig.mncc.com.my/mirror/pub/CPAN
4e860d0a 357
5df44211 358=item Russian Federation
4e860d0a 359
5df44211
JH
360 http://cpan.tomsk.ru
361 ftp://cpan.tomsk.ru/pub/CPAN
4e860d0a 362
5df44211 363=item Saudi Arabia
4e860d0a 364
5df44211 365 ftp://ftp.isu.net.sa/pub/CPAN/
4e860d0a 366
5df44211 367=item Singapore
4e860d0a 368
5c5c2539
JH
369 http://CPAN.en.com.sg/
370 ftp://cpan.en.com.sg/
5df44211
JH
371 http://mirror.averse.net/pub/CPAN
372 ftp://mirror.averse.net/pub/CPAN
5c5c2539
JH
373 http://cpan.oss.eznetsols.org
374 ftp://ftp.oss.eznetsols.org/cpan
4e860d0a 375
5df44211 376=item South Korea
4e860d0a 377
5df44211
JH
378 http://CPAN.bora.net/
379 ftp://ftp.bora.net/pub/CPAN/
5c5c2539
JH
380 http://mirror.kr.FreeBSD.org/CPAN
381 ftp://ftp.kr.FreeBSD.org/pub/CPAN
4e860d0a 382
5df44211 383=item Taiwan
4e860d0a 384
5df44211 385 ftp://ftp.nctu.edu.tw/UNIX/perl/CPAN
5c5c2539
JH
386 http://cpan.cdpa.nsysu.edu.tw/
387 ftp://cpan.cdpa.nsysu.edu.tw/pub/CPAN
388 http://ftp.isu.edu.tw/pub/CPAN
389 ftp://ftp.isu.edu.tw/pub/CPAN
5df44211
JH
390 ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
391 http://ftp.tku.edu.tw/pub/CPAN/
392 ftp://ftp.tku.edu.tw/pub/CPAN/
5df44211 393=item Thailand
4e860d0a 394
5df44211
JH
395 ftp://ftp.loxinfo.co.th/pub/cpan/
396 ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/
4e860d0a
JH
397
398=back
399
400=head2 Central America
401
402=over 4
403
5df44211 404=item Costa Rica
4e860d0a 405
5df44211
JH
406 http://ftp.ucr.ac.cr/Unix/CPAN/
407 ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
4e860d0a
JH
408
409=back
410
411=head2 Europe
412
413=over 4
414
5df44211 415=item Austria
4e860d0a 416
5df44211 417 ftp://ftp.tuwien.ac.at/pub/CPAN/
4e860d0a 418
5df44211 419=item Belgium
4e860d0a 420
5df44211
JH
421 http://ftp.easynet.be/pub/CPAN/
422 ftp://ftp.easynet.be/pub/CPAN/
423 http://cpan.skynet.be
5c5c2539 424 ftp://ftp.cpan.skynet.be/pub/CPAN
5df44211 425 ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
4e860d0a 426
5df44211 427=item Bulgaria
4e860d0a 428
5c5c2539
JH
429 http://cpan.online.bg
430 ftp://cpan.online.bg/cpan
431 http://cpan.zadnik.org
432 ftp://ftp.zadnik.org/mirrors/CPAN/
5df44211
JH
433 http://cpan.lirex.net/
434 ftp://ftp.lirex.net/pub/mirrors/CPAN
4e860d0a 435
5df44211 436=item Croatia
4e860d0a 437
5df44211
JH
438 http://ftp.linux.hr/pub/CPAN/
439 ftp://ftp.linux.hr/pub/CPAN/
4e860d0a 440
5df44211 441=item Czech Republic
4e860d0a 442
5df44211
JH
443 http://ftp.fi.muni.cz/pub/CPAN/
444 ftp://ftp.fi.muni.cz/pub/CPAN/
445 ftp://sunsite.mff.cuni.cz/MIRRORS/ftp.funet.fi/pub/languages/perl/CPAN/
4e860d0a 446
5df44211 447=item Denmark
4e860d0a 448
5df44211
JH
449 http://mirrors.sunsite.dk/cpan/
450 ftp://sunsite.dk/mirrors/cpan/
451 http://cpan.cybercity.dk
452 http://www.cpan.dk/CPAN/
453 ftp://www.cpan.dk/ftp.cpan.org/CPAN/
4e860d0a 454
5df44211 455=item Estonia
4e860d0a 456
5df44211 457 ftp://ftp.ut.ee/pub/languages/perl/CPAN/
4e860d0a 458
5df44211 459=item Finland
4e860d0a 460
5df44211 461 ftp://ftp.funet.fi/pub/languages/perl/CPAN/
5c5c2539 462 http://mirror.eunet.fi/CPAN
4e860d0a 463
5df44211 464=item France
c165c82a 465
5c5c2539 466 http://www.enstimac.fr/Perl/CPAN
5df44211
JH
467 http://ftp.u-paris10.fr/perl/CPAN
468 ftp://ftp.u-paris10.fr/perl/CPAN
469 http://cpan.mirrors.easynet.fr/
470 ftp://cpan.mirrors.easynet.fr/pub/ftp.cpan.org/
471 ftp://ftp.club-internet.fr/pub/perl/CPAN/
472 http://fr.cpan.org/
473 ftp://ftp.lip6.fr/pub/perl/CPAN/
474 ftp://ftp.oleane.net/pub/mirrors/CPAN/
475 ftp://ftp.pasteur.fr/pub/computing/CPAN/
476 http://mir2.ovh.net/ftp.cpan.org
477 ftp://mir1.ovh.net/ftp.cpan.org
5c5c2539
JH
478 http://ftp.crihan.fr/mirrors/ftp.cpan.org/
479 ftp://ftp.crihan.fr/mirrors/ftp.cpan.org/
5df44211
JH
480 http://ftp.u-strasbg.fr/CPAN
481 ftp://ftp.u-strasbg.fr/CPAN
482 http://cpan.cict.fr/
483 ftp://cpan.cict.fr/pub/CPAN/
484 ftp://ftp.uvsq.fr/pub/perl/CPAN/
c165c82a 485
5df44211 486=item Germany
c165c82a 487
5c5c2539 488 ftp://ftp.rub.de/pub/CPAN/
5df44211
JH
489 ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/
490 ftp://ftp.uni-erlangen.de/pub/source/CPAN/
491 ftp://ftp-stud.fht-esslingen.de/pub/Mirrors/CPAN
492 http://pandemonium.tiscali.de/pub/CPAN/
493 ftp://pandemonium.tiscali.de/pub/CPAN/
494 http://ftp.gwdg.de/pub/languages/perl/CPAN/
495 ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
496 ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
497 ftp://ftp.leo.org/pub/CPAN/
498 http://cpan.noris.de/
499 ftp://cpan.noris.de/pub/CPAN/
500 ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
501 ftp://ftp.gmd.de/mirrors/CPAN/
4e860d0a 502
5df44211 503=item Greece
4e860d0a 504
5c5c2539 505 ftp://ftp.acn.gr/pub/lang/perl
5df44211
JH
506 ftp://ftp.forthnet.gr/pub/languages/perl/CPAN
507 ftp://ftp.ntua.gr/pub/lang/perl/
4e860d0a 508
5df44211 509=item Hungary
4e860d0a 510
5df44211
JH
511 http://ftp.kfki.hu/packages/perl/CPAN/
512 ftp://ftp.kfki.hu/pub/packages/perl/CPAN/
4e860d0a 513
5df44211 514=item Iceland
4e860d0a 515
5df44211
JH
516 http://ftp.rhnet.is/pub/CPAN/
517 ftp://ftp.rhnet.is/pub/CPAN/
4e860d0a 518
5df44211 519=item Ireland
4e860d0a 520
5df44211
JH
521 http://cpan.indigo.ie/
522 ftp://cpan.indigo.ie/pub/CPAN/
5c5c2539
JH
523 http://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN
524 ftp://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN
5df44211
JH
525 http://sunsite.compapp.dcu.ie/pub/perl/
526 ftp://sunsite.compapp.dcu.ie/pub/perl/
4e860d0a 527
5df44211 528=item Italy
4e860d0a 529
5df44211
JH
530 http://cpan.nettuno.it/
531 http://gusp.dyndns.org/CPAN/
532 ftp://gusp.dyndns.org/pub/CPAN
533 http://softcity.iol.it/cpan
534 ftp://softcity.iol.it/pub/cpan
535 ftp://ftp.unina.it/pub/Other/CPAN/CPAN/
536 ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
537 ftp://cis.uniRoma2.it/CPAN/
538 ftp://ftp.edisontel.it/pub/CPAN_Mirror/
5c5c2539 539 http://cpan.flashnet.it/
5df44211 540 ftp://ftp.flashnet.it/pub/CPAN/
4e860d0a 541
5df44211 542=item Latvia
4e860d0a 543
5df44211 544 http://kvin.lv/pub/CPAN/
4e860d0a 545
5df44211 546=item Lithuania
4e860d0a 547
5df44211 548 ftp://ftp.unix.lt/pub/CPAN/
4e860d0a 549
5df44211 550=item Netherlands
4e860d0a 551
5df44211
JH
552 ftp://download.xs4all.nl/pub/mirror/CPAN/
553 ftp://ftp.nl.uu.net/pub/CPAN/
554 ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
555 http://cpan.cybercomm.nl/
556 ftp://mirror.cybercomm.nl/pub/CPAN
5c5c2539 557 ftp://mirror.vuurwerk.nl/pub/CPAN/
5df44211
JH
558 ftp://ftp.cpan.nl/pub/CPAN/
559 http://ftp.easynet.nl/mirror/CPAN
560 ftp://ftp.easynet.nl/mirror/CPAN
561 http://archive.cs.uu.nl/mirror/CPAN/
562 ftp://ftp.cs.uu.nl/mirror/CPAN/
4e860d0a 563
5df44211
JH
564=item Norway
565
566 ftp://ftp.uninett.no/pub/languages/perl/CPAN
567 ftp://ftp.uit.no/pub/languages/perl/cpan/
568
569=item Poland
570
5df44211
JH
571 ftp://ftp.man.torun.pl/pub/doc/CPAN/
572 ftp://sunsite.icm.edu.pl/pub/CPAN/
573
574=item Portugal
575
576 ftp://ftp.ua.pt/pub/CPAN/
577 ftp://perl.di.uminho.pt/pub/CPAN/
578 http://cpan.dei.uc.pt/
579 ftp://ftp.dei.uc.pt/pub/CPAN
5c5c2539
JH
580 ftp://ftp.nfsi.pt/pub/CPAN
581 http://ftp.linux.pt/pub/mirrors/CPAN
582 ftp://ftp.linux.pt/pub/mirrors/CPAN
5df44211
JH
583 http://cpan.ip.pt/
584 ftp://cpan.ip.pt/pub/cpan/
5c5c2539
JH
585 http://cpan.telepac.pt/
586 ftp://ftp.telepac.pt/pub/cpan/
4e860d0a 587
5df44211 588=item Romania
4e860d0a 589
5c5c2539 590 ftp://ftp.bio-net.ro/pub/CPAN
5df44211 591 ftp://ftp.kappa.ro/pub/mirrors/ftp.perl.org/pub/CPAN/
5c5c2539 592 ftp://ftp.roedu.net/pub/CPAN/
5df44211 593 ftp://ftp.dntis.ro/pub/cpan/
5c5c2539
JH
594 ftp://ftp.iasi.roedu.net/pub/mirrors/ftp.cpan.org/
595 http://cpan.ambra.ro/
596 ftp://ftp.ambra.ro/pub/CPAN
5df44211
JH
597 ftp://ftp.dnttm.ro/pub/CPAN/
598 ftp://ftp.lasting.ro/pub/CPAN
599 ftp://ftp.timisoara.roedu.net/mirrors/CPAN/
4e860d0a 600
5df44211 601=item Russia
4e860d0a 602
5df44211
JH
603 ftp://ftp.chg.ru/pub/lang/perl/CPAN/
604 http://cpan.rinet.ru/
605 ftp://cpan.rinet.ru/pub/mirror/CPAN/
606 ftp://ftp.aha.ru/pub/CPAN/
607 http://cpan.sai.msu.ru/
608 ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
4e860d0a 609
5df44211 610=item Slovakia
4e860d0a 611
5df44211 612 ftp://ftp.cvt.stuba.sk/pub/CPAN/
4e860d0a 613
5df44211 614=item Slovenia
4e860d0a 615
5df44211 616 ftp://ftp.arnes.si/software/perl/CPAN/
4e860d0a 617
5df44211 618=item Spain
4e860d0a 619
5df44211
JH
620 http://cpan.imasd.elmundo.es/
621 ftp://ftp.rediris.es/mirror/CPAN/
5c5c2539 622 ftp.ri.telefonica-data.net
5df44211 623 ftp://ftp.etse.urv.es/pub/perl/
4e860d0a 624
5df44211 625=item Sweden
4e860d0a 626
5df44211
JH
627 http://ftp.du.se/CPAN/
628 ftp://ftp.du.se/pub/CPAN/
5c5c2539 629 http://mirror.dataphone.se/CPAN
5df44211
JH
630 ftp://mirror.dataphone.se/pub/CPAN
631 ftp://ftp.sunet.se/pub/lang/perl/CPAN/
4e860d0a 632
5df44211 633=item Switzerland
4e860d0a 634
5df44211
JH
635 ftp://ftp.danyk.ch/CPAN/
636 ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
4e860d0a 637
5df44211 638=item Turkey
4e860d0a 639
5df44211
JH
640 http://ftp.ulak.net.tr/perl/CPAN/
641 ftp://ftp.ulak.net.tr/perl/CPAN
642 ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
c165c82a 643
5df44211 644=item Ukraine
c165c82a 645
5df44211
JH
646 http://cpan.org.ua/
647 ftp://cpan.org.ua/
648 ftp://ftp.perl.org.ua/pub/CPAN/
5c5c2539
JH
649 http://no-more.kiev.ua/CPAN/
650 ftp://no-more.kiev.ua/pub/CPAN/
c165c82a 651
5df44211 652=item United Kingdom
d4858812 653
5df44211
JH
654 http://www.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN
655 ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
656 http://cpan.teleglobe.net/
657 ftp://cpan.teleglobe.net/pub/CPAN
5c5c2539
JH
658 http://cpan.mirror.anlx.net/
659 ftp://ftp.mirror.anlx.net/CPAN/
5df44211
JH
660 ftp://ftp.demon.co.uk/pub/CPAN/
661 http://cpan.m.flirble.org/
662 ftp://ftp.flirble.org/pub/languages/perl/CPAN/
663 ftp://ftp.plig.org/pub/CPAN/
5c5c2539 664 http://cpan.hambule.co.uk/
5df44211
JH
665 http://cpan.mirrors.clockerz.net/
666 ftp://ftp.clockerz.net/pub/CPAN/
667 ftp://usit.shef.ac.uk/pub/packages/CPAN/
d4858812 668
4e860d0a
JH
669=back
670
671=head2 North America
672
673=over 4
674
5c5c2539
JH
675=item Canada
676
677=over 4
678
5df44211 679=item Alberta
4e860d0a 680
5c5c2539
JH
681 http://cpan.sunsite.ualberta.ca/
682 ftp://cpan.sunsite.ualberta.ca/pub/CPAN/
4e860d0a 683
5df44211 684=item Manitoba
4e860d0a 685
5df44211
JH
686 http://theoryx5.uwinnipeg.ca/pub/CPAN/
687 ftp://theoryx5.uwinnipeg.ca/pub/CPAN/
4e860d0a 688
5df44211 689=item Nova Scotia
4e860d0a 690
5df44211 691 ftp://cpan.chebucto.ns.ca/pub/CPAN/
4e860d0a 692
5df44211 693=item Ontario
4e860d0a 694
5c5c2539 695 ftp://ftp.nrc.ca/pub/CPAN/
c165c82a 696
5df44211 697=item Mexico
c165c82a 698
5df44211
JH
699 http://cpan.azc.uam.mx
700 ftp://cpan.azc.uam.mx/mirrors/CPAN
701 http://cpan.unam.mx/
702 ftp://cpan.unam.mx/pub/CPAN
703 http://www.msg.com.mx/CPAN/
704 ftp://ftp.msg.com.mx/pub/CPAN/
c165c82a
JH
705
706=back
4e860d0a 707
5c5c2539 708=item United States
d4858812 709
5df44211 710=over 4
4e860d0a 711
5df44211 712=item Alabama
4e860d0a 713
5df44211
JH
714 http://mirror.hiwaay.net/CPAN/
715 ftp://mirror.hiwaay.net/CPAN/
4e860d0a 716
5df44211 717=item California
4e860d0a 718
5df44211
JH
719 http://cpan.develooper.com/
720 http://www.cpan.org/
721 ftp://cpan.valueclick.com/pub/CPAN/
722 http://mirrors.gossamer-threads.com/CPAN
723 ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
724 http://mirrors.kernel.org/cpan/
725 ftp://mirrors.kernel.org/pub/CPAN
726 http://cpan.digisle.net/
727 ftp://cpan.digisle.net/pub/CPAN
728 http://www.perl.com/CPAN/
4e860d0a 729
5df44211 730=item Colorado
4e860d0a 731
5df44211 732 ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
4e860d0a 733
5df44211 734=item Delaware
4e860d0a 735
5df44211
JH
736 http://ftp.lug.udel.edu/pub/CPAN
737 ftp://ftp.lug.udel.edu/pub/CPAN
4e860d0a 738
5df44211 739=item District of Columbia
4e860d0a 740
5df44211 741 ftp://ftp.dc.aleron.net/pub/CPAN/
4e860d0a 742
5df44211 743=item Florida
c165c82a 744
5df44211
JH
745 ftp://ftp.cise.ufl.edu/pub/mirrors/CPAN/
746 http://mirror.csit.fsu.edu/pub/CPAN/
747 ftp://mirror.csit.fsu.edu/pub/CPAN/
748 http://cpan.mirrors.nks.net/
c165c82a 749
5df44211 750=item Illinois
4e860d0a 751
5df44211
JH
752 http://uiarchive.uiuc.edu/mirrors/ftp/cpan.cse.msu.edu/
753 ftp://uiarchive.uiuc.edu/mirrors/ftp/cpan.cse.msu.edu/
4e860d0a 754
5df44211 755=item Indiana
4e860d0a 756
5df44211
JH
757 ftp://ftp.uwsg.iu.edu/pub/perl/CPAN/
758 http://cpan.netnitco.net/
759 ftp://cpan.netnitco.net/pub/mirrors/CPAN/
760 http://archive.progeny.com/CPAN/
761 ftp://archive.progeny.com/CPAN/
5c5c2539
JH
762 http://fx.saintjoe.edu/pub/CPAN
763 ftp://ftp.saintjoe.edu/pub/CPAN
5df44211
JH
764 http://csociety-ftp.ecn.purdue.edu/pub/CPAN
765 ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN
4e860d0a 766
5df44211 767=item Kentucky
4e860d0a 768
5df44211
JH
769 http://cpan.uky.edu/
770 ftp://cpan.uky.edu/pub/CPAN/
5c5c2539
JH
771 http://slugsite.louisville.edu/cpan
772 ftp://slugsite.louisville.edu/CPAN
4e860d0a 773
5df44211 774=item Massachusetts
4e860d0a 775
5c5c2539
JH
776 http://mirrors.towardex.com/CPAN
777 ftp://mirrors.towardex.com/pub/CPAN
5df44211 778 ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
4e860d0a 779
5df44211 780=item Michigan
4e860d0a 781
5df44211 782 ftp://cpan.cse.msu.edu/
4e860d0a 783
5c5c2539
JH
784=item Nevada
785
786 http://www.oss.redundant.com/pub/CPAN
787 ftp://www.oss.redundant.com/pub/CPAN
788
5df44211 789=item New Jersey
4e860d0a 790
5c5c2539 791 http://ftp.cpanel.net/pub/CPAN/
5df44211
JH
792 ftp://ftp.cpanel.net/pub/CPAN/
793 http://cpan.teleglobe.net/
794 ftp://cpan.teleglobe.net/pub/CPAN
4e860d0a 795
5df44211 796=item New York
4e860d0a 797
5df44211 798 http://cpan.belfry.net/
5c5c2539
JH
799 http://cpan.erlbaum.net/
800 ftp://cpan.erlbaum.net/
5df44211
JH
801 http://cpan.thepirtgroup.com/
802 ftp://cpan.thepirtgroup.com/
803 ftp://ftp.stealth.net/pub/CPAN/
804 http://www.rge.com/pub/languages/perl/
805 ftp://ftp.rge.com/pub/languages/perl/
4e860d0a 806
5df44211 807=item North Carolina
4e860d0a 808
5df44211 809 ftp://ftp.duke.edu/pub/perl/
5c5c2539 810 ftp://ftp.ncsu.edu/pub/mirror/CPAN/
4e860d0a 811
5df44211 812=item Oklahoma
4e860d0a 813
5df44211 814 ftp://ftp.ou.edu/mirrors/CPAN/
4e860d0a 815
5df44211 816=item Oregon
4e860d0a 817
5df44211 818 ftp://ftp.orst.edu/pub/CPAN
4e860d0a 819
5df44211 820=item Pennsylvania
4e860d0a 821
5df44211
JH
822 http://ftp.epix.net/CPAN/
823 ftp://ftp.epix.net/pub/languages/perl/
824 http://mirrors.phenominet.com/pub/CPAN/
825 ftp://mirrors.phenominet.com/pub/CPAN/
826 http://cpan.pair.com/
827 ftp://cpan.pair.com/pub/CPAN/
828 ftp://carroll.cac.psu.edu/pub/CPAN/
4e860d0a 829
5df44211 830=item Tennessee
4e860d0a 831
5df44211 832 ftp://ftp.sunsite.utk.edu/pub/CPAN/
4e860d0a 833
5df44211 834=item Texas
4e860d0a 835
5df44211 836 http://ftp.sedl.org/pub/mirrors/CPAN/
5c5c2539 837 http://www.binarycode.org/cpan
5df44211 838 ftp://mirror.telentente.com/pub/CPAN
5c5c2539 839 http://mirrors.theonlinerecordstore.com/CPAN
4e860d0a 840
5df44211 841=item Utah
4e860d0a 842
5df44211 843 ftp://mirror.xmission.com/CPAN/
4e860d0a 844
5df44211 845=item Virginia
4e860d0a 846
5df44211
JH
847 http://mirrors.rcn.net/pub/lang/CPAN/
848 ftp://mirrors.rcn.net/pub/lang/CPAN/
849 http://perl.secsup.org/
850 ftp://perl.secsup.org/pub/perl/
5c5c2539 851 http://noc.cvaix.com/mirrors/CPAN/
4e860d0a 852
5c5c2539 853=item Washington
4e860d0a 854
5df44211
JH
855 http://cpan.llarian.net/
856 ftp://cpan.llarian.net/pub/CPAN/
857 http://cpan.mirrorcentral.com/
858 ftp://ftp.mirrorcentral.com/pub/CPAN/
859 ftp://ftp-mirror.internap.com/pub/CPAN/
d4858812 860
5df44211 861=item Wisconsin
d4858812 862
5df44211
JH
863 http://mirror.sit.wisc.edu/pub/CPAN/
864 ftp://mirror.sit.wisc.edu/pub/CPAN/
4e860d0a
JH
865
866=back
867
5c5c2539
JH
868=back
869
4e860d0a
JH
870=head2 Oceania
871
872=over 4
873
5df44211 874=item Australia
4e860d0a 875
5df44211
JH
876 http://ftp.planetmirror.com/pub/CPAN/
877 ftp://ftp.planetmirror.com/pub/CPAN/
878 ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
879 ftp://cpan.topend.com.au/pub/CPAN/
4e860d0a 880
5df44211 881=item New Zealand
d4858812 882
5df44211 883 ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
5c5c2539
JH
884
885=item United States
886
887 http://aniani.ifa.hawaii.edu/CPAN/
888 ftp://aniani.ifa.hawaii.edu/CPAN/
4e860d0a
JH
889
890=back
891
892=head2 South America
893
894=over 4
895
5df44211 896=item Argentina
4e860d0a 897
5df44211 898 ftp://mirrors.bannerlandia.com.ar/mirrors/CPAN/
5c5c2539
JH
899 http://www.linux.org.ar/mirrors/cpan
900 ftp://ftp.linux.org.ar/mirrors/cpan
4e860d0a 901
5df44211 902=item Brazil
4e860d0a 903
5df44211
JH
904 ftp://cpan.pop-mg.com.br/pub/CPAN/
905 ftp://ftp.matrix.com.br/pub/perl/CPAN/
5c5c2539
JH
906 http://cpan.hostsul.com.br/
907 ftp://cpan.hostsul.com.br/
4e860d0a 908
5df44211 909=item Chile
4e860d0a 910
5df44211
JH
911 http://cpan.netglobalis.net/
912 ftp://cpan.netglobalis.net/pub/CPAN/
2e1d04bc
JH
913
914=back
915
5df44211
JH
916=head2 RSYNC Mirrors
917
5c5c2539
JH
918 ftp.shellhung.org::CPAN
919 ftp.cbn.net.id::CPAN
920 ftp.iglu.org.il::CPAN
921 ftp.kddlabs.co.jp::cpan
922 ftp.ayamura.org::pub/CPAN/
923 mirror.leafbug.org::CPAN
924 rsync.en.com.sg::CPAN
925 mirror.averse.net::cpan
926 rsync.oss.eznetsols.org
927 ftp.kr.FreeBSD.org::CPAN
928 cpan.cdpa.nsysu.edu.tw::CPAN
929 rsync.nic.funet.fi::CPAN
930 ftp.u-paris10.fr::CPAN
931 mir1.ovh.net::CPAN
932 ftp.crihan.fr::CPAN
933 ftp.gwdg.de::FTP/languages/perl/CPAN/
934 ftp.leo.org::CPAN
935 ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN
936 gusp.dyndns.org::cpan
937 cpan.teleglobe.net::CPAN
938 rsync://rsync.mirror.anlx.net::CPAN
939 theoryx5.uwinnipeg.ca::CPAN
940 ftp.sedl.org::cpan
941 archive.progeny.com::CPAN
942 slugsite.louisville.edu::CPAN
943 cpan.teleglobe.net::CPAN
944 ftp.lug.udel.edu::cpan
945 mirrors.kernel.org::mirrors/CPAN
946 mirrors.phenominet.com::CPAN
947 mirror.csit.fsu.edu::CPAN
948 csociety-ftp.ecn.purdue.edu::CPAN
949 aniani.ifa.hawaii.edu::CPAN
950 www.linux.org.ar::cpan
5df44211 951
2e1d04bc 952For an up-to-date listing of CPAN sites,
4e860d0a 953see http://www.cpan.org/SITES or ftp://www.cpan.org/SITES .
2e1d04bc
JH
954
955=head1 Modules: Creation, Use, and Abuse
956
957(The following section is borrowed directly from Tim Bunce's modules
958file, available at your nearest CPAN site.)
959
960Perl implements a class using a package, but the presence of a
961package doesn't imply the presence of a class. A package is just a
962namespace. A class is a package that provides subroutines that can be
963used as methods. A method is just a subroutine that expects, as its
964first argument, either the name of a package (for "static" methods),
965or a reference to something (for "virtual" methods).
966
967A module is a file that (by convention) provides a class of the same
968name (sans the .pm), plus an import method in that class that can be
969called to fetch exported symbols. This module may implement some of
970its methods by loading dynamic C or C++ objects, but that should be
971totally transparent to the user of the module. Likewise, the module
972might set up an AUTOLOAD function to slurp in subroutine definitions on
973demand, but this is also transparent. Only the F<.pm> file is required to
974exist. See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about
975the AUTOLOAD mechanism.
976
977=head2 Guidelines for Module Creation
978
979=over 4
980
ac634a9a
JH
981=item *
982
983Do similar modules already exist in some form?
2e1d04bc
JH
984
985If so, please try to reuse the existing modules either in whole or
986by inheriting useful features into a new class. If this is not
987practical try to get together with the module authors to work on
988extending or enhancing the functionality of the existing modules.
989A perfect example is the plethora of packages in perl4 for dealing
990with command line options.
991
992If you are writing a module to expand an already existing set of
993modules, please coordinate with the author of the package. It
994helps if you follow the same naming scheme and module interaction
995scheme as the original author.
996
ac634a9a
JH
997=item *
998
999Try to design the new module to be easy to extend and reuse.
2e1d04bc
JH
1000
1001Try to C<use warnings;> (or C<use warnings qw(...);>).
1002Remember that you can add C<no warnings qw(...);> to individual blocks
1003of code that need less warnings.
1004
1005Use blessed references. Use the two argument form of bless to bless
1006into the class name given as the first parameter of the constructor,
1007e.g.,:
1008
1009 sub new {
1010 my $class = shift;
1011 return bless {}, $class;
1012 }
1013
1014or even this if you'd like it to be used as either a static
1015or a virtual method.
1016
1017 sub new {
1018 my $self = shift;
1019 my $class = ref($self) || $self;
1020 return bless {}, $class;
1021 }
1022
1023Pass arrays as references so more parameters can be added later
1024(it's also faster). Convert functions into methods where
1025appropriate. Split large methods into smaller more flexible ones.
1026Inherit methods from other modules if appropriate.
1027
1028Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
1029Generally you can delete the C<eq 'FOO'> part with no harm at all.
1030Let the objects look after themselves! Generally, avoid hard-wired
1031class names as far as possible.
1032
1033Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
1034C<< $r->func() >> would work (see L<perlbot> for more details).
1035
1036Use autosplit so little used or newly added functions won't be a
1037burden to programs that don't use them. Add test functions to
1038the module after __END__ either using AutoSplit or by saying:
1039
1040 eval join('',<main::DATA>) || die $@ unless caller();
1041
1042Does your module pass the 'empty subclass' test? If you say
1043C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
1044to use SUBCLASS in exactly the same way as YOURCLASS. For example,
1045does your application still work if you change: C<$obj = new YOURCLASS;>
1046into: C<$obj = new SUBCLASS;> ?
1047
1048Avoid keeping any state information in your packages. It makes it
1049difficult for multiple other packages to use yours. Keep state
1050information in objects.
1051
1052Always use B<-w>.
1053
1054Try to C<use strict;> (or C<use strict qw(...);>).
1055Remember that you can add C<no strict qw(...);> to individual blocks
1056of code that need less strictness.
1057
1058Always use B<-w>.
1059
1060Follow the guidelines in the perlstyle(1) manual.
1061
1062Always use B<-w>.
1063
ac634a9a
JH
1064=item *
1065
1066Some simple style guidelines
2e1d04bc
JH
1067
1068The perlstyle manual supplied with Perl has many helpful points.
1069
1070Coding style is a matter of personal taste. Many people evolve their
1071style over several years as they learn what helps them write and
1072maintain good code. Here's one set of assorted suggestions that
1073seem to be widely used by experienced developers:
1074
1075Use underscores to separate words. It is generally easier to read
1076$var_names_like_this than $VarNamesLikeThis, especially for
1077non-native speakers of English. It's also a simple rule that works
1078consistently with VAR_NAMES_LIKE_THIS.
1079
1080Package/Module names are an exception to this rule. Perl informally
1081reserves lowercase module names for 'pragma' modules like integer
1082and strict. Other modules normally begin with a capital letter and
1083use mixed case with no underscores (need to be short and portable).
1084
1085You may find it helpful to use letter case to indicate the scope
1086or nature of a variable. For example:
1087
1088 $ALL_CAPS_HERE constants only (beware clashes with Perl vars)
1089 $Some_Caps_Here package-wide global/static
1090 $no_caps_here function scope my() or local() variables
1091
1092Function and method names seem to work best as all lowercase.
1093e.g., C<< $obj->as_string() >>.
1094
1095You can use a leading underscore to indicate that a variable or
1096function should not be used outside the package that defined it.
1097
ac634a9a
JH
1098=item *
1099
1100Select what to export.
2e1d04bc
JH
1101
1102Do NOT export method names!
1103
1104Do NOT export anything else by default without a good reason!
1105
1106Exports pollute the namespace of the module user. If you must
1107export try to use @EXPORT_OK in preference to @EXPORT and avoid
1108short or common names to reduce the risk of name clashes.
1109
1110Generally anything not exported is still accessible from outside the
1111module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
1112syntax. By convention you can use a leading underscore on names to
1113indicate informally that they are 'internal' and not for public use.
1114
1115(It is actually possible to get private functions by saying:
1116C<my $subref = sub { ... }; &$subref;>. But there's no way to call that
1117directly as a method, because a method must have a name in the symbol
1118table.)
1119
1120As a general rule, if the module is trying to be object oriented
1121then export nothing. If it's just a collection of functions then
1122@EXPORT_OK anything but use @EXPORT with caution.
1123
ac634a9a
JH
1124=item *
1125
1126Select a name for the module.
2e1d04bc
JH
1127
1128This name should be as descriptive, accurate, and complete as
1129possible. Avoid any risk of ambiguity. Always try to use two or
1130more whole words. Generally the name should reflect what is special
1131about what the module does rather than how it does it. Please use
1132nested module names to group informally or categorize a module.
1133There should be a very good reason for a module not to have a nested name.
1134Module names should begin with a capital letter.
1135
1136Having 57 modules all called Sort will not make life easy for anyone
1137(though having 23 called Sort::Quick is only marginally better :-).
1138Imagine someone trying to install your module alongside many others.
1139If in any doubt ask for suggestions in comp.lang.perl.misc.
1140
1141If you are developing a suite of related modules/classes it's good
1142practice to use nested classes with a common prefix as this will
1143avoid namespace clashes. For example: Xyz::Control, Xyz::View,
1144Xyz::Model etc. Use the modules in this list as a naming guide.
1145
1146If adding a new module to a set, follow the original author's
1147standards for naming modules and the interface to methods in
1148those modules.
1149
4844a3be
SP
1150If developing modules for private internal or project specific use,
1151that will never be released to the public, then you should ensure
1152that their names will not clash with any future public module. You
1153can do this either by using the reserved Local::* category or by
1154using a category name that includes an underscore like Foo_Corp::*.
1155
2e1d04bc
JH
1156To be portable each component of a module name should be limited to
115711 characters. If it might be used on MS-DOS then try to ensure each is
1158unique in the first 8 characters. Nested modules make this easier.
1159
ac634a9a
JH
1160=item *
1161
1162Have you got it right?
2e1d04bc
JH
1163
1164How do you know that you've made the right decisions? Have you
1165picked an interface design that will cause problems later? Have
1166you picked the most appropriate name? Do you have any questions?
1167
1168The best way to know for sure, and pick up many helpful suggestions,
1169is to ask someone who knows. Comp.lang.perl.misc is read by just about
1170all the people who develop modules and it's the best place to ask.
1171
1172All you need to do is post a short summary of the module, its
1173purpose and interfaces. A few lines on each of the main methods is
1174probably enough. (If you post the whole module it might be ignored
1175by busy people - generally the very people you want to read it!)
1176
1177Don't worry about posting if you can't say when the module will be
1178ready - just say so in the message. It might be worth inviting
1179others to help you, they may be able to complete it for you!
1180
ac634a9a
JH
1181=item *
1182
1183README and other Additional Files.
2e1d04bc
JH
1184
1185It's well known that software developers usually fully document the
1186software they write. If, however, the world is in urgent need of
1187your software and there is not enough time to write the full
1188documentation please at least provide a README file containing:
1189
1190=over 10
1191
1192=item *
ac634a9a 1193
2e1d04bc
JH
1194A description of the module/package/extension etc.
1195
1196=item *
ac634a9a 1197
2e1d04bc
JH
1198A copyright notice - see below.
1199
1200=item *
ac634a9a 1201
2e1d04bc
JH
1202Prerequisites - what else you may need to have.
1203
1204=item *
ac634a9a 1205
2e1d04bc
JH
1206How to build it - possible changes to Makefile.PL etc.
1207
1208=item *
ac634a9a 1209
2e1d04bc
JH
1210How to install it.
1211
1212=item *
ac634a9a 1213
2e1d04bc
JH
1214Recent changes in this release, especially incompatibilities
1215
1216=item *
ac634a9a 1217
2e1d04bc
JH
1218Changes / enhancements you plan to make in the future.
1219
1220=back
1221
1222If the README file seems to be getting too large you may wish to
1223split out some of the sections into separate files: INSTALL,
1224Copying, ToDo etc.
1225
1226=over 4
1227
c165c82a 1228=item *
2e1d04bc 1229
c165c82a 1230Adding a Copyright Notice.
ac634a9a 1231
2e1d04bc
JH
1232How you choose to license your work is a personal decision.
1233The general mechanism is to assert your Copyright and then make
1234a declaration of how others may copy/use/modify your work.
1235
2a551100
JH
1236Perl, for example, is supplied with two types of licence: The GNU GPL
1237and The Artistic Licence (see the files README, Copying, and Artistic,
1238or L<perlgpl> and L<perlartistic>). Larry has good reasons for NOT
1239just using the GNU GPL.
2e1d04bc
JH
1240
1241My personal recommendation, out of respect for Larry, Perl, and the
1242Perl community at large is to state something simply like:
1243
1244 Copyright (c) 1995 Your Name. All rights reserved.
1245 This program is free software; you can redistribute it and/or
1246 modify it under the same terms as Perl itself.
1247
1248This statement should at least appear in the README file. You may
1249also wish to include it in a Copying file and your source files.
1250Remember to include the other words in addition to the Copyright.
1251
ac634a9a
JH
1252=item *
1253
1254Give the module a version/issue/release number.
2e1d04bc
JH
1255
1256To be fully compatible with the Exporter and MakeMaker modules you
1257should store your module's version number in a non-my package
1258variable called $VERSION. This should be a floating point
1259number with at least two digits after the decimal (i.e., hundredths,
1260e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version.
1261See L<Exporter> for details.
1262
1263It may be handy to add a function or method to retrieve the number.
1264Use the number in announcements and archive file names when
1265releasing the module (ModuleName-1.02.tar.Z).
1266See perldoc ExtUtils::MakeMaker.pm for details.
1267
ac634a9a
JH
1268=item *
1269
1270How to release and distribute a module.
2e1d04bc
JH
1271
1272It's good idea to post an announcement of the availability of your
1273module (or the module itself if small) to the comp.lang.perl.announce
1274Usenet newsgroup. This will at least ensure very wide once-off
1275distribution.
1276
1277If possible, register the module with CPAN. You should
1278include details of its location in your announcement.
1279
1280Some notes about ftp archives: Please use a long descriptive file
1281name that includes the version number. Most incoming directories
1282will not be readable/listable, i.e., you won't be able to see your
1283file after uploading it. Remember to send your email notification
1284message as soon as possible after uploading else your file may get
1285deleted automatically. Allow time for the file to be processed
1286and/or check the file has been processed before announcing its
1287location.
1288
1289FTP Archives for Perl Modules:
1290
1291Follow the instructions and links on:
1292
4e860d0a
JH
1293 http://www.cpan.org/modules/00modlist.long.html
1294 http://www.cpan.org/modules/04pause.html
2e1d04bc
JH
1295
1296or upload to one of these sites:
1297
1298 https://pause.kbx.de/pause/
1299 http://pause.perl.org/pause/
1300
1301and notify <modules@perl.org>.
1302
1303By using the WWW interface you can ask the Upload Server to mirror
1304your modules from your ftp or WWW site into your own directory on
1305CPAN!
1306
1307Please remember to send me an updated entry for the Module list!
1308
ac634a9a
JH
1309=item *
1310
1311Take care when changing a released module.
2e1d04bc
JH
1312
1313Always strive to remain compatible with previous released versions.
1314Otherwise try to add a mechanism to revert to the
1315old behavior if people rely on it. Document incompatible changes.
1316
1317=back
1318
1319=back
1320
1321=head2 Guidelines for Converting Perl 4 Library Scripts into Modules
1322
1323=over 4
1324
ac634a9a
JH
1325=item *
1326
1327There is no requirement to convert anything.
2e1d04bc
JH
1328
1329If it ain't broke, don't fix it! Perl 4 library scripts should
1330continue to work with no problems. You may need to make some minor
1331changes (like escaping non-array @'s in double quoted strings) but
1332there is no need to convert a .pl file into a Module for just that.
1333
ac634a9a
JH
1334=item *
1335
1336Consider the implications.
2e1d04bc
JH
1337
1338All Perl applications that make use of the script will need to
1339be changed (slightly) if the script is converted into a module. Is
1340it worth it unless you plan to make other changes at the same time?
1341
ac634a9a
JH
1342=item *
1343
1344Make the most of the opportunity.
2e1d04bc
JH
1345
1346If you are going to convert the script to a module you can use the
1347opportunity to redesign the interface. The guidelines for module
1348creation above include many of the issues you should consider.
1349
ac634a9a
JH
1350=item *
1351
1352The pl2pm utility will get you started.
2e1d04bc
JH
1353
1354This utility will read *.pl files (given as parameters) and write
1355corresponding *.pm files. The pl2pm utilities does the following:
1356
1357=over 10
1358
1359=item *
ac634a9a 1360
2e1d04bc
JH
1361Adds the standard Module prologue lines
1362
1363=item *
ac634a9a 1364
2e1d04bc
JH
1365Converts package specifiers from ' to ::
1366
1367=item *
ac634a9a 1368
2e1d04bc
JH
1369Converts die(...) to croak(...)
1370
1371=item *
ac634a9a 1372
2e1d04bc
JH
1373Several other minor changes
1374
1375=back
1376
1377Being a mechanical process pl2pm is not bullet proof. The converted
1378code will need careful checking, especially any package statements.
1379Don't delete the original .pl file till the new .pm one works!
1380
1381=back
1382
1383=head2 Guidelines for Reusing Application Code
1384
1385=over 4
1386
ac634a9a
JH
1387=item *
1388
1389Complete applications rarely belong in the Perl Module Library.
1390
1391=item *
2e1d04bc 1392
ac634a9a 1393Many applications contain some Perl code that could be reused.
2e1d04bc
JH
1394
1395Help save the world! Share your code in a form that makes it easy
1396to reuse.
1397
ac634a9a
JH
1398=item *
1399
1400Break-out the reusable code into one or more separate module files.
1401
1402=item *
1403
1404Take the opportunity to reconsider and redesign the interfaces.
2e1d04bc 1405
ac634a9a 1406=item *
2e1d04bc 1407
ac634a9a 1408In some cases the 'application' can then be reduced to a small
2e1d04bc
JH
1409
1410fragment of code built on top of the reusable modules. In these cases
1411the application could invoked as:
1412
1413 % perl -e 'use Module::Name; method(@ARGV)' ...
1414or
1415 % perl -mModule::Name ... (in perl5.002 or higher)
1416
1417=back
1418
1419=head1 NOTE
1420
1421Perl does not enforce private and public parts of its modules as you may
1422have been used to in other languages like C++, Ada, or Modula-17. Perl
1423doesn't have an infatuation with enforced privacy. It would prefer
1424that you stayed out of its living room because you weren't invited, not
1425because it has a shotgun.
1426
1427The module and its user have a contract, part of which is common law,
1428and part of which is "written". Part of the common law contract is
1429that a module doesn't pollute any namespace it wasn't asked to. The
1430written contract for the module (A.K.A. documentation) may make other
1431provisions. But then you know when you C<use RedefineTheWorld> that
1432you're redefining the world and willing to take the consequences.
1433EOF
1434
1435close MANIFEST or warn "$0: failed to close MANIFEST (../MANIFEST): $!";
1436close OUT or warn "$0: failed to close OUT (perlmodlib.tmp): $!";
1437