NAME

Sys::Path - supply autoconf style installation directories

SYNOPSIS

DESCRIPTION

BUILD

PERL_MM_USE_DEFAULT=1 perl Build.PL \
    --sp-prefix=/usr/local \
    --sp-sysconfdir=/usr/local/etc \
    --sp-localstatedir=/var/local

NOTE

This is an experiment and lot of questions and concerns can come out about the paths configuration. Module::Build integration and the naming. And as this is early version thinks may change. For these purposes there is a mailing list http://lists.meon.sk/mailman/listinfo/sys-path.

DESCRIPTION

This module tries to solve the problem of working with data files, configuration files, images, logs, locks, ..., any non-*.pm files within distribution tar-balls. The default paths for file locations are based on http://www.pathname.com/fhs/ (Filesystem Hierarchy Standard) if the Perl was installed in /usr. For all other non-standard Perl installations or systems the default prefix is the prefix of Perl it self. Still those are just defaults and can be changed during perl Build.PL prompting. After Sys::Path is configured and installed all modules using it can just read/use the paths set.

USAGE

Sys::Path primary usage is for module authors to allow them to find their data files as during development and testing but also when installed. How? Let's look at an example distribution Acme::SysPath that needs a configuration file an image file and a template file. It has path()+template()+image() functions. While working in the distribution tree:

Acme-SysPath$ perl -Ilib -MAcme::SysPath -le 'print Acme::SysPath->config, "\n", Acme::SysPath->template;'
/home/jozef/prog/Acme-SysPath/conf/acme-syspath.cfg
/home/jozef/prog/Acme-SysPath/share/acme-syspath/tt/index.tt2

After install:

Acme-SysPath$ perl Build.PL && ./Build && ./Build test
Acme-SysPath$ sudo ./Build install
Copying lib/Acme/SysPath.pm -> blib/lib/Acme/SysPath.pm
Manifying blib/lib/Acme/SysPath.pm -> blib/libdoc/Acme::SysPath.3pm
Installing /usr/share/acme-syspath/tt/index.tt2
Installing /usr/share/acme-syspath/images/smile.ascii
Installing /usr/local/share/perl/5.10.0/Acme/SysPath.pm
Installing /usr/local/share/perl/5.10.0/Acme/SysPath/SPc.pm
Installing /usr/local/man/man3/Acme::SysPath::SPc.3pm
Installing /usr/local/man/man3/Acme::SysPath.3pm
Installing /etc/acme-syspath.cfg
Writing /usr/local/lib/perl/5.10.0/auto/Acme/SysPath/.packlist

Acme-SysPath$ cat /usr/local/share/perl/5.10.0/Acme/SysPath/SPc.pm
...
sub prefix {'/usr'};
sub sysconfdir {'/etc'};
sub datadir {'/usr/share'};
...

~$ perl -MAcme::SysPath -le 'print Acme::SysPath->config, "\n", Acme::SysPath->template;'
/etc/acme-syspath.cfg
/usr/share/acme-syspath/tt/index.tt2

~$ perl -MAcme::SysPath -le 'print Acme::SysPath->image;'
... try your self :-P

First step is to have a My::App::SPc. Take:

lib/Acme/SysPath/SPc.pm || examples/Sys-Path-Example1/lib/Sys/Path/Example1/SPc.pm

Then keep the needed paths and set then to your distribution taste. (someone likes etc, someone likes cfg or conf or ...) Then replace the Module::Build in Build.PL with Module::Build::SysPath. And finally populate the etc/, cfg/, conf/, share/, doc/, ... with some useful content.

WHY?

To place and then find files on the filesystem where they are suppose to be. There is a Filesystem Hierarchy Standard - http://www.pathname.com/fhs/:

The filesystem standard has been designed to be used by Unix distribution developers, package developers, and system implementors. However, it is primarily intended to be a reference and is not a tutorial on how to manage a Unix filesystem or directory hierarchy.

Sys::Path follows this standard when it is possible. Or when Perl follows. Perl can be installed in many places. Most Linux distributions place Perl in /usr/bin/perl where FHS suggest. In this case the FHS folders are suggested in prompt when doing `perl Build.PL`. In other cases for other folders or home-dir Perl distributions Sys::Path will suggest folders under Perl install prefix. (ex. c:\strawerry\ for the ones using Windows).

PATHS

Here is the list of paths. First the default FHS path, then (to compare) a suggested path when Perl is not installed in /usr.

prefix

/usr - $Config::Config{'prefix'}

localstatedir

/var - $Config::Config{'prefix'}

sysconfdir

/etc - $prefix/etc

datadir

/usr/share - $prefix/share

docdir

/usr/share/doc - $prefix/share/doc

localedir

/usr/share/locale - $prefix/share/locale

cachedir

/var/cache - $localstatedir/cache

logdir

/var/log - $localstatedir/logdir

spooldir

/var/spool - $localstatedir/spool

rundir

/var/run - $localstatedir/rundir

lockdir

/var/lock - $localstatedir/lock

sharedstatedir

/var/lib - $localstatedir/lib

The directory for installing modifiable architecture-independent data. http://www.pathname.com/fhs/pub/fhs-2.3.html#VARLIBVARIABLESTATEINFORMATION

webdir

/var/www - $localstatedir/www

USE CASES

system installation

TODO

custom perl installation

TODO

homedir installation

TODO

HOW IT WORKS

TODO for next version...

METHODS

prefix
localstatedir
sysconfdir
datadir
docdir
localedir
cachedir
logdir
spooldir
rundir
lockdir
sharedstatedir
webdir

BUILDERS/INSTALLERS helper methods

find_distribution_root(__PACKAGE__)

Find the root folder of distribution by going up the folder structure.

prompt_cfg_file_changed($src_file, $dst_file, $prompt_function)

Will prompt if to overwrite $dst_file with $src_file. Returns true for "yes" and false for "no".

changed_since_install($dest_file, $file)

Return if $dest_file changed since install. If optional $file is set then this one is compared agains install $dest_file checksum.

install_checksums(%filenames_with_checksums)

Getter and setter for files checksums recording.

FAQ

Why "SPc" ?

1. it is short (much more than SysPatchConfig)

2. it is weird

3. it's so weird that it is uniq, so there will be no conflict. (hopefully)

AUTHOR

Jozef Kutej, <jkutej at cpan.org>

CONTRIBUTORS

The following people have contributed to the Sys::Path by commiting their code, sending patches, reporting bugs, asking questions, suggesting useful advices, nitpicking, chatting on IRC or commenting on my blog (in no particular order):

Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯
Emmanuel Rodriguez

BUGS

Please report any bugs or feature requests to bug-sys-path at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Sys-Path. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

Mailing list

http://lists.meon.sk/mailman/listinfo/sys-path

The rest

You can find documentation for this module with the perldoc command.

perldoc Sys::Path

You can also look for information at:

• RT: CPAN's request tracker

  http://rt.cpan.org/NoAuth/Bugs.html?Dist=Sys-Path

• AnnoCPAN: Annotated CPAN documentation

  http://annocpan.org/dist/Sys-Path

• CPAN Ratings

  http://cpanratings.perl.org/d/Sys-Path

• Search CPAN

  http://search.cpan.org/dist/Sys-Path

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2009 Jozef Kutej, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Sys::Path

perl -MCPAN -e shell
install Sys::Path