Sys::Path - supply autoconf style installation directories

Sys-Path documentation Contained in the Sys-Path distribution.

Index

Code Index:

NAME

Top

Sys::Path - supply autoconf style installation directories

SYNOPSIS

Top

Paths for basic Unix instalation when Perl is in /usr/bin:

    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

Paths for Unix when Perl is in home dir /home/daxim/local/bin:

    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/log
    print Sys::Path->sharedstatedir, "\n";
    # /home/daxim/local/lib

Paths for MS Windows Strawberry Perl when installed to 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\log
    print Sys::Path->sharedstatedir, "\n";
    # C:\Strawberry\lib

DESCRIPTION

Top

The goal is that Sys::Path provides autoconf style system paths.

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 programs using it can just read/use the paths.

In addition Sys::Path includes some functions that are related to modules build or instalation. For now there is only Module::Build based Module::Build::SysPath that uses Sys::Path.

BUILD TIME CONFIGURATION

Top

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

NOTE

Top

This is an experiment and lot of questions and concerns can come out about the paths configuration. Distributions build systems 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.

WHY?

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

Is a helper function and should not be used directly.

localstatedir

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

Is a helper function and should not be used directly.

sysconfdir

/etc - $prefix/etc

The /etc hierarchy contains configuration files. See http://www.pathname.com/fhs/pub/fhs-2.3.html#ETCHOSTSPECIFICSYSTEMCONFIGURATION.

datadir

/usr/share - $prefix/share

The /usr/share hierarchy is for all read-only architecture independent data files. 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

/var/cache is intended for cached data from applications. See http://www.pathname.com/fhs/pub/fhs-2.3.html#VARCACHEAPPLICATIONCACHEDATA.

logdir

/var/log - $localstatedir/logdir

This directory contains miscellaneous log files. Most logs must be written to this directory or an appropriate subdirectory. See http://www.pathname.com/fhs/pub/fhs-2.3.html#VARLOGLOGFILESANDDIRECTORIES.

spooldir

/var/spool - $localstatedir/spool

Contains data which is awaiting some kind of later processing. See http://www.pathname.com/fhs/pub/fhs-2.3.html#VARSPOOLAPPLICATIONSPOOLDATA.

rundir

/var/run - $localstatedir/rundir

This directory contains system information data describing the system since it was booted. See http://www.pathname.com/fhs/pub/fhs-2.3.html#VARRUNRUNTIMEVARIABLEDATA.

lockdir

/var/lock - $localstatedir/lock

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

sharedstatedir

/var/lib - $localstatedir/lib

The directory for installing modifiable architecture-independent data. See http://www.pathname.com/fhs/pub/fhs-2.3.html#VARLIBVARIABLESTATEINFORMATION.

webdir

/var/www - $localstatedir/www

Not defined by FHS but it is a place to put web page related (html, js, css, ...) files.

HOW IT WORKS

The heart of Sys::Path is just:

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

The idea is that if the Perl was installed to /usr it is FHS type installation and all path defaults are made based on FHS. For the rest of the installations prefix and localstatedir is set exactly to $Config::Config{'prefix'} which is the prefix of Perl that was used to install. In this case sysconfdir is set to prefix+'etc'. See Sys::Path::SPc for the implementation.

METHODS

Top

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

BUILDERS/INSTALLERS helper methods

Top

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.

SEE ALSO

Top

Module::Build::SysPath

FAQ

Top

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

Top

Jozef Kutej, <jkutej at cpan.org>

CONTRIBUTORS

Top

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

Top

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

Top

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

COPYRIGHT & LICENSE

Top

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.

Sys-Path documentation Contained in the Sys-Path distribution. 
package Sys::Path;


use warnings;
use strict;

our $VERSION = '0.10';

use File::Spec;
use Text::Diff 'diff';
use JSON::Util;
use Digest::MD5 qw(md5_hex);
use List::MoreUtils 'any', 'none';
use Carp 'croak';

use base 'Sys::Path::SPc';


sub find_distribution_root {
    my $self        = shift;
    my $module_name = shift;
    
    croak 'pass module_name as argument'
        if not $module_name;
    
    my $module_filename = $module_name.'.pm';
    $module_filename =~ s{::}{/}g;
    if (not exists $INC{$module_filename}) {
        eval 'use '.$module_name;
        die $@ if $@;
    }
    $module_filename = File::Spec->rel2abs($INC{$module_filename});
    
    my @path = File::Spec->splitdir($module_filename);
    my @package_names = split('::',$module_name);
    @path = splice(@path,0,-1-@package_names);
    while (not -d File::Spec->catdir(@path, 't')) {
        pop @path;
        die 'failed to find distribution root'
            if not @path;
    }
    return File::Spec->catdir(@path);
}


sub prompt_cfg_file_changed {
    my $self     = shift;
    my $src_file = shift;
    my $dst_file = shift;
    my $prompt_function = shift;

    my $answer = '';
    while (none { $answer eq $_ } qw(Y I N O) ) {
        print qq{
Installing new version of config file $dst_file ...

Configuration file `$dst_file'
  ==> Modified (by you or by a script) since installation.
  ==> Package distributor has shipped an updated version.
      What would you like to do about it ?  Your options are:
        Y or I  : install the package maintainer's version
        N or O  : keep your currently-installed version
            D     : show the differences between the versions
            Z     : background this process to examine the situation
  The default action is to keep your current version.
};
    
        $answer = uc $prompt_function->('*** '.$dst_file.' (Y/I/N/O/D/Z) ?', 'N');
        if ($answer eq 'D') {
            print "\n\n";
            print diff($src_file, $dst_file, { STYLE => 'Unified' });
            print "\n";
        }
        elsif ($answer eq 'Z') {
            print "Type `exit' when you're done.\n";
            system('bash');
        }
    }

    return 1 if any { $answer eq $_ } qw(Y I);
    return 0;
}



sub changed_since_install {
    my $self      = shift;
    my $dest_file = shift;
    my $file      = shift || $dest_file;

    my %files_checksums = $self->install_checksums;
    my $checksum = md5_hex(IO::Any->slurp([$file]));
    $files_checksums{$dest_file} ||= '';
    return $files_checksums{$dest_file} ne $checksum;
}


sub install_checksums {
    my $self = shift;
    my @args = @_;
    my $checksums_filename = File::Spec->catfile(
        Sys::Path::SPc->sharedstatedir,
        'syspath',
        'install-checksums.json'
    );

    if (@args) {
        print 'Updating ', $checksums_filename, "\n";
        my %conffiles_md5 = (
            $self->install_checksums,
            @args,
        );
        JSON::Util->encode(\%conffiles_md5, [ $checksums_filename ]);
        return %conffiles_md5;
    }
    
    JSON::Util->encode({}, [ $checksums_filename ])
        if not -f $checksums_filename;
    
    return %{JSON::Util->decode([ $checksums_filename ])};
}


1;


__END__


1; # End of Sys::Path