use Some::Module; # searches for Some/Module.pm in @INC
[download]

Using namespaces "outside" of your distribution's main module's namespace is probably not a good idea, as it makes it difficult for other CPAN authors to check if that namespace is already taken.

update:

Should I even name the "helper" file with .pm at the end? All it holds are those routines that the main pm file uses. I will probably require the file in the module.

My answer is "it depends". Are the subroutines tightly coupled to your main module or are they more general utility functions that might be useful elsewhere? If the subroutines are valuable/reuseable in their own right, then it might make sense to release them either in a more logical namespace, or even in a separate distribution.

For example, consider Mail::Box. This comes in the distribution "Mail-Box", but the distribution contains modules Mail::Box and Mail::Message (and a host of others). Just because they're part of the same distribution doesn't mean they need to be in a hierarchical namespace if another namespace would make more sense.

As another example, in the course of writing a simulation module, I found myself needing a consistent random number user interface. Rather than creating them as "My::Sim::Random::Uniform", etc., I factored out the random number code into a standalone module, Math::Random::OO, and released it separately. My simulation code (not yet released), will just list that module as a prerequisite. That keeps both modules distinct and reusable by others in a more granular way than if they were one monolithic distribution

So, if your helper is just breaking up your code into more manageable chunks for you, then make it a module in a subdirectory of your distribution. If your module is tightly coupled to your code, but its purpose would be clearer with a separate name, then keep it in your distribution with a more directory structure. If your module implements distinct functionality on its own that your module needs, but that others might find themselves needing, too, then release it as a separate module and just include it as a prerequisite in your main module.

I've never been particularly keen on a lot of directories in the lib/ directory of my distributions. I know things like h2xs and other module tools want you to think that's a good idea, but I've found it much easier to just put everything in a flat directory.

lib/Module.pm
lib/Helper.pm
[download]

I can easily grep the sources and do other multi-file sorts of things, but more importantly for me, I get to see all of the files in one place. Other people have their preferences. If you do everything right, no one is ever going to know: they'll install the module and get rid of the distribution and be none the wiser. :)

I can install them wherever I like by telling MakeMaker where to put them. My Test::Data breaks out the functions into separate modules, although you get to them through Data.pm. You can use whatever you like for the keys and values of the PM argument to WriteMakefile().

WriteMakefile( #...
'PM' => {
    'lib/Data.pm'     => '$(INST_LIBDIR)/Data.pm',
    'lib/Scalar.pm'   => '$(INST_LIBDIR)/Data/Scalar.pm',
    'lib/Array.pm'    => '$(INST_LIBDIR)/Data/Array.pm',
    'lib/Hash.pm'     => '$(INST_LIBDIR)/Data/Hash.pm',
    'lib/Function.pm' => '$(INST_LIBDIR)/Data/Function.pm',
    },
#...
);
[download]

Beyond that, it doesn't really matter.

You don't use a filename with use(), and it's not just flat namespaces that have the problem.

The problem is a combination of the inner workings of %INC and @INC. If @INC has a relative path in it, and it finds the requested module in the current working directory, it loads it. That could be a name like ./Module.pm or nested path like ./Foo/Bar/Baz/Module.pm. Later in the script (or system like mod_perl), if we try the same thing from a different directory where there is the same relative path but to a different module, %INC thinks it already loaded it. It's the path that matters, not the module file name. %INC just stores the path name. A relative path can represent multiple files, but an absolute path points to one file.

This doesn't bite people with regular scripts because they don't have to worry about persistence. This bites people under mod_perl because a lot of scripts share %INC, and somebody may have already loaded a module. It only bites them if they use relative paths in @INC. If they don't do that, they should get what they expect. Modules like FindBin can help a script figure out where it is, although I prefer to simply install modules in known locations.

Still, this doesn't have anything to do with the layout of a distribution or what its files should be named, at least no more than it does in any other situation.

--
brian d foy <bdfoy@cpan.org>

Thanks for showing me the Light .. really appreciate the same :-)