directory structure of cpan module

Question

I am working on perl module that I would like to submit in CPAN. But I have a small query in regards to the directory structure of module.

As per the perlmonk article the module code directory structure should be as below:

    Foo-Bar-0.01/Bar.pm
    Foo-Bar-0.01/Makefile.PL
    Foo-Bar-0.01/MANIFEST
    Foo-Bar-0.01/Changes
    Foo-Bar-0.01/test.pl
    Foo-Bar-0.01/README

But when I am using the command, the structure is generated as below

    h2xs -AX Foo::Bar

    Writing Foo-Bar/lib/Foo/Bar.pm
    Writing Foo-Bar/Makefile.PL
    Writing Foo-Bar/README0
    Writing Foo-Bar/t/Foo-Bar.t
    Writing Foo-Bar/Changes
    Writing Foo-Bar/MANIFEST

Answer 1

The article in question is advocating a considerably-older module structure. It certainly could be used, but it loses a lot of the advancements that have been put into place as far as good testing, building, and distribution practices.

To break down the differences:

• modules have moved from the top level to the lib/ directory. This unifies the location where your module "lives" (i.e., the place where you work on the code and create the baseline modules to be tested and eventually distributed). It also makes it easier to set up any hierarchy that you need (e.g. subclasses, or helper modules); the newer setup will just pick these up. The older one may but I'm not familiar enough with it to say yes or no.
• Makefile.PL in the newer setup will, when "make" is run. create a library called "blib", the *b*uild *lib*rary - this is where the code is built for actual testing. It will pretty much be a copy of lib/ unless you have XS code, in which case this is where the compiled XS code ends up. This makes the process of building and testing the code simpler; if you update a file in lib/, the Makefile will rebuild the file into blib before trying to test it.
• the t/ directory replaces test.pl; "make test" will execute all the *.t files in t/, as opposed to you having to put all your tests in test.pl. This makes it far easier to write tests, as you can be sure you have a consistent state at the beginning of each test.
• MANIFEST and Changes are the same in both: MANIFEST (built by "make manifest") is used to determine which files in the build library should be redistributed when the module is packaged for upload, and used to verify that a package is complete when it's downloaded and unpacked for building. Changes is simply a changelog, which you edit by hand to record the changes made in each distributed version.

As recommended in the comments on your question, using Module::Starter or Dist::Zilla (be warned that Dist::Zilla is Moose-based and will install a lot of prereqs) is a better approach to building modules in a more modern way. Of the two, the h2xs version is closer to modern packaging standards, but you're really better off using one of the recommended package starter options (and probably Module::Build, which uses a Build Perl script instead of a Makefile to build the code).