Beefy Boxes and Bandwidth Generously Provided by pair Networks
There's more than one way to do things
 
PerlMonks  

Trying to build a module for upload to CPAN

by talexb (Chancellor)
on Oct 29, 2021 at 02:40 UTC ( #11138164=perlquestion: print w/replies, xml ) Need Help??

talexb has asked for the wisdom of the Perl Monks concerning the following question:

I just did a presentation at the Toronto Perlmongers monthly meeting about my new module CSVDB, which lets a user access a CSV using SQL commands. This is a version 0.01 module, so needs lots of work to get ready to be usable, but I've been putting off uploading stuff to CPAN for about twenty years and decided I'd better do it before another twenty years go by.

I used Andy Lester's module-starter to get started about two weeks ago, but that module doesn't have anything about packaging up my code, so I went looking and eventually found a link to Minilla. I installed that, fixed a few things, but eventually wound up confused, because minil release was asking me about the next version (??) so I suggested 0.02 .. and got this error

... xt/minilla/cpan_meta.t ........ ok xt/minilla/minimum_version.t .. 1/13 # Failed test 'Build.PL' # at /usr/local/share/perl/5.30.0/Test/MinimumVersion/Fast.pm line 1 +01. # Build.PL requires 5.008_001 due to explicit requirement # Looks like you failed 1 test of 13.
Looking in Build.PL, I see that this is an autogenerated file, and shouldn't be touched. So that appears to be a dead end.

OK .. what else can I find? Ah, mbtiny looks like it will do the job, so I installed App::ModuleBuildTiny and run the command to build a distribution.

tab@music4: (main) $ mbtiny dist Changes appears to be empty tab@music4: (main) $ wc -l Changes 5 Changes
It appears to be complaining about an empty file that is .. not empty.

I don't understand why minil wants to know about the *next* version .. I just want to package up the *existing* version. I don't understand why mbtiny thinks a non-empty file is empty, and why that means it won't build a release.

I still have work to do -- my MANIFEST file needs updating, so I'm going to do that, then I'll probably just download one of the tarballs from CPAN and take it apart to see what's going on. I'll make this happen.

Suggestions about what the heck's going on will be gratefully received.

Alex / talexb / Toronto

Thanks PJ. We owe you so much. Groklaw -- RIP -- 2003 to 2013.

Replies are listed 'Best First'.
Re: Trying to build a module for upload to CPAN
by kcott (Bishop) on Oct 29, 2021 at 06:54 UTC

    G'day Alex,

    I use Module::Starter with Module::Starter::PBP as a plugin. I use that plugin mainly because I like the templates which I customise a lot (I also pull out the PBP specific parts, e.g. perlcritic.t).

    I keep a number of config files for various purposes; e.g. OO mod, functional mod, $work mod, etc. Each of these points to a different directory with my customised templates. Here's the current one:

    $ cat ~/.module-starter/config author: Ken Cotterill email: kcott@cpan.org builder: ExtUtils::MakeMaker plugins: Module::Starter::PBP template_dir: /home/ken/.module-starter/P532 $ ls -al ~/.module-starter/P532 total 24 drwxr-xr-x+ 1 ken None 0 Jan 9 2021 . drwxr-xr-x+ 1 ken None 0 Jan 6 2021 .. -rw-r--r-- 1 ken None 89 Jan 5 2021 Changes -rw-r--r-- 1 ken None 586 Jan 5 2021 Makefile.PL -rw-r--r-- 1 ken None 82 Jan 9 2021 MANIFEST.SKIP -rw-r--r-- 1 ken None 5205 Jan 5 2021 Module.pm -rw-r--r-- 1 ken None 313 Dec 19 2020 README drwxr-xr-x+ 1 ken None 0 Jan 9 2021 t

    And, just to give you an idea of the templates, Module.pm has:

    package <MODULE NAME>; ... =head1 LICENCE AND COPYRIGHT Copyright (c) <YEAR>, <AUTHOR> C<< <<EMAIL>> >>. All rights reserved. ...

    Creating the module is a little easier with this plugin because you don't need to specify so many options (e.g. the --author="Andy Lester" --email=andy@petdance.com, or equivalent, are not required).

    Creating the distribution uses the fairly standard incantation:

    perl Makefile.PL make make test make dist

    That last command creates the distribution tarball.

    I'd generally want to also run Author Tests so something like this first (your environment variable may have a different name):

    $ export RELEASE_TESTING=1

    I've used this method dozens (if not hundreds) of times and not encountered problems: it seems robust and stable.

    — Ken

Re: Trying to build a module for upload to CPAN
by hippo (Bishop) on Oct 29, 2021 at 09:01 UTC
    Suggestions about what the heck's going on will be gratefully received.

    I concur with kcott and Discipulus. For your first release to CPAN don't even think about using one of the release automation tools like Minilla or Dist::Zilla, etc. They are fine for people who do a lot of releases and already fully understand the procedure but for a first-timer they will be confusing at best.

    Follow the guides such as How to make a CPAN Module Distribution and just use the simple, basic tools many of which are in Core. Once you have a tarball ready for upload to CPAN, I strongly suggest that you copy it to a fresh machine and try to upack it and install your module there first. This can catch any number of problems before you upload it to CPAN.

    Thanks for considering releasing your code and good luck with the release.


    🦛

      I actually used Dist::Zilla for my very first module (in 2013, when Dist::Zilla was already fairly refined) and I remember there being a learning curve, but I was having just as much learning curve trying to figure out the other tools. In the end I went with Dist::Zilla because I hate having package boilerplate hanging around in my git repository, and because I can't ever remember to do all the manual steps during a release like updating all the version numbers in each module and updating the Manifest and tagging in git, etc.

        You, sir, are a trooper and I take my hat off to you.

        I, along with some other denizens of these halls, participated in the Pull Request Challenge a few years back and when it so happened that the module I was assigned required Dist::Zilla my heart would sink. Such an overblown, unnecessary framework - complex and heavy in equal measure - which for a single run-and-release gives back very little. I can fully understand why folks like RJBS and perlancar would use it but it is not for me.

        because I can't ever remember to do all the manual steps during a release like updating all the version numbers in each module and updating the Manifest and tagging in git, etc.

        I wrote a script which does that for me. It is entirely unnecessary for anyone else to have that script or know that it exists. This means that they can collaborate with me on my modules in GitLab (or elsewhere) without having to use either my script or Dist::Zilla or anything else. It is no barrier to participation.


        🦛

      Thanks for pointing out the link to the guide -- I originally skipped it, as one of the references said, Oh that uses h2xs, that's ancient. After looking at the guide a little more closely this morning, it looks like it has everything I need to more or less do the needful. I appreciate your feedback, and I'll try this out tonight after work. :)

      Alex / talexb / Toronto

      Thanks PJ. We owe you so much. Groklaw -- RIP -- 2003 to 2013.

        I still use h2xs for pure Perl modules - think I probably need to update that. Is this still state of the art for XS starters?

        I also noted in Minilla, assumes among other things:

        > Your modules are written in Pure Perl and are located in lib/.

Re: Trying to build a module for upload to CPAN
by Discipulus (Abbot) on Oct 29, 2021 at 07:00 UTC
    Hello talexb,

    > but that module doesn't have anything about packaging up my code..

    as side comment you dont need an external tool to just pack the module: perl Makefile.PL then make dist will do the job. See the relevant part of my little guide

    L*

    There are no rules, there are no thumbs..
    Reinvent the wheel, then learn The Wheel; may be one day you reinvent one of THE WHEELS.
Re: Trying to build a module for upload to CPAN
by syphilis (Archbishop) on Oct 29, 2021 at 12:47 UTC
    I used Andy Lester's module-starter to get started about two weeks ago

    All I've ever done is to create a "Changes", a "README", a "Makefie.PL", a "Module.pm", (optionally) a "Module.pod", a "Module.xs" (if applicable) some t/*.t files and a MANIFEST (that lists all of the files that exist).
    The run perl Makefile.PL, followed by make dist ... then upload the tar.gz file that make dist created to cpan.
    Still works fine for me.

    Cheers,
    Rob
Re: Trying to build a module for upload to CPAN
by kikuchiyo (Friar) on Oct 29, 2021 at 08:29 UTC
    How is this new module different from DBD::CSV?

      The DBD::CSV module presumably lets you access a CSV file using the DBI module. I wanted to use a tool that's more command line oriented. And then I decided, I'm not going to go look for it, I'll just build it.

      Alex / talexb / Toronto

      Thanks PJ. We owe you so much. Groklaw -- RIP -- 2003 to 2013.

Re: Trying to build a module for upload to CPAN
by Anonymous Monk on Oct 29, 2021 at 03:08 UTC
    I just want to package up the *existing* version.
    That's what it's doing. Your next stable version in this case would be 0.01.

    Without a link to your repo, best guess is you also have a minimum version set in code or your cpanfile.
        Your next stable version in this case would be 0.01.

      Ugh .. so what minil is asking is "What version are we building today? (As in, what's the next version that's going to get uploaded to CPAN?)" At the end of a long day, this is not the kind of mental gymnastics I am able to comprehend.

      OK -- thanks for that. I entered 0.01 this time, and looked fine until .. it failed in exactly the same way. My repo is here: https://github.com/talexb/CSVDB.

      Alex / talexb / Toronto

      Thanks PJ. We owe you so much. Groklaw -- RIP -- 2003 to 2013.

        Well, on my system, this is the test results:
        t/20-cmdline.t (Wstat: 11520 Tests: 50 Failed: 45) Failed tests: 2-10, 12-20, 22-30, 32-40, 42-50 Non-zero exit status: 45 t/21-cmdline.t (Wstat: 4608 Tests: 20 Failed: 18) Failed tests: 2-10, 12-20 Non-zero exit status: 18 t/22-cmdline.t (Wstat: 17664 Tests: 77 Failed: 69) Failed tests: 2-5, 7-12, 14, 16-21, 23-32, 34-45, 47-60 62-77 Non-zero exit status: 69 xt/boilerplate.t (Wstat: 0 Tests: 3 Failed: 0) TODO passed: 1, 3 xt/minilla/spelling.t (Wstat: 256 Tests: 1 Failed: 1) Failed test: 1 Non-zero exit status: 1
        You're still missing a LICENSE file but your cpanfile should look like this:
        requires 'perl' => 5.8.1; requires 'Text::CSV' => 0;
        Minilla comes with the functionality to create new dists with minil new [project here]. It'll lay everything out including your cpanfile, LICENSE, minil.toml etc.
Re: Trying to build a module for upload to CPAN
by Bod (Curate) on Oct 29, 2021 at 21:45 UTC
Re: Trying to build a module for upload to CPAN
by Fletch (Bishop) on Oct 29, 2021 at 05:51 UTC

    Not helpful WRT your problem, but you might check out q (https://harelba.github.io/q/) which is a python (and pandas?) thing which does something similar for features to steal inspiration. Have had some people intermittently use it at $work.

    The cake is a lie.
    The cake is a lie.
    The cake is a lie.

      OT^2: The link you provided also contains this interesting reading: Basics of the Unix Philosophy (write programs to write programs when you can., When in doubt, use brute force. etc.)

Re: Trying to build a module for upload to CPAN
by NERDVANA (Pilgrim) on Oct 29, 2021 at 08:37 UTC
    Iíll suggest Dist::Zilla since nobody else did yet. At first look, it seems very heavyweight (based on Moose with lots of plugins) but those plugins are what let Dist::Zilla adapt to your preferred workflow for publishing a module.

    I like to use #VERSION comments in my files that get replaced by whatever version is being built, default to the next version based on the last git tag, have Git be responsible for the MANIFEST, move all my POD to the __END__ of the file, automatically determine my prereqs but let me override them, and test my code for documentation coverage. You can see a minimal configuration for all of that in my module Log::Progress / dist.ini

    Once everything is installed, my release process is "dzil test" then "dzil release", it prompts me for my PAUSE password, then it's published. Releasing a dev version is "V=1.11_01 dzil release" then later "V=1.12 dzil release" to get back to 2 decimal places.

      Thanks for the suggestion .. I saw that was one of the alternatives, but I also read the warnings that it was a bit of a battleship, and decided that there must be something a little more lightweight for my tiny module that has one dependency.

      Alex / talexb / Toronto

      Thanks PJ. We owe you so much. Groklaw -- RIP -- 2003 to 2013.

      I agree here. It's really a guilty pleasure because it's so massive, but you only need to install it on your dev machine.

        But you raise the bar for anyone willing to come up with a patch.

        I've seen not a single project using Dist::Zilla that does not requires (many) additional modules and plugins that won't be used for anything else and thus clutter *my* development box if I want to not only fix something, but also test it before I submit a PR.

        Whereever possible, I will stick to ExtUtils::MakeMaker and it has so far never let me down.

        And for all those that add scripts: add them to a folder (e.g. sandbox) in your git repo, so people trying to help you have them too. And document them in Makefile.PL or README.

        My Ä0.02

        Also read Release::Checklist for motivations.


        Enjoy, Have FUN! H.Merijn

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: perlquestion [id://11138164]
Front-paged by Corion
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others drinking their drinks and smoking their pipes about the Monastery: (1)
As of 2022-05-22 09:55 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    Do you prefer to work remotely?



    Results (80 votes). Check out past polls.

    Notices?