NAME
    Sys::Path - get/configure system paths

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

Build.PL
        use Module::Build::SysPath;
        my $builder = Module::Build::SysPath->new(
            configure_requires => {
                'Module::Build::SysPath' => 0.06,
            },
            build_requires => {
                'Module::Build::SysPath' => 0.06,
            }
            ...

        use Module::Build;
        use Sys::Path;
    
        # update system paths during the installation
        my $builder_class = Module::Build->subclass(
            class => 'My::Builder',
            code => q{ use Module::Build::SysPath; unshift @ISA, 'Module::Build::SysPath'; },
        );
    
        my $builder = $builder_class->new(
            configure_requires => {
                'Module::Build::SysPath' => 0.06,
            },
            build_requires => {
                'Module::Build::SysPath' => 0.06,
            }
            ...

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. In addition to the
    system wide SPc, (SPc.pm) can be added to $HOME/.syspath/ folder in
    which case it has a preference over the system wide one.

  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. See the
    modules

    http://github.com/jozef/Acme-SysPath/blob/1a4b89e8239f55bee31b7f1c4fa3d6
    9c8de7c3a4/lib/Acme/SysPath.pm

    or Acme::SysPath. 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?

    TODO for next version...

  HOW IT WORKS

    TODO for next version...

METHODS
        prefix
        localstatedir
        sysconfdir
        datadir
        docdir
        cache
        log
        spool
        run
        lock
        state

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>'

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.