«

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.
--
NOTE: In my address everything before the period is backwards.

Quoth kj <>:
>
> 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

--
"The Earth is degenerating these days. Bribery and corruption abound.
Children no longer mind their parents, every man wants to write a book,
and it is evident that the end of the world is fast approaching."
-Assyrian stone tablet, c.2800 BC