- SEE ALSO
- COPYRIGHT AND LICENSE
File::ShareDir::Dist - Locate per-dist shared files
use File::ShareDir::Dist qw( dist_share ); my $dir = dist_share 'Foo-Bar-Baz';
- Only supports distribution directories.
It doesn't support perl modules or perl class directories. I have never really needed anything other than a per-dist share directory.
- Doesn't compute filenames.
For some reason there are two types. I have never seen or needed the older type.
- Hopefully doesn't find the wrong directory.
It doesn't blindly go finding the first share directory in @INC that matches the dist name. It actually checks to see that it matches the .pm file that goes along with it.
That does mean that you need to have a .pm that corresponds to your dist name. This is not always the case for some older historical distributions, but it has been the recommended convention for quite some time.
- No non-core dependencies.
The goal of this project is to have no non-core dependencies for the two most recent production versions of Perl. As of this writing that means Perl 5.26 and 5.24. In the future, we
mayadd dependencies on modules that are not part of the Perl core on older Perls.
- Works in your development tree.
Uses the heuristic, for determining if you are in a development tree, and if so, uses the common convention to find the directory named
share. If you are using a relative path in
@INC, if the directory
shareis a sibling of that relative entry in
@INCand if the last element in that relative path is
Example, if you have the directory structure:
and you invoke perl with
% perl -Ilib -MFoo::Bar::Baz -MFile::ShareDir::Dist=dist_share -E 'say dist_share("Foo-Bar-Baz")'
dist_sharewill return the (absolute) path to ./share/data. If you invoked it with:
% export PERL5LIB `pwd`/lib perl -MFoo::Bar::Baz -MFile::ShareDir::Dist=dist_share -E 'say dist_share("Foo-Bar-Baz")'
it would not. For me this covers most of my needs when developing a Perl module with a share directory.
- Built in override.
%File::ShareDir::Dist::overcan be used to override what
dist_sharereturns. You can also override behavior on the command line using a dash followed by a key value pair joined by the equal sign. In other words:
% perl -MFile::ShareDir::Dist=-Foo-Bar-Baz=./share -E 'say File::ShareDir::Dist::dist_share("Foo-Bar-Baz")' /.../share
If neither of those work then you can set PERL_FILE_SHAREDIR_DIST to a dist name, directory pair
% env PERL_FILE_SHAREDIR_DIST=Foo-Bar-Baz=`pwd`/share perl -MFile::ShareDir::Dist -E 'say File::ShareDir::Dist::dist_share("Foo-Bar-Baz")'
For File::ShareDir you have to either mock the
dist_dirfunction or install File::ShareDir::Override. For testing you can use Test::File::ShareDir. I have never understood why such a simple concept needs three modules to do all of this.
Functions must be explicitly exported. They are not exported by default.
my $dir = dist_share $dist_name; my $dir = dist_share $module_name;
Returns the absolute path to the share directory of the given distribution.
As a convenience you can also use the "main" module name associated with the distribution. That means if you want the share directory for the dist
Foo-Bar-Baz you may use either
Foo::Bar::Baz to find it.
Returns nothing if no share directory could be found.
Can be used to set a single dist directory override.
All the stuff that is in File::ShareDir but not in this module could be considered either caveats or features depending on your perspective I suppose.
Author: Graham Ollis <firstname.lastname@example.org>
Yanick Champoux (yanick)
This software is copyright (c) 2017 by Graham Ollis.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.