6

I just published my first perl program, unifdef+ (code::unifdefplus, v0.5.3), but I'm not sure if I've done it properly. The program is broken into two parts -- a script (script/unifdef+.pl), and a module (lib/unifdefplus.pm). The script is basically a wrapper for the module. This is supposed to act as a command line utility (which is in reality what I wanted to publish).

The README file I included documents the script, not the module. CPAN seems to be taking the version from the module rather than the script as well (which is undefined at the moment).

So, my questions is: if I want this to be indexed as a script rather than a module, do I need to do anything differently? Also, I'm taking it I should write some documentation for the module as well -- in which case I'm assuming it should be a README file in the lib directory?

Again, I apologize, but this is the first time I've done this, and I want to make sure I've done it right.

user2766918
  • 574
  • 4
  • 17
  • 2
    Check how other scripts do it, for example in the `App::` namespace. – choroba Feb 26 '17 at 16:34
  • 1
    Good examples are App::cpanminus, App::cpanminus::reporter or CPAN::Uploader. Don't publish anything that starts with a small letter in the first part of the namespace. Those are reserved for pragmas. – simbabque Feb 26 '17 at 16:58
  • Write all your documentation as POD in the source itself. Noone reads README files. – Borodin Feb 26 '17 at 18:08
  • 1
    Re "*CPAN seems to be taking the version from the module rather than the script as well*", With both MM and MB, you can specify which file to take the version from – ikegami Feb 26 '17 at 23:21
  • 1
    Re "*a module (lib/unifdefplus.pm)*", Don't put on CPAN modules with a root namesapce – ikegami Feb 26 '17 at 23:21
  • 1
    @ikegami has a very important point, and I've updated my answer with this information. All new CPAN authors should always read [On the naming of modules](https://pause.perl.org/pause/query?ACTION=pause_namingmodules). – stevieb Feb 27 '17 at 02:47
  • Sorry, the actual module is code::UnifdefPlus, which does start with a capital, but also has camel case (hope that's OK). I'm using a Build.PL to create the tarball, where the files are `script/unifdef+.pl`, `lib/UnifdefPlus.pm`, `Build.PL`, `README`, and some generated files. I'm not sure what MM or MB are? – user2766918 Feb 27 '17 at 23:20

1 Answers1

6

Right off the bat, please read On the naming of modules from the PAUSE admins. If you still have questions, or you're still unsure, reach out to modules <at> perl.org.

The simplest way is to use a name in the App:: namespace, such as App::MyMod.

Typically, I'd keep the script and module documentation within their separate files, but near the top of the module documentation, clearly link to the script's documentation, and state that most users will want to read that for normal use.

To build the README from the script documentation:

pod2readme bin/my_script

Likewise, if you change your mind and want README to reference the module instead:

pod2readme lib/App/MyMod.pm

Assuming you're using ExtUtils::MakeMaker for your builds, you can ensure that the script is installed by adding a directive:

EXE_FILES => [
    'bin/my_script'
],

With of course your script in the top-level bin directory of your distribution. Other build systems have similar directives.

stevieb
  • 9,065
  • 3
  • 26
  • 36
  • Ok, just to be clear, you're suggesting I move my module from code::UnifdefPlus to App::Unifdefplus. I'm using the perl `Module::Build` utility to generate the file. I'll see if it has an equivalent to MakeMaker's EXE_FILES option. – user2766918 Feb 28 '17 at 12:38
  • Yes, that's what I'm saying. – stevieb Feb 28 '17 at 13:04
  • Ok, thanks. I've moved it to App. There didn't seem to be an EXE_FILES equivalent in Module::Build, so I'm hoping that moving it to App is sufficient. Thanks for the help. – user2766918 Mar 01 '17 at 13:25