What MakeMaker does with NAME is complicated, I don't entirely understand all
of it, but it is clearly attached to there being a real .pm file. It uses
NAME to make DISTNAME (the tarball name), FULLEXT (the directory to put
packlists and autoloader stuff) and some XS voodoo. It looks like Foo::Bar
means it will look for Bar.xs.
NAME should *probably* map to a real .pm file (ie. Foo::Bar maps to
Foo/Bar.pm)... but I haven't seen anything that makes that necessary. I
actually haven't seen anything which requires NAME even be a declared package.
Either way, I think the docs should say this about the NAME...
* NAME must be a valid package name
* NAME must have a matching a .pm file (Foo::Bar has Foo/Bar.pm)
* Many variables are derived from NAME such as
* DISTNAME
* FULLEXT
* The default XS file.
* NAME is required
Talk about a default should be removed, it's dangerous and I see how the
mention of "directory name" is confusing.
So... how about this:
------------------------
=item NAME
The main Perl package representing the distribution. For example,
C<Test::More> or C<ExtUtils::MakeMaker>. It will be used to derive
information about the distribution such as the L<DISTNAME>, installation
locations within the Perl library and where XS files will be looked for.
The C<NAME> should be a valid Perl module name and it should have an
associated C<.pm> file.
For example, C<Foo::Bar> is a valid C<NAME> and there should exist
F<Foo/Bar.pm>. Any XS code should be in F<Bar.xs>.
Your distribution B<must> have a C<NAME>.
--------------------------
On 2011.12.19 2:52 AM, Mark Overmeer via RT wrote:
Show quoted text> I spent a few hours to figure-out why my XS module wouldn't load with
> XSLoader, and then I discovered that it was caused by my confusion about
> the NAME field in ExtUtils::MakeMaker.
>
> The current description is:
>
> NAME
> Perl module name for this extension (DBD::Oracle). This will
> default to the directory name but should be explicitly defined
> in the Makefile.PL.
>
> This "module name" seems to be defined differently from CPAN
> terminology. What is meant here?
>
> 1 the base of the distribution name? If you put DBD-Oracle in the
> NAME field, you get exactly the same distribution tgz's
>
> 2 the name of the most prominent package provided by this
> distribution
>
> 3 the name of the most prominent module contained in this
> distribution
>
> (1) caused my problems: I accidentally put the '-' in, then XS gets
> compiled incorrectly.
Yes, that's right out. Various things split up the NAME on :: to derive more
variables. I don't think there's a package syntax check on the NAME.
Show quoted text> (2) would be my explanation, for me "module" is a file (pm) which
> has a platform dependent name, f.i. DBD/Oracle.pm CPAN looks into
> the files for package names to be put in 02packages.details.txt
>
> (3) was the strong suggestion of Zefram.
"package" is clearly defined as something defined with the package statement.
"module" is muddy and should probably be avoided. For example, I'm not sure
what is meant as the difference between #2 and #3.
Show quoted text> At the same time, I suggest to rewrite or remove the line about
> "default". Does it still work now modules get unpacked as
> ~/.cpan/build/PPI-1.215-2OaYDt/
I agree, ExtUtils::MM_Unix->guess_name won't guess correctly on that and it's
a silly feature anyway. It should just die full stop if there's no NAME.
