PERLNEWMOD(1perl)

💖 NAME 💖

perlnewmod — bestie, this is your guide to prepping a brand-new Perl module for distribution 🎀 like, taking your cute lil code baby and releasing it into the wild of CPAN.

---

✨ DESCRIPTION ✨

okay so, this doc is basically me (your friendly neighborhood Unix bestie) giving you all the suggestions about how to write Perl modules, how to prep them for distribution, and how to make them available via CPAN. 🦋

Here's the tea: one of the things that makes Perl genuinely SO powerful is that Perl hackers love sharing solutions to problems they've already suffered through, so you and me don't have to battle the exact same problem all over again. 💅

The way they do that? They abstract the solution into a Perl module. Now — if you don't even know what a module is, fr fr, the rest of this document is not gonna be much use to you. Also you're lowkey missing out on a metric ton of useful code 😭 so go peek at perlmod, perlmodlib and perlmodinstall before you come back here. k thanks 💖

And when you've discovered there's no module out there for what you're trying to do, and you had to write the code yourself? That's your sign, bestie. Consider packaging that solution up into a module and uploading it to CPAN so everyone else can benefit. 🌈

You should also go look at perlmodstyle for best practices in making a module — it's giving "style guide but iconic".

🌸 Warning 🌸

We're gonna primarily concentrate on Perl-only modules here, not XS modules. XS modules serve a rather different purpose, and you should think about different things before distributing them — like the popularity of the library you're gluing, portability to other operating systems, and so on. 🙈

That said, the notes on preparing the Perl side of the module, plus packaging and distributing it, apply equally well to an XS module as to a pure-Perl one. so don't skip ahead thinking this isn't for you 💅

🎀 What should I make into a module? 🎀

Make a module out of any code you think is gonna be useful to others. Anything likely to fill a hole in the communal library, anything someone else can slot directly into their program — that's a candidate. And literally any part of your code you can isolate, extract and plug into something else? yeah. likely candidate. 👑

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. 😌 very main character.

Now — quite a few people have the Acme Transmogrifier, and you've had to write something to talk that protocol from scratch. bestie, 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. periodt.

Nobody else on the planet is gonna talk your local data format, so we can ignore that one. 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 wanna modularise that code too. 🌟

So hopefully you've now got a few ideas about what's good to modularise. Let's see how it's done. 💖

Step-by-step: Preparing the ground 🌱

Before we even start scraping out the code, there are a few things we wanna do in advance.

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 it's nice and simple, then looking at something a little more complex like File::Copy. For object oriented code, WWW::Mechanize or the "Email::*" modules provide some good examples.

These should give you an overall feel for how modules are laid out and written.

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 out here reinventing the wheel! 💀

Discuss the need 💬

You might love it. You might feel like 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 "module-authors@perl.org" mailing list (send an email to "module-authors-subscribe@perl.org" to subscribe; see <https://lists.perl.org/list/module-authors.html> for more information and a link to the archives).

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.

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.

When you've got your name sorted out and you're sure your module is wanted and not currently available, it's time to start coding. 🚀

Step-by-step: Making the module 🛠️

Start with module-starter or h2xs 🍼

The module-starter 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:

module-starter --module=Foo::Bar \
   --author="Your Name" --email=yourname@cpan.org

If you do not wish to install the Module::Starter package from CPAN, h2xs is an older tool, originally intended for the development of XS modules, which comes packaged with the Perl distribution.

A typical invocation of h2xs for a pure Perl module is:

h2xs -AX --skip-exporter --use-new-tests -n Foo::Bar

The -A omits the Autoloader code, -X omits XS elements, --skip-exporter omits the Exporter code, --use-new-tests sets up a modern testing environment, and -n specifies the name of the module. 💅

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 wanna distribute code that wasn't warning or strict-clean anyway, right? 😭 no cap.

Use Carp 🐟

The Carp module lets you present your error messages from the caller's perspective. It gives you a way to signal a problem with the caller and not your module. For instance, if you say this:

warn "No hostname given";

the user will see something like this:

No hostname given at
/usr/local/lib/perl5/site_perl/5.6.0/Net/Acme.pm line 123.

which looks like your module is doing something wrong. 😳 Instead, you want to put the blame on the user, and say this:

No hostname given at bad_code, line 10.

You do this by using Carp and replacing your "warn"s with "carp"s. If you need to "die", say "croak" instead. However, keep "warn" and "die" in place for your sanity checks — where it really is your module at fault.

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 use Net::Acme qw(&frob) would import the frob subroutine.

The package variable @EXPORT will determine which symbols get exported when the caller simply says use Net::Acme — you will hardly ever want to put anything in there. @EXPORT_OK, on the other hand, specifies which symbols you're willing to export. If you do wanna export a bunch of symbols, use the %EXPORT_TAGS and define a standard export set — look at Exporter for more details. 💖

Use plain old documentation 📝

The work isn't over until the paperwork is done, bestie, and you're gonna need to put in some time writing documentation for your module. "module-starter" or "h2xs" 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. 🎀

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 — and if you upload your module to CPAN, a whole host of testers will build your module and send you the results of the tests. Again, "module-starter" and "h2xs" 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. ✨

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 by-module and by-category directories if you make it onto the modules list. It's a good idea to put here what the module actually does in detail. 👑

Write Changes 🔄

Add any user-visible changes since the last release to your Changes file.

Step-by-step: Distributing your module 🚀

Get a CPAN user ID 🆔

Every developer publishing modules on CPAN needs a CPAN ID. Visit "<https://pause.perl.org/>", select "Request PAUSE Account", and wait for your request to be approved by the PAUSE administrators. (yes bestie we wait. patience is iconic.)

Make the tarball 🎁

Once again, "module-starter" or "h2xs" has done all the work for you. They produce the standard "Makefile.PL" you see when you download and install modules, and this produces a Makefile with a "dist" target.

perl Makefile.PL && make test && make distcheck && make dist

Once you've ensured that your module passes its own tests — always a good thing to make sure — you can "make distcheck" to make sure everything looks OK, followed by "make dist", and the Makefile will hopefully produce you a nice tarball of your module, ready for upload. 🦋

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.

Alternatively you can use the cpan-upload script, part of the CPAN::Uploader distribution on CPAN.

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... 💀😭

---

👑 AUTHOR 👑

Simon Cozens, "simon@cpan.org"

Updated by Kirrily "Skud" Robert, "skud@cpan.org"

✨ SEE ALSO ✨

okay bestie, you made it to the end, and now I'm legally obligated to hand you the whole friend group 😌 these are the pages and modules that ride shotgun with this one, so go be nosy:

• perlmod — the big-picture lore on how Perl modules actually work 🧠
• perlmodlib — where to find modules and how to write your own, the library lore
• perlmodinstall — how to install modules from CPAN, step by step
• h2xs — the classic tool that turns your header files into a module skeleton
• strict — turn it on. I'm serious. it's giving responsible.
• Carp — better warnings, like carp and croak 💅
• Exporter — the way you let other code borrow your symbols, iconic behaviour
• perlpod — the docs format, so your module actually has readable docs 📝
• Test::Simple — baby's first tests, perfect starting point
• Test::More — the upgrade, the full toolkit, obsessed
• ExtUtils::MakeMaker — the build-system mainstay for getting your module out the door
• Module::Build — the other build option, build your module with Perl itself
• Module::Starter — scaffolds a whole new module so you don't hand-make every file 🎀

and the mothership: <https://www.cpan.org/> 🌈

---

and that's the whole page, bestie!! you now know how to make a module, doc it, test it and ship it to CPAN. go be somebody's favourite dependency 💖

this little tour came to you from perl v5.44.0, dated 2026-10-17, and the page itself is PERLNEWMOD(1perl). slay, stay safe, and remember: strict and warnings are not optional, they're a lifestyle ✨🦋