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#VARLIBVARIABLESTATEINFORMAT ION 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, `' 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.