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.
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...
- Basic Testing Tutorial by hippo, PerlMonks, Sep 11, 2019
I had focused on typing/coding up three files:
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
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.
GitHub RepositoryIn Makefile.PL...
$ 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
Checking if your kit is complete... Looks good Generating a Unix-style Makefile Writing Makefile for Math::Cryptarithm Writing MYMETA.yml and MYMETA.json
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
$ 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
has entered CPAN as
size: XX bytes
CPAN Testers will start reporting results in an hour or so:
Request entered by: myPAUSEID (my name)
Request entered on: XXX, XX Aug 2021 XXXXXXXX GMT Request completed: XXX, XX Aug 2021 XXXXXXXX GMT
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.
Distribution file: Math-Cryptarithm-version.tar.gz
Number of files: 9
*.pm files: 1
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 versionuse 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?
To find some links
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