1File::ShareDir::ProjectUDsiesrtDCiorn(t3r)ibuted Perl DoFciulmee:n:tSahtairoenDir::ProjectDistDir(3)
2
6 File::ShareDir::ProjectDistDir - Simple set-and-forget using of a
7 '/share' directory in your projects root
8
10 version 1.000009
11
13 STOP!. Before using this distribution, some warnings MUST be
14 considered.
15 The primary use-case for this module is targeted at development
17 projects that are NOT intended for "CPAN".
18 As such, using it for "CPAN" is generally a bad idea, and better
20 solutions generally involve the less fragile "Test::File::ShareDir",
21 constraining any magical behavior exclusively to where it is needed:
22 Tests.
23 Why?
25 • Determining whether or not we are "dev" during "runtime" is a
27 perilous heuristic that routinely fails with even slightly unusual
28 file system layouts.
29 • Auto-magical changing of behavior at "runtime" based on the above
31 leads to many surprising and hard to debug problems.
32 For these reason, it is dangerous to rely on this distribution while
34 striving to produce quality code.
35 If this documentation is not sufficient to dissuade you, I must
37 strongly implore you to choose the "strict" mechanism, because that
38 substantially reduces the possibilities with regards to false-positive
39 of potential "dev" directories.
40 I have in mind to find a better mechanism to deliver the same
42 objective, but no solutions are forthcoming at this time.
43
45 package An::Example::Package;
46 use File::ShareDir::ProjectDistDir;
48 # during development, $dir will be $projectroot/share
50 # but once installed, it will be wherever File::Sharedir thinks it is.
51 my $dir = dist_dir('An-Example')
52 Project layout requirements:
54 $project/
56 $project/lib/An/Example/Package.pm
57 $project/share/ # files for package 'An-Example' go here.
58 You can use a directory name other than 'share' ( Assuming you make
60 sure when you install that, you specify the different directory there
61 also ) as follows:
62 use File::ShareDir::ProjectDistDir ':all', defaults => {
64 projectdir => 'templates',
65 };
66
68 import
69 use File::ShareDir::ProjectDistDir (@args);
70 This uses "Sub::Exporter" to do the heavy lifting, so most usage of
72 this module can be maximized by understanding that first.
73 • ":all"
75 ->import( ':all' , .... )
77 Import both "dist_dir" and "dist_file"
79 • "dist_dir"
81 ->import('dist_dir' , .... )
83 Import the dist_dir method
85 • "dist_file"
87 ->import('dist_file' , .... )
89 Import the dist_file method
91 • "projectdir"
93 ->import( .... , projectdir => 'share' )
95 Specify what the project directory is as a path relative to the
97 base of your distributions source, and this directory will be used
98 as a "ShareDir" simulation path for the exported methods During
99 development.
100 If not specified, the default value 'share' is used.
102 • "filename"
104 ->import( .... , filename => 'some/path/to/foo.pm' );
106 Generally you don't want to set this, as its worked out by caller()
108 to work out the name of the file its being called from. This file's
109 path is walked up to find the 'lib' element with a sibling of the
110 name of your "projectdir".
111 • "distname"
113 ->import( .... , distname => 'somedistname' );
115 Specifying this argument changes the way the functions are emitted
117 at installed "runtime", so that instead of taking the standard
118 arguments File::ShareDir does, the specification of the "distname"
119 in those functions is eliminated.
120 i.e:
122 # without this flag
124 use File::ShareDir::ProjectDistDir qw( :all );
125 my $dir = dist_dir('example');
127 my $file = dist_file('example', 'path/to/file.pm' );
128 # with this flag
130 use File::ShareDir::ProjectDistDir ( qw( :all ), distname => 'example' );
131 my $dir = dist_dir();
133 my $file = dist_file('path/to/file.pm' );
134 • "strict"
136 ->import( ... , strict => 1 );
138 This parameter specifies that all "dist" "sharedirs" will occur
140 within the "projectdir" directory using the following layout:
141 <root>/<projectdir>/dist/<DISTNAME>/
143 As opposed to
145 <root>/<projectdir>
147 This means if Heuristics misfire and accidentally find another
149 distributions "share" directory, it will not pick up on it unless
150 that "share" directory also has that layout, and will instead
151 revert to the "installdir" path in @INC
152 This parameter may become the default option in the future
154 Specifying this parameter also mandates you MUST declare the
156 "DISTNAME" value in your file somewhere. Doing otherwise is
157 considered insanity anyway.
158 • "defaults"
160 ->import( ... , defaults => {
162 filename => ....,
163 projectdir => ....,
164 });
165 This is mostly an alternative syntax for specifying "filename" and
167 "projectdir", which is mostly used internally, and their
168 corresponding other values are packed into this one.
169 Sub::Exporter tricks of note.
171 Make your own sharedir util
173 package Foo::Util;
175 sub import {
177 my ($caller_class, $caller_file, $caller_line ) = caller();
178 if ( grep { /share/ } @_ ) {
179 require File::ShareDir::ProjectDistDir;
180 File::ShareDir::ProjectDistDir->import(
181 filename => $caller_file,
182 dist_dir => { distname => 'myproject' , -as => 'share' },
183 dist_dir => { distname => 'otherproject' , -as => 'other_share' , projectdir => 'share2' },
184 -into => $caller_class,
185 );
186 }
187 }
188 ....
190 package Foo;
192 use Foo::Util qw( share );
193 my $dir = share();
195 my $other_dir => other_share();
196 build_dist_dir
198 use File::ShareDir::ProjectDirDir ( : all );
199 # this calls
201 my $coderef = File::ShareDir::ProjectDistDir->build_dist_dir(
202 'dist_dir' => {},
203 { defaults => { filename => 'path/to/yourcallingfile.pm', projectdir => 'share' } }
204 );
205 use File::ShareDir::ProjectDirDir ( qw( :all ), distname => 'example-dist' );
207 # this calls
209 my $coderef = File::ShareDir::ProjectDistDir->build_dist_dir(
210 'dist_dir' => {},
211 { distname => 'example-dist', defaults => { filename => 'path/to/yourcallingfile.pm', projectdir => 'share' } }
212 );
213 use File::ShareDir::ProjectDirDir
215 dist_dir => { distname => 'example-dist', -as => 'mydistdir' },
216 dist_dir => { distname => 'other-dist', -as => 'otherdistdir' };
217 # This calls
219 my $coderef = File::ShareDir::ProjectDistDir->build_dist_dir(
220 'dist_dir',
221 { distname => 'example-dist' },
222 { defaults => { filename => 'path/to/yourcallingfile.pm', projectdir => 'share' } },
223 );
224 my $othercoderef = File::ShareDir::ProjectDistDir->build_dist_dir(
225 'dist_dir',
226 { distname => 'other-dist' },
227 { defaults => { filename => 'path/to/yourcallingfile.pm', projectdir => 'share' } },
228 );
229 # And leverages Sub::Exporter to create 2 subs in your package.
231 Generates the exported 'dist_dir' method. In development environments,
233 the generated method will return a path to the development directories
234 'share' directory. In non-development environments, this simply returns
235 "File::ShareDir::dist_dir".
236 As a result of this, specifying the Distribution name is not required
238 during development ( unless in "strict" mode ), however, it will start
239 to matter once it is installed. This is a potential avenues for bugs if
240 you happen to name it wrong.
241 In "strict" mode, the distribution name is ALWAYS REQUIRED, either at
243 least at "import" or dist_dir() time.
244 build_dist_file
246 use File::ShareDir::ProjectDirDir ( : all );
247 # this calls
249 my $coderef = File::ShareDir::ProjectDistDir->build_dist_file(
250 'dist_file' => {},
251 { defaults => { filename => 'path/to/yourcallingfile.pm', projectdir => 'share' } }
252 );
253 use File::ShareDir::ProjectDirDir ( qw( :all ), distname => 'example-dist' );
255 # this calls
257 my $coderef = File::ShareDir::ProjectDistDir->build_dist_file(
258 'dist_file' => {},
259 { distname => 'example-dist', defaults => { filename => 'path/to/yourcallingfile.pm', projectdir => 'share' } }
260 );
261 use File::ShareDir::ProjectDirDir
263 dist_file => { distname => 'example-dist', -as => 'mydistfile' },
264 dist_file => { distname => 'other-dist', -as => 'otherdistfile' };
265 # This calls
267 my $coderef = File::ShareDir::ProjectDistDir->build_dist_file(
268 'dist_file',
269 { distname => 'example-dist' },
270 { defaults => { filename => 'path/to/yourcallingfile.pm', projectdir => 'share' } },
271 );
272 my $othercoderef = File::ShareDir::ProjectDistDir->build_dist_file(
273 'dist_file',
274 { distname => 'other-dist' },
275 { defaults => { filename => 'path/to/yourcallingfile.pm', projectdir => 'share' } },
276 );
277 # And leverages Sub::Exporter to create 2 subs in your package.
279 Generates the 'dist_file' method.
281 In development environments, the generated method will return a path to
283 the development directories 'share' directory. In non-development
284 environments, this simply returns "File::ShareDir::dist_file".
285 Caveats as a result of package-name as stated in "build_dist_dir" also
287 apply to this method.
288
290 1.000000
291 Strict Mode.
292 Using Strict Mode
294 use File::ShareDir::ProjectDistDir ':all', strict => 1;
296 use File::ShareDir::ProjectDistDir 'dist_dir' => { strict => 1 };
297 Why you should use strict mode
299 Starting with 1.000000, there is a parameter "strict" that changes how
301 "sharedir" resolution performs.
302 Without strict:
304 lib/...
306 share/...
307 With strict
309 lib/...
311 share/dist/Dist-Name-Here/...
312 This technique greatly builds resilience to the long standing problem
314 with "develop" vs "install" heuristic ambiguity.
315 Here at least,
317 dist_dir('Dist-Name')
319 Will instead fall back to
321 @INC/auto/share/dist/Dist-Name
323 When
325 share/dist/Dist-Name
327 Does not exist.
329 This means if you have a layout like this:
331 <DEVROOT>/inc/<a local::lib path here>
333 <DEVROOT>/lib/<development files here>
334 Then when "Foo-Bar-Baz" is installed as:
336 <DEVROOT>/inc/lib/Foo/Bar/Baz.pm
338 <DEVROOT>/inc/lib/auto/share/dist/Foo-Bar-Baz
339 Then "Baz.pm" will not see the "DEVROOT" and assume "Hey, this is
341 development" and then proceed to try finding files in "DEVROOT/share"
342 Instead, "DEVROOT" must have "DEVROOT/share/dist/Foo-Bar-Baz" too,
344 otherwise it reverts to "DEVROOT/inc/lib/auto..."
345 "Path::Class" interfaces deprecated and dependency dropped.
347 If you have any dependence on this function, now is the time to get
349 yourself off it.
350 Minimum Changes to stay with "Path::Class" short term.
352 As the dependency has been dropped on "Path::Class", if you have "CPAN"
354 modules relying on "Path::Class" interface, you should now at a very
355 minimum start declaring
356 { requires => "Path::Class" }
358 This will keep your dist working, but will not be future proof against
360 further changes.
361 Staying with "Path::Class" long term.
363 Recommended approach if you want to stay using the "Path::Class"
365 interface:
366 use File::ShareDir::... etc
368 use Path::Class qw( dir file );
369 my $dir = dir( dist_dir('Dist-Name') );
371 This should future-proof you against anything File::ShareDir may do in
373 the future.
374 "Versioning Scheme arbitrary converted to float"
376 This change is a superficial one, and should have no bearing on how
378 significant you think this release is.
379 It is a significant release, but the primary reason for the version
381 change is simply to avoid compatibility issues in versions themselves.
382 However, outside that, "x.y.z" semantics are still intended to be semi-
384 meaningful, just with less "." and more 0 ☺
385 "dev" path determination now deferred to call time instead of "use"
387 This was essentially a required change to make "strict" mode plausible,
389 because strict mode _requires_ the "distname" to be known, even in the
390 development environment.
391 This should not have any user visible effects, but please, if you have
393 any problems, file a bug.
394 "file" component determination wrested from "File::ShareDir".
396 dist_file('foo','bar')
398 Is now simply sugar syntax for
400 path(dist_dir('foo'))->child('bar')
402 This should have no side effects in your code, but please file any bugs
404 you experience.
405 ( return value is still "undef" if the file does not exist, and still
407 "croak"'s if the file is not a file, or unreadable, but these may both
408 be subject to change )
409 0.5.0 - Heuristics and Return type changes
411 New "devdir" heuristic
412 Starting with 0.5.0, instead of using our simple "lib/../share" pattern
414 heuristic, a more advanced heuristic is used from the new
415 "Path::FindDev" and "Path::IsDev".
416 This relies on a more "concrete" marker somewhere at the top of your
418 development tree, and more importantly, checks for the existence of
419 specific files that are not likely to occur outside a project root.
420 "lib" and "share" based heuristics were a little fragile, for a few
422 reasons:
423 • "lib" can, and does appear all over UNIX file systems, for purposes
425 other than development project roots.
426 For instance, have a look in "/usr/"
428 /usr/bin
430 /usr/lib
431 /usr/share ## UHOH.
432 This would have the very bad side effect of anything installed in
434 "/usr/lib" thinking its "in development".
435 Fortunately, nobody seems to have hit this specific bug, which I
437 suspect is due only to "/usr/lib" being a symbolic link on most
438 x86_64 systems.
439 • "lib" is also reasonably common within "CPAN" package names.
441 For instance:
443 lib::abs
445 Which means you'll have a hierarchy like:
447 $PREFIX/lib/lib/abs
449 All you need for something to go horribly wrong would be for
451 somebody to install a "CPAN" module named:
452 share::mystuff
454 Or similar, and instantly, you have:
456 $PREFIX/lib/lib/
458 $PREFIX/lib/share/
459 Which would mean any module calling itself "lib::*" would be unable
461 to use this module.
462 So instead, as of 0.5.0, the heuristic revolves around certain specific
464 files being in the "dev" directory.
465 Which is hopefully a more fault resilient mechanism.
467 New Return Types
469 Starting with 0.5.0, the internals are now based on "Path::Tiny"
471 instead of "Path::Class", and as a result, there may be a few glitches
472 in transition.
473 Also, previously you could get a "Path::Class::*" object back from
475 "dist_dir" and "dist_file" by importing it as such:
476 use File::ShareDir::ProjectDistDir
478 qw( dist_dir dist_file ),
479 defaults => { pathclass => 1 };
480 Now you can also get "Path::Tiny" objects back, by passing:
482 use File::ShareDir::ProjectDistDir
484 qw( dist_dir dist_file ),
485 defaults => { pathtiny => 1 };
486 For the time being, you can still get Path::Class objects back, it is
488 deprecated since 1.000000
489 ( In fact, I may even make 2 specific sub-classes of "PDD" for people
491 who want objects back, as it will make the "API" and the code much
492 cleaner )
493
495 Kent Fredric <kentnl@cpan.org>
496
498 This software is copyright (c) 2017 by Kent Fredric <kentnl@cpan.org>.
499 This is free software; you can redistribute it and/or modify it under
501 the same terms as the Perl 5 programming language system itself.
502perl v5.38.0 2023-07-20 File::ShareDir::ProjectDistDir(3)