{
    "mode": "man",
    "parameter": "PERLNEWMOD",
    "section": "1",
    "url": "https://www.chedong.com/phpMan.php/man/PERLNEWMOD/1/json",
    "generated": "2026-06-15T14:38:13Z",
    "sections": {
        "NAME": {
            "content": "perlnewmod - preparing a new module for distribution\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "This document gives you some suggestions about how to go about writing Perl modules,\npreparing them for distribution, and making them available via CPAN.\n\nOne of the things that makes Perl really powerful is the fact that Perl hackers tend to want\nto share the solutions to problems they've faced, so you and I don't have to battle with the\nsame problem again.\n\nThe main way they do this is by abstracting the solution into a Perl module. If you don't\nknow what one of these is, the rest of this document isn't going to be much use to you.\nYou're also missing out on an awful lot of useful code; consider having a look at perlmod,\nperlmodlib and perlmodinstall before coming back here.\n\nWhen you've found that there isn't a module available for what you're trying to do, and\nyou've had to write the code yourself, consider packaging up the solution into a module and\nuploading it to CPAN so that others can benefit.\n\nYou should also take a look at perlmodstyle for best practices in making a module.\n",
            "subsections": [
                {
                    "name": "Warning",
                    "content": "We're going to primarily concentrate on Perl-only modules here, rather than XS modules. XS\nmodules serve a rather different purpose, and you should consider different things before\ndistributing them - the popularity of the library you are gluing, the portability to other\noperating systems, and so on. However, the notes on preparing the Perl side of the module and\npackaging and distributing it will apply equally well to an XS module as a pure-Perl one.\n"
                },
                {
                    "name": "What should I make into a module?",
                    "content": "You should make a module out of any code that you think is going to be useful to others.\nAnything that's likely to fill a hole in the communal library and which someone else can slot\ndirectly into their program. Any part of your code which you can isolate and extract and plug\ninto something else is a likely candidate.\n\nLet's take an example. Suppose you're reading in data from a local format into a hash-of-\nhashes in Perl, turning that into a tree, walking the tree and then piping each node to an\nAcme Transmogrifier Server.\n\nNow, quite a few people have the Acme Transmogrifier, and you've had to write something to\ntalk the protocol from scratch - you'd almost certainly want to make that into a module. The\nlevel at which you pitch it is up to you: you might want protocol-level modules analogous to\nNet::SMTP which then talk to higher level modules analogous to Mail::Send. The choice is\nyours, but you do want to get a module out for that server protocol.\n\nNobody else on the planet is going to talk your local data format, so we can ignore that. But\nwhat about the thing in the middle? Building tree structures from Perl variables and then\ntraversing them is a nice, general problem, and if nobody's already written a module that\ndoes that, you might want to modularise that code too.\n\nSo hopefully you've now got a few ideas about what's good to modularise.  Let's now see how\nit's done.\n"
                },
                {
                    "name": "Step-by-step: Preparing the ground",
                    "content": "Before we even start scraping out the code, there are a few things we'll want to do in\nadvance.\n\nLook around\nDig into a bunch of modules to see how they're written. I'd suggest starting with\nText::Tabs, since it's in the standard library and is nice and simple, and then looking at\nsomething a little more complex like File::Copy.  For object oriented code, WWW::Mechanize\nor the \"Email::*\" modules provide some good examples.\n\nThese should give you an overall feel for how modules are laid out and written.\n\nCheck it's new\nThere are a lot of modules on CPAN, and it's easy to miss one that's similar to what\nyou're planning on contributing. Have a good plough through <http://metacpan.org> and make\nsure you're not the one reinventing the wheel!\n\nDiscuss the need\nYou might love it. You might feel that everyone else needs it. But there might not\nactually be any real demand for it out there. If you're unsure about the demand your\nmodule will have, consider asking the \"module-authors@perl.org\" mailing list (send an\nemail to \"module-authors-subscribe@perl.org\" to subscribe; see\n<https://lists.perl.org/list/module-authors.html> for more information and a link to the\narchives).\n\nChoose a name\nPerl modules included on CPAN have a naming hierarchy you should try to fit in with. See\nperlmodlib for more details on how this works, and browse around CPAN and the modules list\nto get a feel of it. At the very least, remember this: modules should be title\ncapitalised, (This::Thing) fit in with a category, and explain their purpose succinctly.\n\nCheck again\nWhile you're doing that, make really sure you haven't missed a module similar to the one\nyou're about to write.\n\nWhen you've got your name sorted out and you're sure that your module is wanted and not\ncurrently available, it's time to start coding.\n"
                },
                {
                    "name": "Step-by-step: Making the module",
                    "content": "Start with module-starter or h2xs\nThe module-starter utility is distributed as part of the Module::Starter CPAN package.  It\ncreates a directory with stubs of all the necessary files to start a new module, according\nto recent \"best practice\" for module development, and is invoked from the command line,\nthus:\n\nmodule-starter --module=Foo::Bar \\\n--author=\"Your Name\" --email=yourname@cpan.org\n\nIf you do not wish to install the Module::Starter package from CPAN, h2xs is an older\ntool, originally intended for the development of XS modules, which comes packaged with the\nPerl distribution.\n\nA typical invocation of h2xs for a pure Perl module is:\n\nh2xs -AX --skip-exporter --use-new-tests -n Foo::Bar\n\nThe \"-A\" omits the Autoloader code, \"-X\" omits XS elements, \"--skip-exporter\" omits the\nExporter code, \"--use-new-tests\" sets up a modern testing environment, and \"-n\" specifies\nthe name of the module.\n\nUse strict and warnings\nA module's code has to be warning and strict-clean, since you can't guarantee the\nconditions that it'll be used under. Besides, you wouldn't want to distribute code that\nwasn't warning or strict-clean anyway, right?\n\nUse Carp\nThe Carp module allows you to present your error messages from the caller's perspective;\nthis gives you a way to signal a problem with the caller and not your module. For\ninstance, if you say this:\n\nwarn \"No hostname given\";\n\nthe user will see something like this:\n\nNo hostname given at\n/usr/local/lib/perl5/siteperl/5.6.0/Net/Acme.pm line 123.\n\nwhich looks like your module is doing something wrong. Instead, you want to put the blame\non the user, and say this:\n\nNo hostname given at badcode, line 10.\n\nYou do this by using Carp and replacing your \"warn\"s with \"carp\"s. If you need to \"die\",\nsay \"croak\" instead. However, keep \"warn\" and \"die\" in place for your sanity checks -\nwhere it really is your module at fault.\n\nUse Exporter - wisely!\nExporter gives you a standard way of exporting symbols and subroutines from your module\ninto the caller's namespace. For instance, saying \"use Net::Acme qw(&frob)\" would import\nthe \"frob\" subroutine.\n\nThe package variable @EXPORT will determine which symbols will get exported when the\ncaller simply says \"use Net::Acme\" - you will hardly ever want to put anything in there.\n@EXPORTOK, on the other hand, specifies which symbols you're willing to export. If you do\nwant to export a bunch of symbols, use the %EXPORTTAGS and define a standard export set -\nlook at Exporter for more details.\n\nUse plain old documentation\nThe work isn't over until the paperwork is done, and you're going to need to put in some\ntime writing some documentation for your module.  \"module-starter\" or \"h2xs\" will provide\na stub for you to fill in; if you're not sure about the format, look at perlpod for an\nintroduction. Provide a good synopsis of how your module is used in code, a description,\nand then notes on the syntax and function of the individual subroutines or methods. Use\nPerl comments for developer notes and POD for end-user notes.\n\nWrite tests\nYou're encouraged to create self-tests for your module to ensure it's working as intended\non the myriad platforms Perl supports; if you upload your module to CPAN, a host of\ntesters will build your module and send you the results of the tests. Again,\n\"module-starter\" and \"h2xs\" provide a test framework which you can extend - you should do\nsomething more than just checking your module will compile.  Test::Simple and Test::More\nare good places to start when writing a test suite.\n\nWrite the README\nIf you're uploading to CPAN, the automated gremlins will extract the README file and place\nthat in your CPAN directory. It'll also appear in the main by-module and by-category\ndirectories if you make it onto the modules list. It's a good idea to put here what the\nmodule actually does in detail.\n\nWrite Changes\nAdd any user-visible changes since the last release to your Changes file.\n"
                },
                {
                    "name": "Step-by-step: Distributing your module",
                    "content": "Get a CPAN user ID\nEvery developer publishing modules on CPAN needs a CPAN ID.  Visit\n\"<http://pause.perl.org/>\", select \"Request PAUSE Account\", and wait for your request to\nbe approved by the PAUSE administrators.\n\n\"perl Makefile.PL; make test; make distcheck; make dist\"\nOnce again, \"module-starter\" or \"h2xs\" has done all the work for you.  They produce the\nstandard \"Makefile.PL\" you see when you download and install modules, and this produces a\nMakefile with a \"dist\" target.\n\nOnce you've ensured that your module passes its own tests - always a good thing to make\nsure - you can \"make distcheck\" to make sure everything looks OK, followed by \"make dist\",\nand the Makefile will hopefully produce you a nice tarball of your module, ready for\nupload.\n\nUpload the tarball\nThe email you got when you received your CPAN ID will tell you how to log in to PAUSE, the\nPerl Authors Upload SErver. From the menus there, you can upload your module to CPAN.\n\nAlternatively you can use the cpan-upload script, part of the CPAN::Uploader distribution\non CPAN.\n\nFix bugs!\nOnce you start accumulating users, they'll send you bug reports. If you're lucky, they'll\neven send you patches. Welcome to the joys of maintaining a software project...\n"
                }
            ]
        },
        "AUTHOR": {
            "content": "Simon Cozens, \"simon@cpan.org\"\n\nUpdated by Kirrily \"Skud\" Robert, \"skud@cpan.org\"\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "perlmod, perlmodlib, perlmodinstall, h2xs, strict, Carp, Exporter, perlpod, Test::Simple,\nTest::More ExtUtils::MakeMaker, Module::Build, Module::Starter <http://www.cpan.org/>, Ken\nWilliams' tutorial on building your own module at\n<http://mathforum.org/~ken/perlmodules.html>\n\n\n\nperl v5.34.0                                 2025-07-25                                PERLNEWMOD(1)",
            "subsections": []
        }
    },
    "summary": "perlnewmod - preparing a new module for distribution",
    "flags": [],
    "examples": [],
    "see_also": []
}