How I Uploaded a CPAN Module

An updated but yet to be completed version is here.

So, accumulating effort from Wednesday, today(Friday) I become a CPAN contributor!

I got a PAUSE ID 2 weeks ago. If you are also interested in the Perl ecosystem, you may consider to apply for a PAUSE ID as well.

In this blogpost, I mainly follow the instructions here:

How to make a CPAN Module Distribution, by tachyon, PerlMonks, Apr 14, 2002.

Some contents of the PerlMonks article are largely repeated here.

This piece of PerlMonks article is already 19-year-old, but it is still valid. One of the good things of the article is that you need not install new modules or programs if you are on a *nix system.

Prerequisites

One should have some knowledge on modules, packages and, not really necessary, object-oriented Perl ("Perl OO" in short).

Note that the Perl OO I have used in my first product is the "bless" Perl OO system, neither Moo nor Moose. Honestly I guess it is better for future maintenance if you choose to use Moo or other modern Perl OO system.

One should know how to write POD.

One should know how to use some of the Test::XXXX suite.

If you have never heard of any one of key terms above...

https://metacpan.org/pod/Moo
https://metacpan.org/pod/Moose
https://perldoc.perl.org/perlpod
Basic Testing Tutorial by hippo, PerlMonks, Sep 11, 2019

Getting Started

I had focused on typing/coding up three files:

a_perl_script_with_the_to-be_released_package.pl
a_perl_script_for_testing.pl
contents_I_would_like_to_see_on_the_description_page_of_the_module_on_metacpan.txt

For assistancy, I wrote a Perl script which did more time-consuming requests or for seeing the output of methods as well. Data::Dumper was a great help.

After finishing up (1) and (2), I re-organized the codes in (1) and (2) into

Cryptarithm.pm
test.pl

And I converted the format of (3) into POD format, and checked the content. A helper was Pod::Html.

  use Pod::Html qw/pod2html/;

  pod2html("",
         "--infile=./page.pod",
         "--outfile=./podpage.html");

Preparing to be seen by the World

Almostly exactly follow the instructions on the PerlMonks article by tachyon:

I moved to a directory "~/build". Then

$ h2xs -AX Math::Cryptarithm

After some trivial editing, renaming and directory operations, the structure of the "~/build" directory became

$ tree
.
└── Math-Cryptarithm
    ├── Changes
    ├── lib
    │   └── Math
    │       └── Cryptarithm.pm
    ├── Makefile.PL
    ├── MANIFEST
    ├── README
    └── t
        └── test.t

I had mainly edited Cryptarithm.pm, put the content of (1) onto it (update the version number!), and then put the POD-formatted content of (3) after __END__ in Cryptarithm.pm .

Packaging

Almostly exactly follow the instructions on the PerlMonks article by tachyon:

$ tar -czf Math-Cryptarithm-0.02.tar.gz Math-Cryptarithm-0.02
$ # This is a bad practice. See the comment by Grinnz at the bottom of this page

Then I copied the Math-Cryptarithm-0.02.tar.gz to "~/test" directory via Linux Desktop Environment. Back to the shell:

$ cd ~/test
$ tar -xzvf Math-Cryptarithm-0.02.tar.gz
$ cd Math-Cryptarithm-0.02
$ perl Makefile.PL
Checking if your kit is complete...
Looks good
Generating a Unix-style Makefile
Writing Makefile for Math::Cryptarithm
Writing MYMETA.yml and MYMETA.json
$ make
cp lib/Math/Cryptarithm.pm blib/lib/Math/Cryptarithm.pm
Manifying 1 pod document
$ make test
PERL_DL_NONLAZY=1 "/home/linuxbrew/.linuxbrew/Cellar/perl/5.34.0/bin/perl" "-MExtUtils::Command::MM" "-MTest::Harness" "-e" "undef *Test::Harness::Switches; test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
t/test.t .. ok     
All tests successful.
Files=1, Tests=10, 34 wallclock secs ( 0.00 usr  0.02 sys + 34.47 cusr  0.00 csys = 34.49 CPU)
Result: PASS
$ sudo make install
[sudo] password for user_name:
Manifying 1 pod document
Installing /home/user_name/perl5/lib/perl5/Math/Cryptarithm.pm
Installing /home/user_name/perl5/man/man3/Math::Cryptarithm.3
Appending installation info to /home/user_name/perl5/lib/perl5/x86_64-linux-thread-multi/perllocal.pod

It seemed all ok.

Interaction with PAUSE

I uploaded the .tar.gz file via https://pause.perl.org/ . Soon I got an email

"The uploaded file

Math-Cryptarithm-0.02.tar.gz

has entered CPAN as

file: $CPAN/authors/id/C/CY/myPAUSEID/Math-Cryptarithm-0.02.tar.gz
size: XX bytes
md5: XX
sha1: XX

CPAN Testers will start reporting results in an hour or so:

http://matrix.cpantesters.org/?dist=Math-Cryptarithm

Request entered by: myPAUSEID (my name)
Request entered on: Fri, 09 Jul 2021 08:09:53 GMT
Request completed: Fri, 09 Jul 2021 08:10:59 GMT

Thanks,
--
paused, v1049"

Passing the CPAN Testers is NOT necessary for the module to appear on CPAN.

Within three minutes after receiving the above email from PAUSE, I got another email from them, with the title "PAUSE indexer report myPAUSEID/Math-Cryptarithm-0.02.tar.gz":

"The following report has been written by the PAUSE namespace indexer.
...

User: ...
Distribution file: Math-Cryptarithm-0.02.tar.gz
Number of files: 6
*.pm files: 1
README: Math-Cryptarithm-0.02/README
META-File: No META.yml or META.json found
META-Parser: Parse::CPAN::Meta 1.4414
META-driven index: no
Timestamp of file: Fri Jul 9 08:10:58 2021 UTC
Time of this run: Fri Jul 9 08:12:30 2021 UTC

Status of this distro: OK
=========================

The following packages (grouped by status) have been found in the distro:

Status: Successfully indexed
============================
...
"

And I could see my module in https://metacpan.org/recent . □

[Update: 10th July, 2021 07:20 (HKT)]
Feedback from the posting on blogs.perl.org [here]:

Grinnz:

Do not use tar to create tarballs for CPAN. Always use `make dist` or `./Build dist` or the release building mechanism of your author tool. This creates the correct metadata.

Contact on twitter: @e7_87.

Created Date: 9th July, 2021; Last Update: 04th February, 2022

Perl Ecosystem