NAME
    Sys::Path - provide autoconf-style installation directories

SYNOPSIS
    Default paths when Perl's installation prefix is /usr:

        use Sys::Path;

        print Sys::Path->sysconfdir, "\n";
        # /etc
        print Sys::Path->datadir, "\n";
        # /usr/share
        print Sys::Path->logdir, "\n";
        # /var/log
        print Sys::Path->sharedstatedir, "\n";
        # /var/lib

    Default paths when Perl's installation prefix is /home/daxim/local:

        print Sys::Path->sysconfdir, "\n";
        # /home/daxim/local/etc
        print Sys::Path->datadir, "\n";
        # /home/daxim/local/share
        print Sys::Path->logdir, "\n";
        # /home/daxim/local/var/log
        print Sys::Path->sharedstatedir, "\n";
        # /home/daxim/local/var/lib

    Default paths when Strawberry Perl's installation prefix is
    C:\Strawberry:

        print Sys::Path->sysconfdir, "\n";
        # C:\Strawberry\etc
        print Sys::Path->datadir, "\n";
        # C:\Strawberry\share
        print Sys::Path->logdir, "\n";
        # C:\Strawberry\var\log
        print Sys::Path->sharedstatedir, "\n";
        # C:\Strawberry\var\lib

DESCRIPTION
    Sys::Path provides a common set of installation-directory accessors.
    When Perl's installation prefix is /usr, their defaults follow the
    Filesystem Hierarchy Standard <http://www.pathname.com/fhs/>. Otherwise,
    defaults are derived from Perl's own prefix.

    "perl Build.PL" prompts for each path. The build writes the selected
    values into "Sys::Path::SPc", so installed consumers read the values
    configured for this Sys::Path installation.

    The module also provides helper methods for distribution builds and
    configuration-file installation. Module::Build::SysPath integrates these
    methods with Module::Build.

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

    Each accessor has a canonical "--sp-<accessor>" option. The legacy
    "--sp-cache", "--sp-log", "--sp-spool", "--sp-run", "--sp-lock", and
    "--sp-state" aliases remain available.

STATUS
    Sys::Path was published as an experiment in system-path configuration,
    build system integration, and path naming. The original documentation
    warned that its interfaces might change and directed discussion to
    <http://lists.meon.sk/mailman/listinfo/sys-path>.

  WHY?
    The Filesystem Hierarchy Standard defines shared directory locations for
    Unix distributions, packages, and systems. Sys::Path uses those
    locations when Perl's prefix is /usr. For other installations, including
    a Perl installed under a home directory or C:\Strawberry, it derives
    defaults beneath Perl's prefix. This keeps a non-system Perl
    installation self-contained by default.

  PATHS
    Each entry lists the default for a Perl prefix of /usr, followed by the
    default for any other prefix.

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

    Base path used to derive several other paths. Applications should
    normally use the more specific accessors below.

   localstatedir
    /var - $prefix/var

    Base path used for variable data. Applications should normally use the
    more specific accessors below.

   sysconfdir
    /etc - $prefix/etc

    Host-specific system configuration. See
    <http://www.pathname.com/fhs/pub/fhs-2.3.html#ETCHOSTSPECIFICSYSTEMCONFI
    GURATION>.

   datadir
    /usr/share - $prefix/share

    Read-only, architecture-independent data. See
    <http://www.pathname.com/fhs/pub/fhs-2.3.html#USRSHAREARCHITECTUREINDEPE
    NDENTDATA>.

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

    See "datadir"

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

    See "datadir"

   cachedir
    /var/cache - $localstatedir/cache

    Application cache data. See
    <http://www.pathname.com/fhs/pub/fhs-2.3.html#VARCACHEAPPLICATIONCACHEDA
    TA>.

   logdir
    /var/log - $localstatedir/log

    Application log files. See
    <http://www.pathname.com/fhs/pub/fhs-2.3.html#VARLOGLOGFILESANDDIRECTORI
    ES>.

   spooldir
    /var/spool - $localstatedir/spool

    Data awaiting later processing. See
    <http://www.pathname.com/fhs/pub/fhs-2.3.html#VARSPOOLAPPLICATIONSPOOLDA
    TA>.

   rundir
    /var/run - $localstatedir/run

    Runtime state describing the system since boot. See
    <http://www.pathname.com/fhs/pub/fhs-2.3.html#VARRUNRUNTIMEVARIABLEDATA>
    .

   lockdir
    /var/lock - $localstatedir/lock

    Lock files. See
    <http://www.pathname.com/fhs/pub/fhs-2.3.html#VARLOCKLOCKFILES>.

   sharedstatedir
    /var/lib - $localstatedir/lib

    Modifiable, architecture-independent application state. See
    <http://www.pathname.com/fhs/pub/fhs-2.3.html#VARLIBVARIABLESTATEINFORMA
    TION>.

   srvdir
    /srv - $prefix/srv

    Data served by the system. See
    <http://www.pathname.com/fhs/pub/fhs-2.3.html#SRVDATAFORSERVICESPROVIDED
    BYSYSTEM>.

   webdir
    /var/www - $localstatedir/www

    Static web content installed by distributions.

  HOW IT WORKS
    Default selection starts with Perl's configured prefix:

        use Config;
        if ($Config::Config{'prefix'} eq '/usr') { ... }

    For a prefix of /usr, Sys::Path selects the listed FHS defaults. For any
    other prefix, "localstatedir" is var beneath that prefix, and the
    remaining defaults are derived from "prefix" or "localstatedir" as shown
    above. Sys::Path::SPc implements the accessors; the build replaces its
    temporary configuration logic with the selected literal values.

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

BUILD AND INSTALLATION HELPERS
  find_distribution_root(__PACKAGE__)
    Load the named module if necessary, then search its parent directories
    for MANIFEST, Build.PL, or Makefile.PL. If the module cannot be loaded,
    start at the current working directory. Return the first matching
    directory; throw an exception if no distribution root is found.

    The current-working-directory fallback applies only when the named
    module is not installed. Errors raised while compiling or initializing
    an installed module are propagated.

    $module_name is required. Loading a module can execute its compile-time
    code.

  prompt_cfg_file_changed($src_file, $dst_file, $prompt_function)
    Ask whether $src_file should replace the modified $dst_file. The
    callback receives the prompt text and the default answer, "N". Return
    true for "Y" or "I", and false for "N" or "O".

    "D" prints a unified diff and prompts again. "Z" starts the user's login
    shell and prompts again after the shell exits. These options write
    directly to standard output.

  changed_since_install($dest_file, $file)
    Return true when the MD5 checksum of $file differs from the checksum
    recorded for $dest_file. $file defaults to $dest_file. A destination
    without a recorded checksum is considered changed.

    The method reads the entire comparison file and propagates read and
    decode errors from its dependencies.

  install_checksums(%filenames_with_checksums)
    Return the filename/checksum pairs stored in
    sharedstatedir/syspath/install-checksums.json. With arguments, merge the
    supplied pairs into the registry and return the resulting pairs.

    The parent directory must already exist. Reading a missing registry
    creates an empty JSON file and therefore requires write permission.
    Access is serialized through a persistent lock file, and "IO::Any"
    replaces the registry through its atomic-output mode. The lock
    coordinates cooperating callers; lock and replacement failures from the
    host platform are propagated.

SEE ALSO
    Module::Build::SysPath

AUTHOR
    Jozef Kutej, "<jkutej at cpan.org>"

CONTRIBUTORS
    The following people contributed code, patches, bug reports, questions,
    and suggestions (in no particular order):

        Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯
        Emmanuel Rodriguez
        Salve J. Nilsen
        Daniel Perrett
        Jose Luis Perez Diez
        Petr Písař
        Mohammad S Anwar

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.