GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  PATH::ISDEV (3)

.ds Aq ’

NAME

Path::IsDev - Determine if a given Path resembles a development source tree

CONTENTS

VERSION

version 1.001002

SYNOPSIS



    use Path::IsDev qw(is_dev);

    if( is_dev(/some/path) ) {
        ...
    } else {
        ...
    }



DESCRIPTION

This module is more or less a bunch of heuristics for determining if a given path is a development tree root of some kind.

This has many useful applications, notably ones that require behaviours for installed modules to be different to those that are still in development

FUNCTIONS

    debug

Debug callback.

To enable debugging:



    export PATH_ISDEV_DEBUG=1



CWis_dev

Using an import’ed is_dev:



    if( is_dev( $path ) ) {

    }



Though the actual heuristics used will be based on how import was called.

Additionally, you can call



    Path::IsDev::is_dev



without importing anything, and it will behave exactly the same as if you’d imported it using



    use Path::IsDev qw( is_dev );



That is, no set specification is applicable, so you’ll only get the default.

UNDERSTANDING AND DEBUGGING THIS MODULE

Understanding how this module works, is critical to understand where you can use it, and the consequences of using it.

This module operates on a very simplistic level, and its easy for false-positives to occur.

There are two types of Heuristics, Postive/Confirming Heuristics, and Negative/Disconfirming Heuristics.

Positive Heuristics and Negative Heuristics are based solely on the presence of specific marker files in a directory, or special marker directories.

For instance, the files META.yml, Makefile.PL, and Build.PL are all <B>Positive HeuristicB> markers, because their presence often indicates a root of a development tree.

And for instance, the directories t/, xt/ and .git/ are also <B>Positive HeuristicB> markers, because these structures are common in perl development trees, and uncommon in install trees.

However, these markers sometimes go wrong, for instance, consider you have a local::lib or perlbrew install in $HOME



    $HOME/
    $HOME/lib/
    $HOME/perl5/perls/perl-5.19.3/lib/site_perl/



Etc.

Under normal circumstances, neither $HOME nor those 3 paths are considered dev.

However, all it takes to cause a false positive, is for somebody to install a t or xt directory, or a marker file in one of the above directories for path_isdev($dir) to return true.

This may not be a problem, at least, until you use Path::FindDev which combines Path::IsDev with recursive up-level traversal.



    $HOME/
    $HOME/lib/
    $HOME/perl5/perls/perl-5.19.3/lib/site_perl/

    find_dev($HOME/perl5/perls/perl-5.19.3/lib/site_perl/) # returns false, because it is not inside a dev directory

    mkdir $HOME/t

    find_dev($HOME/perl5/perls/perl-5.19.3/lib/site_perl/) # returns $HOME, because $HOME/t exists.



And it is this kind of problem that usually catches people off guard.



    PATH_ISDEV_DEBUG=1 \
        perl -Ilib -MPath::FindDev=find_dev \
        -E "say find_dev(q{/home/kent/perl5/perlbrew/perls/perl-5.19.3/lib/site_perl})"

    ...
    [Path::IsDev=0] + ::Tool::Dzil => 0 : dist.ini does not exist
    [Path::IsDev=0] + ::Tool::MakeMaker => 0 : Makefile.PL does not exist
    [Path::IsDev=0] + ::Tool::ModuleBuild => 0 : Build.PL does not exist
    [Path::IsDev=0] + ::META => 0 : META.json does not exist
    [Path::IsDev=0] + ::META => 1 : META.yml exists
    [Path::IsDev=0] + ::META => 1 : /home/kent/perl5/META.yml is a file
    [Path::IsDev=0] + ::META matched path /home/kent/perl5
    /home/kent/perl5



Whoops!.



    [Path::IsDev=0] + ::META => 1 : META.yml exists
    [Path::IsDev=0] + ::META => 1 : /home/kent/perl5/META.yml is a file



No wonder!



    rm /home/kent/perl5/META.yml

    PATH_ISDEV_DEBUG=1 \
        perl -Ilib -MPath::FindDev=find_dev \
        -E "say find_dev(q{/home/kent/perl5/perlbrew/perls/perl-5.19.3/lib/site_perl})"

    ...
    [Path::IsDev=0] Matching /home/kent/perl5
    ...
    [Path::IsDev=0] + ::TestDir => 0 : xt does not exist
    [Path::IsDev=0] + ::TestDir => 1 : t exists
    [Path::IsDev=0] + ::TestDir => 1 : /home/kent/perl5/t is a dir
    [Path::IsDev=0] + ::TestDir matched path /home/kent/perl5
    /home/kent/perl5



Double whoops!



    [Path::IsDev=0] + ::TestDir => 1 : t exists
    [Path::IsDev=0] + ::TestDir => 1 : /home/kent/perl5/t is a dir



And you could keep doing that until you rule out all the bad heuristics in your tree.

Or, you could use a negative heuristic.



    touch /home/kent/perl5/.path_isdev_ignore

    PATH_ISDEV_DEBUG=1 \
        perl -Ilib -MPath::FindDev=find_dev \
        -E "say find_dev(q{/home/kent/perl5/perlbrew/perls/perl-5.19.3/lib/site_perl})"
    ...
    [Path::IsDev=0] Matching /home/kent/perl5
    [Path::IsDev=0] - ::IsDev::IgnoreFile => 1 : .path_isdev_ignore exists
    [Path::IsDev=0] - ::IsDev::IgnoreFile => 1 : /home/kent/perl5/.path_isdev_ignore is a file
    [Path::IsDev=0] - ::IsDev::IgnoreFile excludes path /home/kent/perl5
    [Path::IsDev=0] no match found
    ...
    [Path::IsDev=0] Matching /
    ...
    [Path::IsDev=0] no match found



Success!



    [Path::IsDev=0] - ::IsDev::IgnoreFile => 1 : .path_isdev_ignore exists
    [Path::IsDev=0] - ::IsDev::IgnoreFile => 1 : /home/kent/perl5/.path_isdev_ignore is a file



HEURISTICS

    Negative Heuristics bundled with this distribution

Just remember, a <B>NegativeB> Heuristic <B>excludes the path it is associated withB>
o IsDev::IgnoreFile - .path_isdev_ignore

    Positive Heuristics bundled with this distribution

o Changelog - Files matching Changes, Changelog, and similar, case insensitive, extensions optional.
o DevDirMarker - explicit .devdir file to indicate a project root.
o META - META.yml/META.json
o MYMETA - MYMETA.yml/MYMETA.json
o Makefile - Any Makefile format documented supported by GNU Make
o TestDir - A directory called either t/ or xt/
o Tool::DZil - A dist.ini file
o Tool::MakeMaker - A Makefile.PL file
o Tool::ModuleBuild - A Build.PL file
o VCS::Git - A .git directory

HEURISTIC SETS

    Heuristic Sets Bundled with this distribution

o Basic - The basic heuristic set that contains most, if not all heuristics.

ADVANCED USAGE

    Custom Sets

Path::IsDev has a system of sets of Heuristics, in order to allow for pluggable and flexible heuristic types.

Though, for the vast majority of cases, this is not required.



    use Path::IsDev is_dev => { set => Basic };
    use Path::IsDev is_dev => { set => SomeOtherSet , -as => is_dev_other };



    Overriding the default set

If for whatever reason the Basic set is insufficient, or if it false positives on your system for some reason, the default set can be overridden.



    export PATH_ISDEV_DEFAULT_SET="SomeOtherSet"

    ...
    use Path::IsDev qw( is_dev );
    is_dev(/some/path) # uses SomeOtherSet



Though this will only take priority in the event the set is not specified during import

If this poses a security concern for the user, then this security hole can be eliminated by declaring the set you want in code:



    export PATH_ISDEV_DEFAULT_SET="SomeOtherSet"

    ...
    use Path::IsDev  is_dev => { set => Basic };
    is_dev(/some/path) # uses Basic, regardless of ENV



SECURITY

Its conceivable, than an evil user could construct an evil set, containing arbitrary and vulnerable code, and possibly stash that evil set in a poorly secured privileged users @INC

And if they managed to achieve that, if they could poison the privileged users %ENV, they could trick the privileged user into executing arbitrary code.

Though granted, if you can do either of those 2 things, you’re probably security vulnerable anyway, and granted, if you could do either of those 2 things you could do much more evil things by the following:



    export PERL5OPT="-MEvil::Module"



So with that in understanding, saying this modules default utility is insecure is mostly a bogus argument.

And to that effect, this module does nothing to lock down that mechanism, and this module encourages you to <B>NOTB> force a set, unless you <B>NEEDB> to, and strongly suggests that forcing a set for the purpose of security will achieve no real improvement in security, while simultaneously reducing utility.

AUTHOR

Kent Fredric <kentfredric@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Kent Fredric <kentfredric@gmail.com>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 PATH::ISDEV (3) 2014-08-16

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.