Structure of complex distributions

[kj]

I am working on a pretty complex distribution, and I could use some
advice on how to structure its directories.

This distribution contains several modules, not all under the same
directory (i.e. A.pm, B.pm, A/X.pm, B/Y.pm, etc.).

Moreover, some of these modules are Perl extensions, so there's a
whole bunch of *.xs, *.c, *.h, and typemaps files associated with
them [1].

In addition, the distribution includes several scripts.

Some of these scripts are part of the distribution proper.

Other scripts are code-generating *.pl.PL scripts. The resulting
*.pl scripts are part of what is ultimately installed.

The remaining scripts (e.g. Configure.pl, and test scripts) are
run during installation.

The distribution also includes separate *.pod and *.html documentation
files.

Lastly, this distribution includes several LARGE data files (they
account for 95% of the installed distribution's footprint).

What directory structure would you use for such a distribution? Is
there anything like a consensus on what types of files go where?

I look forward to reading your thoughts on this. Thanks.

kj

[1] I have seen many cases in which, e.g., Foo.xs file is placed
at the top of the distro, while the corresponding Foo.pm (which
defines the package Bar::Baz::Foo) is placed either in $TOP_OF_DISTRO
or in $TOP_OF_DISTRO/lib/Bar/Baz. I get the impression that there
is something against putting Foo.xs in $TOP_OF_DISTRO/lib/Bar/Baz.
Is this the case, and why? The cases in which Foo.pm is put in
$TOP_OF_DISTRO, right alongside Foo.xs, and not in
$TOP_OF_DISTRO/lib/Bar/Baz also puzzle me.

 

[Ben Morrow]

I am working on a pretty complex distribution, and I could use some
advice on how to structure its directories.

This depends on what you are using to install the distro. For something
this complicated, I would recommend Module::Build, which prefers you to
put things under lib/:

lib/A.pm
lib/A/X.pm
lib/A/X.xs

etc.

Other scripts are code-generating *.pl.PL scripts. The resulting
*.pl scripts are part of what is ultimately installed.

If you tell Module::Build about these it will run them and install the
results for you.

[1] I have seen many cases in which, e.g., Foo.xs file is placed
at the top of the distro, while the corresponding Foo.pm (which
defines the package Bar::Baz::Foo) is placed either in $TOP_OF_DISTRO
or in $TOP_OF_DISTRO/lib/Bar/Baz. I get the impression that there
is something against putting Foo.xs in $TOP_OF_DISTRO/lib/Bar/Baz.
Is this the case, and why? The cases in which Foo.pm is put in
$TOP_OF_DISTRO, right alongside Foo.xs, and not in
$TOP_OF_DISTRO/lib/Bar/Baz also puzzle me.

This is because ExtUtils::MakeMaker (the traditional install mechanism)
doesn't properly support the lib/Bar/Baz structure, and wants all the xs
files at the top-level.

Ben