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, `<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.

