diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/perlnewmod.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/perlnewmod.1 | 319 |
1 files changed, 319 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/perlnewmod.1 b/upstream/mageia-cauldron/man1/perlnewmod.1 new file mode 100644 index 00000000..315343bb --- /dev/null +++ b/upstream/mageia-cauldron/man1/perlnewmod.1 @@ -0,0 +1,319 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "PERLNEWMOD 1" +.TH PERLNEWMOD 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +perlnewmod \- preparing a new module for distribution +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This document gives you some suggestions about how to go about writing +Perl modules, preparing them for distribution, and making them available +via CPAN. +.PP +One of the things that makes Perl really powerful is the fact that Perl +hackers tend to want to share the solutions to problems they've faced, +so you and I don't have to battle with the same problem again. +.PP +The main way they do this is by abstracting the solution into a Perl +module. If you don't know what one of these is, the rest of this +document isn't going to be much use to you. You're also missing out on +an awful lot of useful code; consider having a look at perlmod, +perlmodlib and perlmodinstall before coming back here. +.PP +When you've found that there isn't a module available for what you're +trying to do, and you've had to write the code yourself, consider +packaging up the solution into a module and uploading it to CPAN so that +others can benefit. +.PP +You should also take a look at perlmodstyle for best practices in +making a module. +.SS Warning +.IX Subsection "Warning" +We're going to primarily concentrate on Perl-only modules here, rather +than XS modules. XS modules serve a rather different purpose, and +you should consider different things before distributing them \- the +popularity of the library you are gluing, the portability to other +operating systems, and so on. However, the notes on preparing the Perl +side of the module and packaging and distributing it will apply equally +well to an XS module as a pure-Perl one. +.SS "What should I make into a module?" +.IX Subsection "What should I make into a module?" +You should make a module out of any code that you think is going to be +useful to others. Anything that's likely to fill a hole in the communal +library and which someone else can slot directly into their program. Any +part of your code which you can isolate and extract and plug into +something else is a likely candidate. +.PP +Let's take an example. Suppose you're reading in data from a local +format into a hash-of-hashes in Perl, turning that into a tree, walking +the tree and then piping each node to an Acme Transmogrifier Server. +.PP +Now, quite a few people have the Acme Transmogrifier, and you've had to +write something to talk the protocol from scratch \- you'd almost +certainly want to make that into a module. The level at which you pitch +it is up to you: you might want protocol-level modules analogous to +Net::SMTP which then talk to higher level modules analogous +to Mail::Send. The choice is yours, but you do want to get +a module out for that server protocol. +.PP +Nobody else on the planet is going to talk your local data format, so we +can ignore that. But what about the thing in the middle? Building tree +structures from Perl variables and then traversing them is a nice, +general problem, and if nobody's already written a module that does +that, you might want to modularise that code too. +.PP +So hopefully you've now got a few ideas about what's good to modularise. +Let's now see how it's done. +.SS "Step-by-step: Preparing the ground" +.IX Subsection "Step-by-step: Preparing the ground" +Before we even start scraping out the code, there are a few things we'll +want to do in advance. +.IP "Look around" 3 +.IX Item "Look around" +Dig into a bunch of modules to see how they're written. I'd suggest +starting with Text::Tabs, since it's in the standard +library and is nice and simple, and then looking at something a little +more complex like File::Copy. For object oriented +code, WWW::Mechanize or the \f(CW\*(C`Email::*\*(C'\fR modules provide some good +examples. +.Sp +These should give you an overall feel for how modules are laid out and +written. +.IP "Check it's new" 3 +.IX Item "Check it's new" +There are a lot of modules on CPAN, and it's easy to miss one that's +similar to what you're planning on contributing. Have a good plough +through <https://metacpan.org> and make sure you're not the one +reinventing the wheel! +.IP "Discuss the need" 3 +.IX Item "Discuss the need" +You might love it. You might feel that everyone else needs it. But there +might not actually be any real demand for it out there. If you're unsure +about the demand your module will have, consider asking the +\&\f(CW\*(C`module\-authors@perl.org\*(C'\fR mailing list (send an email to +\&\f(CW\*(C`module\-authors\-subscribe@perl.org\*(C'\fR to subscribe; see +<https://lists.perl.org/list/module\-authors.html> for more information +and a link to the archives). +.IP "Choose a name" 3 +.IX Item "Choose a name" +Perl modules included on CPAN have a naming hierarchy you should try to +fit in with. See perlmodlib for more details on how this works, and +browse around CPAN and the modules list to get a feel of it. At the very +least, remember this: modules should be title capitalised, (This::Thing) +fit in with a category, and explain their purpose succinctly. +.IP "Check again" 3 +.IX Item "Check again" +While you're doing that, make really sure you haven't missed a module +similar to the one you're about to write. +.Sp +When you've got your name sorted out and you're sure that your module is +wanted and not currently available, it's time to start coding. +.SS "Step-by-step: Making the module" +.IX Subsection "Step-by-step: Making the module" +.IP "Start with \fImodule-starter\fR or \fIh2xs\fR" 3 +.IX Item "Start with module-starter or h2xs" +The \fImodule-starter\fR utility is distributed as part of the +Module::Starter CPAN package. It creates a directory +with stubs of all the necessary files to start a new module, according +to recent "best practice" for module development, and is invoked from +the command line, thus: +.Sp +.Vb 2 +\& module\-starter \-\-module=Foo::Bar \e +\& \-\-author="Your Name" \-\-email=yourname@cpan.org +.Ve +.Sp +If you do not wish to install the Module::Starter +package from CPAN, \fIh2xs\fR is an older tool, originally intended for the +development of XS modules, which comes packaged with the Perl +distribution. +.Sp +A typical invocation of h2xs for a pure Perl module is: +.Sp +.Vb 1 +\& h2xs \-AX \-\-skip\-exporter \-\-use\-new\-tests \-n Foo::Bar +.Ve +.Sp +The \f(CW\*(C`\-A\*(C'\fR omits the Autoloader code, \f(CW\*(C`\-X\*(C'\fR omits XS elements, +\&\f(CW\*(C`\-\-skip\-exporter\*(C'\fR omits the Exporter code, \f(CW\*(C`\-\-use\-new\-tests\*(C'\fR sets up a +modern testing environment, and \f(CW\*(C`\-n\*(C'\fR specifies the name of the module. +.IP "Use strict and warnings" 3 +.IX Item "Use strict and warnings" +A module's code has to be warning and strict-clean, since you can't +guarantee the conditions that it'll be used under. Besides, you wouldn't +want to distribute code that wasn't warning or strict-clean anyway, +right? +.IP "Use Carp" 3 +.IX Item "Use Carp" +The Carp module allows you to present your error messages from +the caller's perspective; this gives you a way to signal a problem with +the caller and not your module. For instance, if you say this: +.Sp +.Vb 1 +\& warn "No hostname given"; +.Ve +.Sp +the user will see something like this: +.Sp +.Vb 2 +\& No hostname given at +\& /usr/local/lib/perl5/site_perl/5.6.0/Net/Acme.pm line 123. +.Ve +.Sp +which looks like your module is doing something wrong. Instead, you want +to put the blame on the user, and say this: +.Sp +.Vb 1 +\& No hostname given at bad_code, line 10. +.Ve +.Sp +You do this by using Carp and replacing your \f(CW\*(C`warn\*(C'\fRs with +\&\f(CW\*(C`carp\*(C'\fRs. If you need to \f(CW\*(C`die\*(C'\fR, say \f(CW\*(C`croak\*(C'\fR instead. However, keep +\&\f(CW\*(C`warn\*(C'\fR and \f(CW\*(C`die\*(C'\fR in place for your sanity checks \- where it really is +your module at fault. +.IP "Use Exporter \- wisely!" 3 +.IX Item "Use Exporter - wisely!" +Exporter gives you a standard way of exporting symbols and +subroutines from your module into the caller's namespace. For instance, +saying \f(CW\*(C`use Net::Acme qw(&frob)\*(C'\fR would import the \f(CW\*(C`frob\*(C'\fR subroutine. +.Sp +The package variable \f(CW@EXPORT\fR will determine which symbols will get +exported when the caller simply says \f(CW\*(C`use Net::Acme\*(C'\fR \- you will hardly +ever want to put anything in there. \f(CW@EXPORT_OK\fR, on the other hand, +specifies which symbols you're willing to export. If you do want to +export a bunch of symbols, use the \f(CW%EXPORT_TAGS\fR and define a standard +export set \- look at Exporter for more details. +.IP "Use plain old documentation" 3 +.IX Item "Use plain old documentation" +The work isn't over until the paperwork is done, and you're going to +need to put in some time writing some documentation for your module. +\&\f(CW\*(C`module\-starter\*(C'\fR or \f(CW\*(C`h2xs\*(C'\fR will provide a stub for you to fill in; if +you're not sure about the format, look at perlpod for an +introduction. Provide a good synopsis of how your module is used in +code, a description, and then notes on the syntax and function of the +individual subroutines or methods. Use Perl comments for developer notes +and POD for end-user notes. +.IP "Write tests" 3 +.IX Item "Write tests" +You're encouraged to create self-tests for your module to ensure it's +working as intended on the myriad platforms Perl supports; if you upload +your module to CPAN, a host of testers will build your module and send +you the results of the tests. Again, \f(CW\*(C`module\-starter\*(C'\fR and \f(CW\*(C`h2xs\*(C'\fR +provide a test framework which you can extend \- you should do something +more than just checking your module will compile. +Test::Simple and Test::More are good +places to start when writing a test suite. +.IP "Write the \fIREADME\fR" 3 +.IX Item "Write the README" +If you're uploading to CPAN, the automated gremlins will extract the +README file and place that in your CPAN directory. It'll also appear in +the main \fIby-module\fR and \fIby-category\fR directories if you make it onto +the modules list. It's a good idea to put here what the module actually +does in detail. +.IP "Write \fIChanges\fR" 3 +.IX Item "Write Changes" +Add any user-visible changes since the last release to your \fIChanges\fR +file. +.SS "Step-by-step: Distributing your module" +.IX Subsection "Step-by-step: Distributing your module" +.IP "Get a CPAN user ID" 3 +.IX Item "Get a CPAN user ID" +Every developer publishing modules on CPAN needs a CPAN ID. Visit +\&\f(CW\*(C`<https://pause.perl.org/>\*(C'\fR, select "Request PAUSE Account", and wait for +your request to be approved by the PAUSE administrators. +.IP "Make the tarball" 3 +.IX Item "Make the tarball" +Once again, \f(CW\*(C`module\-starter\*(C'\fR or \f(CW\*(C`h2xs\*(C'\fR has done all the work for you. +They produce the standard \f(CW\*(C`Makefile.PL\*(C'\fR you see when you download and +install modules, and this produces a Makefile with a \f(CW\*(C`dist\*(C'\fR target. +.Sp +.Vb 1 +\& perl Makefile.PL && make test && make distcheck && make dist +.Ve +.Sp +Once you've ensured that your module passes its own tests \- always a +good thing to make sure \- you can \f(CW\*(C`make distcheck\*(C'\fR to make sure +everything looks OK, followed by \f(CW\*(C`make dist\*(C'\fR, and the Makefile will +hopefully produce you a nice tarball of your module, ready for upload. +.IP "Upload the tarball" 3 +.IX Item "Upload the tarball" +The email you got when you received your CPAN ID will tell you how to +log in to PAUSE, the Perl Authors Upload SErver. From the menus there, +you can upload your module to CPAN. +.Sp +Alternatively you can use the \fIcpan-upload\fR script, part of the +CPAN::Uploader distribution on CPAN. +.IP "Fix bugs!" 3 +.IX Item "Fix bugs!" +Once you start accumulating users, they'll send you bug reports. If +you're lucky, they'll even send you patches. Welcome to the joys of +maintaining a software project... +.SH AUTHOR +.IX Header "AUTHOR" +Simon Cozens, \f(CW\*(C`simon@cpan.org\*(C'\fR +.PP +Updated by Kirrily "Skud" Robert, \f(CW\*(C`skud@cpan.org\*(C'\fR +.SH "SEE ALSO" +.IX Header "SEE ALSO" +perlmod, perlmodlib, perlmodinstall, h2xs, strict, +Carp, Exporter, perlpod, Test::Simple, Test::More +ExtUtils::MakeMaker, Module::Build, Module::Starter +<https://www.cpan.org/> |