How I Uploaded a CPAN Module

I have become a CPAN contributor!

I got a PAUSE ID in late June. 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. Honestly I guess it is better for future maintenance if you choose to use Object::Pad, 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/Object::Pad
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
        ├── 00-load.t
        └── 01-main.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 .

Also edit the Makefile.PL,MANIFEST and README.

Dependencies

In Makefile.PL...

GitHub Repository

In Makefile.PL...

Versions

$ perl -E 'use CPAN::Version; say CPAN::Version->vcmp("0.4.1" , "0.4");'
-1
$ perl -E 'use CPAN::Version; say CPAN::Version->vcmp("0.4.1" , "0.4.01");'
0

Packaging

$ 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

It seems that there are enough data for GNU make.

$ make dist

rm -rf Math-Cryptarithm-version
"/home/linuxbrew/.linuxbrew/Cellar/perl/5.34.0/bin/perl" "-MExtUtils::Manifest=manicopy,maniread" \
	-e "manicopy(maniread(),'Math-Cryptarithm-version', 'best');"
mkdir Math-Cryptarithm-version
mkdir Math-Cryptarithm-version/t
mkdir Math-Cryptarithm-version/lib
mkdir Math-Cryptarithm-version/lib/Math
Generating META.yml
Generating META.json
tar cvf Math-Cryptarithm-version.tar Math-Cryptarithm-version
Math-Cryptarithm-version/
Math-Cryptarithm-version/MANIFEST
Math-Cryptarithm-version/Changes
Math-Cryptarithm-version/README
Math-Cryptarithm-version/META.json
Math-Cryptarithm-version/t/
Math-Cryptarithm-version/t/01-main.t
Math-Cryptarithm-version/t/00-load.t
Math-Cryptarithm-version/META.yml
Math-Cryptarithm-version/lib/
Math-Cryptarithm-version/lib/Math/
Math-Cryptarithm-version/lib/Math/Cryptarithm.pm
Math-Cryptarithm-version/Makefile.PL
rm -rf Math-Cryptarithm-version
gzip --best Math-Cryptarithm-version.tar
Created Math-Cryptarithm-version.tar.gz

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

$ cd ~/test
$ tar -xzvf Math-Cryptarithm-version.tar.gz
$ cd Math-Cryptarithm-version
$ 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/00-load.t .. 1/1 # Testing Math::Cryptarithm version, Perl 5.034000, /home/linuxbrew/.linuxbrew/Cellar/perl/5.34.0/bin/perl
t/00-load.t .. ok   
t/01-main.t .. ok   
All tests successful.
Files=2, Tests=9,  2 wallclock secs ( 0.02 usr  0.00 sys +  1.98 cusr  0.02 csys =  2.02 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-version.tar.gz

has entered CPAN as

file: $CPAN/authors/id/C/CY/myPAUSEID/Math-Cryptarithm-version.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: XXX, XX Aug 2021 XXXXXXXX GMT Request completed: XXX, XX Aug 2021 XXXXXXXX GMT
Thanks,
--
paused, v1049"

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-version.tar.gz":

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

User: ...
Distribution file: Math-Cryptarithm-version.tar.gz
Number of files: 9
*.pm files: 1
README: Math-Cryptarithm-version/README
META-File: Math-Cryptarithm-v0.20.1/META.json
META-Parser: Parse::CPAN::Meta 1.4414
META-driven index: no
Timestamp of file: XXXXXXX 2021 UTC
Time of this run: XXXXXXX 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 .

Appendix: `use version`

use version; (Reference: Perl Best Practices by Damian Conway)

perl -Mversion -e 'print version->parse("0.02")->normal'

blah blah blah blah...# to be written

Where to go further?

the CPAN Testers

Dependency

To find some links

Update:
Follow the advice from Grinnz and use `make dist`. Thanks Grinnz.
Add a follow-up section. □

links: deprecated version of this post

Contact on twitter: @e7_87.

Discuss via GitHub issues: here.

Created Date: 14th August, 2021

Perl Ecosystem