Beefy Boxes and Bandwidth Generously Provided by pair Networks
more useful options

Where to put the bits and pieces - Installing a complex CPAN dist

by Hercynium (Hermit)
on Sep 18, 2008 at 20:50 UTC ( #712383=perlquestion: print w/replies, xml ) Need Help??
Hercynium has asked for the wisdom of the Perl Monks concerning the following question:

I'm working on re-doing the Module::Build scripts for a fairly complex set of perl modules, scripts and supporting config files, demo scripts, and documentation (more than just POD and HTML). Heck, I've even got some compiled C to throw into the mix!

Installing the modules themselves is easy, along with the POD and utility scripts. However, there's a lot of other pieces that don't really fit in any of the typical categories and I'm not sure where I should put them. I've searched high and low for the "correct" answer but I just can't find one that satifies my need for "getting it right".

So, there's the typical info in the Debian Perl Policy and Perl5 Wiki's Hints for Distributors but none of that seems to cover all the extras I've got here.

If I try to categorize everything in this distro in a similar way to MB and EUMM, I would break it down like this:
  • lib        modules
  • script     utility scripts
  • bin        compiled utility program (optional)
  • bindoc     man pages and pod for stuff in script and bin
  • libdoc     man pages and pod for stuff in lib
  • conf       config files used by the stuff in script and bin
  • demo       scripts that show what this distro can do (optional)
  • demo_conf  configuration files used by the demo scripts (optional)
  • share      docs and readme files and other such things (optional)

Given the above list of installable elements, and the rules set out in various docs... I'm trying to figure out what the proper places to install the non-standard stuff (conf, demo, demo_conf, share) would be - for both distro-packaged and CPAN installations. I'm thinking I should do it like like this:
  • lib        $Config{installvendorlib}
  • script     $Config{installvendorbin}
  • bin        $Config{installvendorbin}
  • bindoc     $Config{installvendorman1dir}
  • libdoc     $Config{installvendorman3dir}
  • conf       File::Spec->catfile( '/etc', $distname )
  • demo       File::Spec->catfile( $Config{vendorprefixexp}, 'share', $distname', 'demo' )
  • demo_conf  File::Spec->catfile( $Config{vendorprefixexp}, 'share', $distname', 'demo', 'conf' )
  • share      File::Spec->catfile( $Config{vendorprefixexp}, 'share', $distname' )
  • lib        $Config{installsitelib}
  • script     $Config{installsitebin}
  • bin        $Config{installsitebin}
  • bindoc     $Config{installsiteman1dir}
  • libdoc     $Config{installsiteman3dir}
  • conf       File::Spec->catfile( $Config{siteprefixexp}, 'etc', $distname )
  • demo       File::Spec->catfile( $Config{siteprefixexp}, 'share', $distname', 'demo', )
  • demo_conf  File::Spec->catfile( $Config{siteprefixexp}, 'share', $distname', 'demo', 'conf' )
  • share      File::Spec->catfile( $Config{siteprefixexp}, 'share', $distname )

I've also considered putting the non-standard stuff into a $Config{siteprefixexp}/$distname/{etc,doc,demo,etc/demo} sort of organization. I'm not sure how *that* would go over with sysadmins, though it actually simplifies things for *me* quite a bit...

The conundrum here is that I *really* want to do this properly and the paths shown above still just don't feel right. I really dislike hard-coding directory paths. Currently, I'm only concerned about *nix, but I'm trying to plan ahead a little for Windows as well. - Hence the use of File::Spec.

SO... What's the best practice here? Is what I have OK? Can anybody suggest a CPAN dist that had to do the same thing? (so I can see how *they* solved it)

UPDATE: I've started putting up some notes on my scratch-pad, which may someday evolve into a proper Meditation :)

Replies are listed 'Best First'.
Re: Where to put the bits and pieces - Installing a complex CPAN dist
by LesleyB (Friar) on Sep 19, 2008 at 08:25 UTC

    I'm only a humble user of Debian and Perl so please take my suggestions a if I know very little

    Put the demos and demo conf in a pod. Then you could have Your::Module::Demo and Your::Module::Demo::Conf, assuming you have Your::Module of course.

    You would also have Your::Module::Conf to discuss the default configuration and Your::Module would have to indicate these other pods exist.

    The demos and their confs as distinct files could also end up in a sub dir of /usr/share/doc/libyourmodule-perl/. As could any info about the default conf. That's where I might expect to look for them anyway.

    As for the shared stuff there are share directories used by many perl modules e.g. /usr/share/perl/5.8.8, /usr/local/share/perl/5.8.8 and /usr/share/perl5 with rules as to what goes where.

    Then you could consider a web site to show the documentation again

    Best I can offer I'm afraid - if I am understanding correctly what you are asking of course.

      Thank you for your input - Debian tends to be my "gold standard" for correct packaging, and it seems that most of the Perl community agrees.

      To try to clarify, the demo scripts are just that - scripts, and they use config files that the modules will look for on the system (the search path is *fully* configurable). Each script has it's own config file.

      In the case of this distro, applications written using the modules will need to load config files and so I think the appropriate location is in /etc/$distname or /usr/local/etc/$distname. System defaults (like the search-path and various default behaviors) are stored in a module generated by Module::Build, but those can be overridden by any application's config.

      I'm wondering if I should put the demo configs under an etc directory as well, or should they be sequestered under a /usr/share sort of place. Perhaps I should put them under /usr/share and install into /usr/bin a script that the user could run later that copies the demo configs and scripts from there to /etc?

      After packaging it correctly, my goal for this distro is to make it as *easy* as possible for people to use and try out. It's been used in production for years now, but the author always custom-installed it, usually placing things wherever seemed good for that particular instance. Now we both want to see this software with a broader user-base, and my opinion is that a distro *must* install properly, right from CPAN, or 99.9% of users will give up and never look back. "Properly" includes putting things in places that are accessible and expected by the users and won't annoy sysadmins who run a tight ship (ARRRRRR!)

        It's always difficult to really be sure but I think the standard form is to put demo scripts and their config files in /usr/share/doc/<package-name>/demo and /usr/share/doc/<package-name>/demo/conf directories. I think tucked away with the default config in /etc would be the wrong place - not even exim4, spamassassin or clamav do that.

        I think that /etc or /usr/local/etc is the right place for an active config or set of configs for an installed system. (My /usr/local/etc happens to be empty on two systems.)

        Pod could always point out the existence of the /usr/share/doc/<package-name>/demo directories and even discuss their contents as well as that of the default install

        I think that is fairly general Linux behaviour - at least what I have seen of Debian, SuSE, Mandriva and Ubuntu - and so not entirely limited to Debian. The FHS says /usr/local/etc is for host specific configuration files for local binaries. I don't know if your application falls into that category.

        Nightmare with all the different possibilities, though -- I can't imagine where things go in Windows... or a Mac .

        Good luck

Re: Where to put the bits and pieces - Installing a complex CPAN dist
by Anonymous Monk on Sep 19, 2008 at 10:10 UTC
      Thanks for your input, but that distro isn't even remotely close to what I'm working with (however ironically... one of the many uses of this software is to create applications with WxPerl)
Re: Where to put the bits and pieces - Installing a complex CPAN dist
by adamk (Chaplain) on Sep 23, 2008 at 12:52 UTC
    See the behaviour of the current versions of Module::Install::Share and File::ShareDir for the "correct" pure-Perlish shared directory paths.
      Thanks! I actually found those this past weekend, and while I don't think they quite fit here, they are *quite* handy! In a fit of Laziness, Impatience and Hubris I began crafting my own system-path-resolver-thingie and it's using File::ShareDir, along with File::HomeDir, et. al.

      I do plan on posting some of my notes here just as soon as I've finished figuring out which ones make me look smart and which ones betray my true level of ignorance. :)

      OK, a link to the notes has been posted in the update section of the OP!
        There's a few problems I see... Firstly, you've dumped straight under unix system share... what if there are non-Perl packages that share a name with a CPAN distribution? What about when there are multiple versions of Perl installed on the machine? Where is the equivalent path on Windows? How do they get packaged into Perl distributions. The reason we use the auto method is that it handles most of the above cases...

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://712383]
Approved by Corion
Front-paged by salva
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others perusing the Monastery: (3)
As of 2017-04-28 19:31 GMT
Find Nodes?
    Voting Booth?
    I'm a fool:

    Results (528 votes). Check out past polls.