Re: How do I package a module and related apps for successful upload to cpan

[hippo]

a collection of modules that are for building applications that access the NOAA Global Climatology Network data repository. I've named these modules GHCN::Station, GHCN::StationTable etc.

Forgive me, but that seems to be a rather specific use case. Why is it that you think this deserves its own top-level namespace? Wouldn't these fit under WebService:: or somewhere like that? Did you discuss the name here first? On or PrePAN? Or on [e-mail]?

my .pl scripts, which I said reside under bin are listed as Documentation! Why?

Perhaps because scripts like this are usually placed in scripts/ as opposed to bin/?

To answer the question in the title, you should indeed split the dist into 2. People who want to use the webservice/protocol side of it won't necessarily want the application. So, distribute the webservice integration as one dist and the application as a second dist which has the first as a dependency.

While you're in there making such changes, it would be better to omit the dist.ini from the uploaded tarball(s).

Edit: Gah! PrePAN appears to have gone and been snaffled by a domain grabber. Another one bites the dust.

[PUCKERING]

Thanks for your insight. I hadn’t really thought through the implications of creating a new top level namespace. The thing is, we can upload pretty much any standalone module we want so long as the name is unique. And I picked a pretty unique name to contain my related modules. It didn’t occur to me the rules would be different for a namespace, though it makes sense that they are. I’ll try to find something suitable.

I’ll try /scripts. I had read that /scripts and /bin were supported in Dist:Zilla, it I don’t recall there being any clear distinction made and I was following other examples on cpan where /bin is used, like App::cpanminus.

I’ll omit dist.ini from the tarball. I thought I had done that, so thanks for the catch.

[hippo]

I’ll try /scripts. I had read that /scripts and /bin were supported in Dist:Zilla, it I don’t recall there being any clear distinction made and I was following other examples on cpan where /bin is used, like App::cpanminus.

If you take a look at how MetaCPAN treats the file in bin/ in App::cpanminus you will notice that it too is labelled as "Documentation". Arguably, it shouldn't be but if you put your scripts in scripts/ like HTML::Template then they evidently won't be considered as documentation. It's a very minor point, all told.

Edited for link typo (Thanks, pryrt)

[PUCKERING]

After some experimentation I discovered the key difference between putting scripts in /bin vs /scripts: the installer Dist::Zilla creates will install scripts it finds in /bin into the perl/site/bin directory, but it doesn't do that for /scripts. It also automatically generates .bat files for them on Windows. I haven't checked Unix, but it wouldn't surprise me if it generates files without the .pl extension and sets the executable permission on them.

This actually suits my use case. I built ghcn_fetch.pl to be general purpose (albeit for a very specific application) so anyone interested in climate data could use it find weather stations of interest and to retrieve daily or summarized data from NOAA GHCN and easily analyze that data in Excel or other tools. So, when I install Weather::GHCN I want it to install the ghcn_*.pl scripts in site/bin so I can execute them.

Is this not reasonable? Is there a better or more preferred way?

As a side note, the scripts are really just a thin wrapper that uses a like-named module (e.g. ghcn_fetch.pl uses Fetch.pl) and calls its run() sub, plus a lot of POD. I've currently put these app modules in App::GHCN. But now I'm wondering if that's the right approach.

My original vision was to have module GHCN and application scripts ghcn_fetch, ghcn_extremes and ghcn_station_counts all show up in CPAN when you search for GHCN. Now I'm thinking there are two ways to package this stuff:

Plan A

1. Weather-GHCN will be the package name, and it will contain lib Weather/GHCN and the .pm files for the GHCN modules.

2. The app modules Fetch.pm, Extremes.pm and StationCounts.pm could live there too, or maybe in an App subfolder (e.g. use Weather::GHCN::App::Fetch inside ghcn_fetch.pl)

3. The ghcn_*.pl scripts go in a /bin folder so they'll be installed in site/bin

The downside to this plan is that I don't think that ghcn_fetch et al will show up in cpan at all. The POD in the GHCN modules documents the API. The POD in ghcn_fetch documents the application and how one would use it. If someone is looking for a tool to extract and analyze climate data, I want them to find ghcn_fetch and read it's POD, not the POD for any of the GHCN modules. They only need that to build their own tool.

Plan B

1. same as Plan A

2. same as Plan A

3. The ghcn_*.pl scripts are each packaged separately: App::ghcn_fetch, App:ghcn_extremes, and App:ghcn_station_counts

The advantage to this plan is that the ghcn scripts will show up in a cpan search and, perhaps more importantly, the documentation will be picked up from the script and be a lot more meaningful than the POD for a GHCN class API. So, I'm leaning in this direction.

Your feedback on these plans, and other suggestions, would be much appreciated.

Thank you for your time on this matter. You've been a real help. I've been programming off and on in perl for years, am retired now, and it's become something of a hobby. I'm a neophyte when it comes to cpan though, and I'd like to start giving back to the community so I plan to put your help to good use.

- Gary

P.S. I considered using Weather::NOAA for GHCN, but when I tried emailing the owner of the modules in that namespace email failed. Apparently [e-mail] is no longer a valid email. I also downloaded the module Weather::NOAA:GFS, which is from 2004, and discovered that the servers it accesses do not respond to ping. The code is likely quite out of data. So, I didn't want my code coexisting with a couple of defunct modules in the ::NOAA subspace.

[eyepopslikeamosquito]

> I’ll try /scripts. I had read that /scripts and /bin were supported in Dist:Zilla ...

Note that davido, in Re: What do I use to release a module to CPAN for the first time?, strongly advises you to stay away from Dist::Zilla until you understand every step involved in doing it manually:

If you were using Dist::Zilla (which you shouldn't be using for your first module, or maybe even your first ten modules)...

Based on your experiences, davido's advice seems to be spot on. :)