Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 259 lines (166 sloc) 9.353 kb
5b160b3 Kent Fredric Add README.mkdn
kentfredric authored
1 # NAME
2
3 Path::IsDev - Determine if a given Path resembles a development source tree
4
5 # VERSION
6
d55a5cf Kent Fredric post-release cleanup
kentfredric authored
7 version 1.001003
5b160b3 Kent Fredric Add README.mkdn
kentfredric authored
8
9 # SYNOPSIS
10
11 use Path::IsDev qw(is_dev);
12
13 if( is_dev('/some/path') ) {
14 ...
15 } else {
16 ...
17 }
18
19 # DESCRIPTION
20
21 This module is more or less a bunch of heuristics for determining if a given path
22 is a development tree root of some kind.
23
24 This has many useful applications, notably ones that require behaviours for "installed"
25 modules to be different to those that are still "in development"
26
27 # FUNCTIONS
28
29 ## debug
30
31 Debug callback.
32
33 To enable debugging:
34
35 export PATH_ISDEV_DEBUG=1
36
37 ## `is_dev`
38
39 Using an `import`'ed `is_dev`:
40
41 if( is_dev( $path ) ) {
42
43 }
44
45 Though the actual heuristics used will be based on how `import` was called.
46
47 Additionally, you can call
48
49 Path::IsDev::is_dev
50
51 without `import`ing anything, and it will behave exactly the same as if you'd imported
52 it using
53
54 use Path::IsDev qw( is_dev );
55
56 That is, no `set` specification is applicable, so you'll only get the "default".
57
00b84f8 Kent Fredric Improve base documentation
kentfredric authored
58 # UNDERSTANDING AND DEBUGGING THIS MODULE
59
60 Understanding how this module works, is critical to understand where you can use it, and the consequences of using it.
61
62 This module operates on a very simplistic level, and its easy for false-positives to occur.
63
64 There are two types of Heuristics, Postive/Confirming Heuristics, and Negative/Disconfirming Heuristics.
65
46829b0 Kent Fredric Update Docs
kentfredric authored
66 Positive Heuristics and Negative Heuristics are based solely on the presence of specific marker files in a directory, or special
67 marker directories.
00b84f8 Kent Fredric Improve base documentation
kentfredric authored
68
4d01823 Kent Fredric Update generated documentation
kentfredric authored
69 For instance, the files `META.yml`, `Makefile.PL`, and `Build.PL` are all **Positive Heuristic** markers, because their
46829b0 Kent Fredric Update Docs
kentfredric authored
70 presence often indicates a "root" of a development tree.
00b84f8 Kent Fredric Improve base documentation
kentfredric authored
71
4d01823 Kent Fredric Update generated documentation
kentfredric authored
72 And for instance, the directories `t/`, `xt/` and `.git/` are also **Positive Heuristic** markers, because these structures
00b84f8 Kent Fredric Improve base documentation
kentfredric authored
73 are common in `perl` development trees, and uncommon in install trees.
74
75 However, these markers sometimes go wrong, for instance, consider you have a `local::lib` or `perlbrew` install in `$HOME`
76
77 $HOME/
78 $HOME/lib/
79 $HOME/perl5/perls/perl-5.19.3/lib/site_perl/
80
81 Etc.
82
83 Under normal circumstances, neither `$HOME` nor those 3 paths are considered `dev`.
84
46829b0 Kent Fredric Update Docs
kentfredric authored
85 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
86 the above directories for `path_isdev($dir)` to return true.
00b84f8 Kent Fredric Improve base documentation
kentfredric authored
87
46829b0 Kent Fredric Update Docs
kentfredric authored
88 This may not be a problem, at least, until you use `Path::FindDev` which combines `Path::IsDev` with recursive up-level
89 traversal.
00b84f8 Kent Fredric Improve base documentation
kentfredric authored
90
91 $HOME/
92 $HOME/lib/
93 $HOME/perl5/perls/perl-5.19.3/lib/site_perl/
94
95 find_dev('$HOME/perl5/perls/perl-5.19.3/lib/site_perl/') # returns false, because it is not inside a dev directory
96
97 mkdir $HOME/t
98
99 find_dev('$HOME/perl5/perls/perl-5.19.3/lib/site_perl/') # returns $HOME, because $HOME/t exists.
100
101 And it is this kind of problem that usually catches people off guard.
102
46829b0 Kent Fredric Update Docs
kentfredric authored
103 PATH_ISDEV_DEBUG=1 \
104 perl -Ilib -MPath::FindDev=find_dev \
105 -E "say find_dev(q{/home/kent/perl5/perlbrew/perls/perl-5.19.3/lib/site_perl})"
00b84f8 Kent Fredric Improve base documentation
kentfredric authored
106
ba33b60 Kent Fredric Misc documenation updates
kentfredric authored
107 ...
108 [Path::IsDev=0] + ::Tool::Dzil => 0 : dist.ini does not exist
109 [Path::IsDev=0] + ::Tool::MakeMaker => 0 : Makefile.PL does not exist
110 [Path::IsDev=0] + ::Tool::ModuleBuild => 0 : Build.PL does not exist
111 [Path::IsDev=0] + ::META => 0 : META.json does not exist
112 [Path::IsDev=0] + ::META => 1 : META.yml exists
113 [Path::IsDev=0] + ::META => 1 : /home/kent/perl5/META.yml is a file
114 [Path::IsDev=0] + ::META matched path /home/kent/perl5
115 /home/kent/perl5
00b84f8 Kent Fredric Improve base documentation
kentfredric authored
116
117 Whoops!.
118
ba33b60 Kent Fredric Misc documenation updates
kentfredric authored
119 [Path::IsDev=0] + ::META => 1 : META.yml exists
120 [Path::IsDev=0] + ::META => 1 : /home/kent/perl5/META.yml is a file
00b84f8 Kent Fredric Improve base documentation
kentfredric authored
121
122 No wonder!
123
ba33b60 Kent Fredric Misc documenation updates
kentfredric authored
124 rm /home/kent/perl5/META.yml
00b84f8 Kent Fredric Improve base documentation
kentfredric authored
125
46829b0 Kent Fredric Update Docs
kentfredric authored
126 PATH_ISDEV_DEBUG=1 \
127 perl -Ilib -MPath::FindDev=find_dev \
128 -E "say find_dev(q{/home/kent/perl5/perlbrew/perls/perl-5.19.3/lib/site_perl})"
ba33b60 Kent Fredric Misc documenation updates
kentfredric authored
129
130 ...
00b84f8 Kent Fredric Improve base documentation
kentfredric authored
131 [Path::IsDev=0] Matching /home/kent/perl5
ba33b60 Kent Fredric Misc documenation updates
kentfredric authored
132 ...
133 [Path::IsDev=0] + ::TestDir => 0 : xt does not exist
134 [Path::IsDev=0] + ::TestDir => 1 : t exists
135 [Path::IsDev=0] + ::TestDir => 1 : /home/kent/perl5/t is a dir
136 [Path::IsDev=0] + ::TestDir matched path /home/kent/perl5
137 /home/kent/perl5
00b84f8 Kent Fredric Improve base documentation
kentfredric authored
138
139 Double whoops!
140
ba33b60 Kent Fredric Misc documenation updates
kentfredric authored
141 [Path::IsDev=0] + ::TestDir => 1 : t exists
142 [Path::IsDev=0] + ::TestDir => 1 : /home/kent/perl5/t is a dir
00b84f8 Kent Fredric Improve base documentation
kentfredric authored
143
144 And you could keep doing that until you rule out all the bad heuristics in your tree.
145
146 Or, you could use a negative heuristic.
147
ba33b60 Kent Fredric Misc documenation updates
kentfredric authored
148 touch /home/kent/perl5/.path_isdev_ignore
00b84f8 Kent Fredric Improve base documentation
kentfredric authored
149
46829b0 Kent Fredric Update Docs
kentfredric authored
150 PATH_ISDEV_DEBUG=1 \
151 perl -Ilib -MPath::FindDev=find_dev \
152 -E "say find_dev(q{/home/kent/perl5/perlbrew/perls/perl-5.19.3/lib/site_perl})"
ba33b60 Kent Fredric Misc documenation updates
kentfredric authored
153 ...
00b84f8 Kent Fredric Improve base documentation
kentfredric authored
154 [Path::IsDev=0] Matching /home/kent/perl5
ba33b60 Kent Fredric Misc documenation updates
kentfredric authored
155 [Path::IsDev=0] - ::IsDev::IgnoreFile => 1 : .path_isdev_ignore exists
156 [Path::IsDev=0] - ::IsDev::IgnoreFile => 1 : /home/kent/perl5/.path_isdev_ignore is a file
157 [Path::IsDev=0] - ::IsDev::IgnoreFile excludes path /home/kent/perl5
00b84f8 Kent Fredric Improve base documentation
kentfredric authored
158 [Path::IsDev=0] no match found
ba33b60 Kent Fredric Misc documenation updates
kentfredric authored
159 ...
160 [Path::IsDev=0] Matching /
161 ...
00b84f8 Kent Fredric Improve base documentation
kentfredric authored
162 [Path::IsDev=0] no match found
163
164 Success!
165
ba33b60 Kent Fredric Misc documenation updates
kentfredric authored
166 [Path::IsDev=0] - ::IsDev::IgnoreFile => 1 : .path_isdev_ignore exists
167 [Path::IsDev=0] - ::IsDev::IgnoreFile => 1 : /home/kent/perl5/.path_isdev_ignore is a file
00b84f8 Kent Fredric Improve base documentation
kentfredric authored
168
169 # HEURISTICS
170
171 ## Negative Heuristics bundled with this distribution
172
4d01823 Kent Fredric Update generated documentation
kentfredric authored
173 Just remember, a **Negative** Heuristic **excludes the path it is associated with**
00b84f8 Kent Fredric Improve base documentation
kentfredric authored
174
66b75bf Kent Fredric Point README to MetaCPAN
kentfredric authored
175 - [`IsDev::IgnoreFile`](https://metacpan.org/pod/Path::IsDev::NegativeHeuristic::IsDev::IgnoreFile) - `.path_isdev_ignore`
00b84f8 Kent Fredric Improve base documentation
kentfredric authored
176
177 ## Positive Heuristics bundled with this distribution
178
46829b0 Kent Fredric Update Docs
kentfredric authored
179 - [`Changelog`](https://metacpan.org/pod/Path::IsDev::Heuristic::Changelog) - Files matching `Changes`, `Changelog`, and similar, case
180 insensitive, extensions optional.
66b75bf Kent Fredric Point README to MetaCPAN
kentfredric authored
181 - [`DevDirMarker`](https://metacpan.org/pod/Path::IsDev::Heuristic::DevDirMarker) - explicit `.devdir` file to indicate a project root.
182 - [`META`](https://metacpan.org/pod/Path::IsDev::Heuristic::META) - `META.yml`/`META.json`
183 - [`MYMETA`](https://metacpan.org/pod/Path::IsDev::Heuristic::MYMETA) - `MYMETA.yml`/`MYMETA.json`
184 - [`Makefile`](https://metacpan.org/pod/Path::IsDev::Heuristic::Makefile) - Any `Makefile` format documented supported by GNU Make
185 - [`TestDir`](https://metacpan.org/pod/Path::IsDev::Heuristic::TestDir) - A directory called either `t/` or `xt/`
186 - [`Tool::DZil`](https://metacpan.org/pod/Path::IsDev::Heuristic::Tool::DZil) - A `dist.ini` file
187 - [`Tool::MakeMaker`](https://metacpan.org/pod/Path::IsDev::Heuristic::Tool::MakeMaker) - A `Makefile.PL` file
188 - [`Tool::ModuleBuild`](https://metacpan.org/pod/Path::IsDev::Heuristic::Tool::ModuleBuild) - A `Build.PL` file
189 - [`VCS::Git`](https://metacpan.org/pod/Path::IsDev::Heuristic::VCS::Git) - A `.git` directory
00b84f8 Kent Fredric Improve base documentation
kentfredric authored
190
191 # HEURISTIC SETS
192
193 ## Heuristic Sets Bundled with this distribution
194
66b75bf Kent Fredric Point README to MetaCPAN
kentfredric authored
195 - [`Basic`](https://metacpan.org/pod/Path::IsDev::HeuristicSet::Basic) - The basic heuristic set that contains most, if not all heuristics.
00b84f8 Kent Fredric Improve base documentation
kentfredric authored
196
5b160b3 Kent Fredric Add README.mkdn
kentfredric authored
197 # ADVANCED USAGE
198
199 ## Custom Sets
200
201 `Path::IsDev` has a system of "sets" of Heuristics, in order to allow for pluggable
202 and flexible heuristic types.
203
204 Though, for the vast majority of cases, this is not required.
205
206 use Path::IsDev is_dev => { set => 'Basic' };
207 use Path::IsDev is_dev => { set => 'SomeOtherSet' , -as => 'is_dev_other' };
208
209 ## Overriding the default set
210
211 If for whatever reason the `Basic` set is insufficient, or if it false positives on your system for some reason,
212 the "default" set can be overridden.
213
214 export PATH_ISDEV_DEFAULT_SET="SomeOtherSet"
215
216 ...
217 use Path::IsDev qw( is_dev );
218 is_dev('/some/path') # uses SomeOtherSet
219
220 Though this will only take priority in the event the set is not specified during `import`
221
222 If this poses a security concern for the user, then this security hole can be eliminated by declaring the set you want in code:
223
224 export PATH_ISDEV_DEFAULT_SET="SomeOtherSet"
225
226 ...
227 use Path::IsDev is_dev => { set => 'Basic' };
228 is_dev('/some/path') # uses Basic, regardless of ENV
229
230 # SECURITY
231
46829b0 Kent Fredric Update Docs
kentfredric authored
232 Its conceivable, than an evil user could construct an evil set, containing arbitrary and vulnerable code, and possibly stash that
233 evil set in a poorly secured privileged users @INC
5b160b3 Kent Fredric Add README.mkdn
kentfredric authored
234
46829b0 Kent Fredric Update Docs
kentfredric authored
235 And if they managed to achieve that, if they could poison the privileged users %ENV, they could trick the privileged user into
236 executing arbitrary code.
5b160b3 Kent Fredric Add README.mkdn
kentfredric authored
237
46829b0 Kent Fredric Update Docs
kentfredric authored
238 Though granted, if you can do either of those 2 things, you're probably security vulnerable anyway, and granted, if you could do
239 either of those 2 things you could do much more evil things by the following:
5b160b3 Kent Fredric Add README.mkdn
kentfredric authored
240
241 export PERL5OPT="-MEvil::Module"
242
243 So with that in understanding, saying this modules default utility is "insecure" is mostly a bogus argument.
244
245 And to that effect, this module does nothing to "lock down" that mechanism, and this module encourages you
4d01823 Kent Fredric Update generated documentation
kentfredric authored
246 to **NOT** force a set, unless you **NEED** to, and strongly suggests that forcing a set for the purpose of security will achieve
46829b0 Kent Fredric Update Docs
kentfredric authored
247 no real improvement in security, while simultaneously reducing utility.
5b160b3 Kent Fredric Add README.mkdn
kentfredric authored
248
249 # AUTHOR
250
251 Kent Fredric <kentfredric@gmail.com>
252
253 # COPYRIGHT AND LICENSE
254
46829b0 Kent Fredric Update Docs
kentfredric authored
255 This software is copyright (c) 2014 by Kent Fredric <kentfredric@gmail.com>.
5b160b3 Kent Fredric Add README.mkdn
kentfredric authored
256
257 This is free software; you can redistribute it and/or modify it under
258 the same terms as the Perl 5 programming language system itself.
Something went wrong with that request. Please try again.