.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "File::ShareDir::Dist 3"
.TH File::ShareDir::Dist 3 "2018-08-30" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
File::ShareDir::Dist \- Locate per\-dist shared files
.SH "VERSION"
.IX Header "VERSION"
version 0.07
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use File::ShareDir::Dist qw( dist_share );
\& 
\& my $dir = dist_share \*(AqFoo\-Bar\-Baz\*(Aq;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
File::ShareDir::Dist finds share directories for distributions.  It is similar to File::ShareDir
with a few differences:
.IP "Only supports distribution directories." 4
.IX Item "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.
.IP "Doesn't compute filenames." 4
.IX Item "Doesn't compute filenames."
Doesn't compute files in the share directory for you.  This is what File::Spec or Path::Tiny
are for.
.IP "Doesn't support old style shares." 4
.IX Item "Doesn't support old style shares."
For some reason there are two types.  I have never seen or needed the older type.
.IP "Hopefully doesn't find the wrong directory." 4
.IX Item "Hopefully doesn't find the wrong directory."
It doesn't blindly go finding the first share directory in \f(CW@INC\fR that matches the dist name.  It actually
checks to see that it matches the .pm file that goes along with it.
.Sp
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.
.IP "No non-core dependencies." 4
.IX Item "No non-core dependencies."
File::ShareDir only has Class::Inspector, but since we are only doing per-dist share
directories we don't even need that.
.Sp
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 \f(CW\*(C`may\*(C'\fR add
dependencies on modules that are not part of the Perl core on older Perls.
.IP "Works in your development tree." 4
.IX Item "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 \f(CW\*(C`share\*(C'\fR.  If you are using a relative path in \f(CW@INC\fR,
if the directory \f(CW\*(C`share\*(C'\fR is a sibling of that relative entry in \f(CW@INC\fR and if the last element
in that relative path is \f(CW\*(C`lib\*(C'\fR.
.Sp
Example, if you have the directory structure:
.Sp
.Vb 2
\& lib/Foo/Bar/Baz.pm
\& share/data
.Ve
.Sp
and you invoke perl with
.Sp
.Vb 1
\& % perl \-Ilib \-MFoo::Bar::Baz \-MFile::ShareDir::Dist=dist_share \-E \*(Aqsay dist_share("Foo\-Bar\-Baz")\*(Aq
.Ve
.Sp
\&\f(CW\*(C`dist_share\*(C'\fR will return the (absolute) path to ./share/data.  If you invoked it with:
.Sp
.Vb 2
\& % export PERL5LIB \`pwd\`/lib
\& perl \-MFoo::Bar::Baz \-MFile::ShareDir::Dist=dist_share \-E \*(Aqsay dist_share("Foo\-Bar\-Baz")\*(Aq
.Ve
.Sp
it would not.  For me this covers most of my needs when developing a Perl module with a share
directory.
.Sp
prove foils this heuristic by making \f(CW@INC\fR absolute paths.  To get around that you can use
App::Prove::Plugin::ShareDirDist.
.IP "Built in override." 4
.IX Item "Built in override."
The hash \f(CW%File::ShareDir::Dist::over\fR can be used to override what \f(CW\*(C`dist_share\*(C'\fR returns.
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:
.Sp
.Vb 2
\& % perl \-MFile::ShareDir::Dist=\-Foo\-Bar\-Baz=./share \-E \*(Aqsay File::ShareDir::Dist::dist_share("Foo\-Bar\-Baz")\*(Aq
\& /.../share
.Ve
.Sp
If neither of those work then you can set \s-1PERL_FILE_SHAREDIR_DIST\s0 to a dist name, directory pair
.Sp
.Vb 1
\& % env PERL_FILE_SHAREDIR_DIST=Foo\-Bar\-Baz=\`pwd\`/share perl \-MFile::ShareDir::Dist \-E \*(Aqsay File::ShareDir::Dist::dist_share("Foo\-Bar\-Baz")\*(Aq
.Ve
.Sp
For File::ShareDir you have to either mock the \f(CW\*(C`dist_dir\*(C'\fR function 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.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
Functions must be explicitly exported.  They are not exported by default.
.SS "dist_share"
.IX Subsection "dist_share"
.Vb 2
\& my $dir = dist_share $dist_name;
\& my $dir = dist_share $module_name;
.Ve
.PP
Returns the absolute path to the share directory of the given distribution.
.PP
As a convenience you can also use the \*(L"main\*(R" module name associated with the
distribution.  That means if you want the share directory for the dist
\&\f(CW\*(C`Foo\-Bar\-Baz\*(C'\fR you may use either \f(CW\*(C`Foo\-Bar\-Baz\*(C'\fR or \f(CW\*(C`Foo::Bar::Baz\*(C'\fR to find
it.
.PP
Returns nothing if no share directory could be found.
.SS "dist_config"
.IX Subsection "dist_config"
[version 0.07]
.PP
.Vb 1
\& my $config = dist_config $dist_name;
.Ve
.PP
Returns the config at runtime as created by File::ShareDir::Dist::Install and install time.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
.IP "\s-1PERL_FILE_SHAREDIR_DIST\s0" 4
.IX Item "PERL_FILE_SHAREDIR_DIST"
Can be used to set a single dist directory override.
.SH "CAVEATS"
.IX Header "CAVEATS"
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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "File::ShareDir::Dist::Install" 4
.IX Item "File::ShareDir::Dist::Install"
.PD 0
.IP "App::Prove::Plugin::ShareDirDist" 4
.IX Item "App::Prove::Plugin::ShareDirDist"
.IP "App::Yath::Plugin::ShareDirDist" 4
.IX Item "App::Yath::Plugin::ShareDirDist"
.PD
.SH "AUTHOR"
.IX Header "AUTHOR"
Author: Graham Ollis <plicease@cpan.org>
.PP
Contributors:
.PP
Yanick Champoux (yanick)
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2017,2018 by Graham Ollis.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.