How to create and name module tarball for CPAN

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

Another simple newbie CPAN question:

What should I name my tarball for upload to CPAN?

I have chosen to give the package I am creating a home at Regexp::CharClasses::Thai on CPAN, so the final filename in that tree is simply "Thai.pm". However, obviously it needs to find its way past the first two levels in that tree...so I'm assuming that I should name it "Regexp-CharClasses-Thai.tar" (which contains the tarball made of the entire package and its associated files). Would this be a correct assumption? Alternatively, should it be compressed as well, i.e. "Regexp-CharClasses-Thai.tar.gz" OR "Regexp-CharClasses-Thai.tgz"?

Also, do I create the tarball to include the directories './Regexp/CharClasses/Thai/', or just the final directory (the one with the MakeFile.PL, etc., in this case /Thai/), or something else, e.g. no prior directories at all, just the one with the package files and subdirs?

Note that I have already checked, and found no specifics on how to name or structure the tarball (it's as if all the documentation assumes a root-level module) in any of these 'official' places:

I hate asking so many questions, but I'm rather stumped on this one and wishing the kind folk who have worked so hard on the documentation for how to create and submit modules to CPAN would have given some thought to the creation of the tarball once the module itself was prepared. (Or perhaps one of you might direct me to where this was done and has yet escaped my notice.)

One additional question that came up while reading the materials linked above: Can I just submit a link to CPAN and then host the module myself? If so, how would this be done?

Blessings,

~Polyglot~

Comment on How to create and name module tarball for CPAN Download Code

Replies are listed 'Best First'.
Re: How to create and name module tarball for CPAN by Corion (Patriarch) on Nov 27, 2023 at 19:06 UTC
If you are using ExtUtils::MakeMaker in your `Makefile.PL`, you can create the dist tarball by the following commands: `perl Makefile.PL make make dist` [download] For uploading to CPAN, I've automated that step through CPAN::Uploader or CPAN::Upload::Tiny (I don't remember which one).	[reply] [d/l] [select]
Re^2: How to create and name module tarball for CPAN by hippo (Archbishop) on Nov 28, 2023 at 09:35 UTC
`make dist` Absolutely this. However, it does require the author to have constructed the source tree and the Makefile.PL correctly in the first place and the OP doesn't entirely convince that this is the case. 🦛	[reply] [d/l]
Re^3: How to create and name module tarball for CPAN by Corion (Patriarch) on Nov 28, 2023 at 09:43 UTC
Ooh, indeed! This is another chance for me to plug my Dist-Template repository. I just copy the contents of the subfolder `template/` into the root of my distribution directory and then have `Makefile.PL` als my build tool for the distribution. Other starters are `h2xs`, Module::Starter, Dist::Inktly::Minty, but I've only used `h2xs` and then started copying old distribution skeletons into new distributions...	[reply] [d/l] [select]
Re^4: How to create and name module tarball for CPAN by SankoR (Prior) on Nov 28, 2023 at 13:16 UTC
Re^5: How to create and name module tarball for CPAN by Tux (Canon) on Nov 28, 2023 at 14:14 UTC
Some notes below your chosen depth have not been shown here
Re: How to create and name module tarball for CPAN by Bod (Parson) on Nov 27, 2023 at 23:00 UTC
There is an excellent tutorial available in Re: What do I use to release a module to CPAN for the first time? Without it, or similar, I would not have released any modules to CPAN. Note that Step 13 is not needed. Although if you follow it there will be no adverse effects.	[reply]
Re: How to create and name module tarball for CPAN by eyepopslikeamosquito (Archbishop) on Nov 28, 2023 at 01:12 UTC
What should I name my tarball for upload to CPAN? For basic CPAN module naming advice: pause: On the Naming of Modules (advice on choosing a good module name) 01modulesindex (shows the names of CPAN's 34152 modules distributions) For general advice to CPAN authors, you might like to scan the huge Writing Solid CPAN Modules for topics of interest. 👁️🍾👍🦟	[reply]
Re^2: How to create and name module tarball for CPAN by Polyglot (Chaplain) on Nov 28, 2023 at 03:06 UTC
Unless someone has meritorious reasons for choosing a different name than I have selected, that portion of my development is already decided in my mind. It was not without first consulting the monks here, and I have accepted their combined wisdom (with very slight rearrangement) in the end. See that thread, here: Namespace/advice for new CPAN modules for Thai & Lao Among those suggestions made earlier, consider: "Regexp::CharProps::Thai" and the one that I was at that time leaning toward based on the many suggestions: "Regexp::Thai::CharClasses." What I am now choosing is a compromise between these, i.e. "Regexp::CharClasses::Thai". Feel free to sound a final warning if this is a misguided idea, but be aware it is not without due consideration on my part, and I have found that "Regexp::CharClasses" already exists on CPAN, so adding "Thai" to this seems logical. https://metacpan.org/pod/Regexp::CharClasses My module does exactly what one would expect of a module so named--it adds Unicode property character classes for use with Perl regular expressions handling Thai script. With all of this in mind, my question was not about the naming of the module, but rather of its tarball. Even the additional links provided by others here for beginners like me have not been super clear on this point, so I'm still a bit foggy on how to do this. For example, should the tarball also have the version number for the module included in its name? If so, is there a standard format for this (hyphens, underscores, decimal points, etc.)? Perhaps I'm overthinking everything, and I just need to jump in and get my feet wet. Perhaps the corrections are all to be made after complaints roll in that "that's not how to do it!" I don't know. I just prefer to do it right the first time. Blessings, ~Polyglot~	[reply]
Re^3: How to create and name module tarball for CPAN by eyepopslikeamosquito (Archbishop) on Nov 28, 2023 at 04:02 UTC
... my question was not about the naming of the module, but rather of its tarball. Even the additional links provided by others here for beginners like me have not been super clear on this point ... I think ++Bod's link Re: What do I use to release a module to CPAN for the first time? by davido is clear on this point. For davido's example `Foo::Bar` module, point number 15 states: At this point you'll have a tarball that you can upload to CPAN, named something like `Foo-Bar-0.01.tar.gz` 👁️🍾👍🦟	[reply] [d/l] [select]
Re^3: How to create and name module tarball for CPAN by Polyglot (Chaplain) on Dec 01, 2023 at 10:20 UTC
Well, I jumped. We'll see how it lands. Blessings, ~Polyglot~	[reply]