/ 
Sys-Path-0.17
⭐ Starred 3 / Sys::Path

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. 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#ETCHOSTSPECIFICSYSTEMCONFIGURATION.

datadir

/usr/share - $prefix/share

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

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#VARCACHEAPPLICATIONCACHEDATA.

logdir

/var/log - $localstatedir/log

Application log files. See http://www.pathname.com/fhs/pub/fhs-2.3.html#VARLOGLOGFILESANDDIRECTORIES.

spooldir

/var/spool - $localstatedir/spool

Data awaiting later processing. See http://www.pathname.com/fhs/pub/fhs-2.3.html#VARSPOOLAPPLICATIONSPOOLDATA.

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#VARLIBVARIABLESTATEINFORMATION.

srvdir

/srv - $prefix/srv

Data served by the system. See http://www.pathname.com/fhs/pub/fhs-2.3.html#SRVDATAFORSERVICESPROVIDEDBYSYSTEM.

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.