.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "File::ShareDir::ProjectDistDir 3pm"
.TH File::ShareDir::ProjectDistDir 3pm "2014-08-18" "perl v5.20.1" "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::ProjectDistDir \- Simple set\-and\-forget using of a '/share' directory in your projects root
.SH "VERSION"
.IX Header "VERSION"
version 1.000004
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  package An::Example::Package;
\&
\&  use File::ShareDir::ProjectDistDir;
\&
\&  # during development, $dir will be $projectroot/share
\&  # but once installed, it will be wherever File::Sharedir thinks it is.
\&  my $dir = dist_dir(\*(AqAn\-Example\*(Aq)
.Ve
.PP
Project layout requirements:
.PP
.Vb 3
\&  $project/
\&  $project/lib/An/Example/Package.pm
\&  $project/share/   # files for package \*(AqAn\-Example\*(Aq go here.
.Ve
.PP
You can use a directory name other than 'share' ( Assuming you make sure when
you install that, you specify the different directory there also ) as follows:
.PP
.Vb 3
\&  use File::ShareDir::ProjectDistDir \*(Aq:all\*(Aq, defaults => {
\&    projectdir => \*(Aqtemplates\*(Aq,
\&  };
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "import"
.IX Subsection "import"
.Vb 1
\&    use File::ShareDir::ProjectDistDir (@args);
.Ve
.PP
This uses \f(CW\*(C`Sub::Exporter\*(C'\fR to do the heavy lifting, so most usage of this module can be maximized by
understanding that first.
.IP "\(bu" 4
\&\fB\f(CB\*(C`:all\*(C'\fB\fR
.Sp
.Vb 1
\&    \->import( \*(Aq:all\*(Aq , .... )
.Ve
.Sp
Import both \f(CW\*(C`dist_dir\*(C'\fR and \f(CW\*(C`dist_file\*(C'\fR
.IP "\(bu" 4
\&\fB\f(CB\*(C`dist_dir\*(C'\fB\fR
.Sp
.Vb 1
\&    \->import(\*(Aqdist_dir\*(Aq , .... )
.Ve
.Sp
Import the dist_dir method
.IP "\(bu" 4
\&\fB\f(CB\*(C`dist_file\*(C'\fB\fR
.Sp
.Vb 1
\&    \->import(\*(Aqdist_file\*(Aq , .... )
.Ve
.Sp
Import the dist_file method
.IP "\(bu" 4
\&\fB\f(CB\*(C`projectdir\*(C'\fB\fR
.Sp
.Vb 1
\&    \->import( .... , projectdir => \*(Aqshare\*(Aq )
.Ve
.Sp
Specify what the project directory is as a path relative to the base of your distributions source,
and this directory will be used as a \f(CW\*(C`ShareDir\*(C'\fR simulation path for the exported methods \fIDuring development\fR.
.Sp
If not specified, the default value 'share' is used.
.IP "\(bu" 4
\&\fB\f(CB\*(C`filename\*(C'\fB\fR
.Sp
.Vb 1
\&    \->import( .... , filename => \*(Aqsome/path/to/foo.pm\*(Aq );
.Ve
.Sp
Generally you don't want to set this, as its worked out by \fIcaller()\fR to work out the name of
the file its being called from. This file's path is walked up to find the 'lib' element with a sibling
of the name of your \f(CW\*(C`projectdir\*(C'\fR.
.IP "\(bu" 4
\&\fB\f(CB\*(C`distname\*(C'\fB\fR
.Sp
.Vb 1
\&    \->import( .... , distname => \*(Aqsomedistname\*(Aq );
.Ve
.Sp
Specifying this argument changes the way the functions are emitted at \fIinstalled \f(CI\*(C`runtime\*(C'\fI\fR, so that instead of
taking the standard arguments File::ShareDir does, the specification of the \f(CW\*(C`distname\*(C'\fR in those functions is eliminated.
.Sp
i.e:
.Sp
.Vb 2
\&    # without this flag
\&    use File::ShareDir::ProjectDistDir qw( :all );
\&
\&    my $dir = dist_dir(\*(Aqexample\*(Aq);
\&    my $file = dist_file(\*(Aqexample\*(Aq, \*(Aqpath/to/file.pm\*(Aq );
\&
\&    # with this flag
\&    use File::ShareDir::ProjectDistDir ( qw( :all ), distname => \*(Aqexample\*(Aq );
\&
\&    my $dir = dist_dir();
\&    my $file = dist_file(\*(Aqpath/to/file.pm\*(Aq );
.Ve
.IP "\(bu" 4
\&\fB\f(CB\*(C`strict\*(C'\fB\fR
.Sp
.Vb 1
\&    \->import( ... , strict => 1 );
.Ve
.Sp
This parameter specifies that all \f(CW\*(C`dist\*(C'\fR \f(CW\*(C`sharedirs\*(C'\fR will occur within the \f(CW\*(C`projectdir\*(C'\fR directory using the following layout:
.Sp
.Vb 1
\&    <root>/<projectdir>/dist/<DISTNAME>/
.Ve
.Sp
As opposed to
.Sp
.Vb 1
\&    <root>/<projectdir>
.Ve
.Sp
This means if Heuristics misfire and accidentally find another distributions \f(CW\*(C`share\*(C'\fR directory, it will not pick up on it
unless that \f(CW\*(C`share\*(C'\fR directory also has that layout, and will instead revert to the \f(CW\*(C`installdir\*(C'\fR path in \f(CW@INC\fR
.Sp
\&\fBThis parameter may become the default option in the future\fR
.Sp
Specifying this parameter also mandates you \fB\s-1MUST\s0\fR declare the \f(CW\*(C`DISTNAME\*(C'\fR value in your file somewhere. Doing otherwise is
considered insanity anyway.
.IP "\(bu" 4
\&\fB\f(CB\*(C`defaults\*(C'\fB\fR
.Sp
.Vb 4
\&    \->import( ... , defaults => {
\&        filename => ....,
\&        projectdir => ....,
\&    });
.Ve
.Sp
This is mostly an alternative syntax for specifying \f(CW\*(C`filename\*(C'\fR and \f(CW\*(C`projectdir\*(C'\fR,
which is mostly used internally, and their corresponding other values are packed into this one.
.PP
\fISub::Exporter tricks of note.\fR
.IX Subsection "Sub::Exporter tricks of note."
.PP
Make your own sharedir util
.IX Subsection "Make your own sharedir util"
.PP
.Vb 1
\&    package Foo::Util;
\&
\&    sub import {
\&        my ($caller_class, $caller_file, $caller_line )  = caller();
\&        if ( grep { /share/ } @_ ) {
\&            require File::ShareDir::ProjectDistDir;
\&            File::ShareDir::ProjectDistDir\->import(
\&                filename => $caller_file,
\&                dist_dir => { distname => \*(Aqmyproject\*(Aq , \-as => \*(Aqshare\*(Aq },
\&                dist_dir => { distname => \*(Aqotherproject\*(Aq , \-as => \*(Aqother_share\*(Aq , projectdir => \*(Aqshare2\*(Aq },
\&                \-into => $caller_class,
\&            );
\&        }
\&    }
\&
\&    ....
\&
\&    package Foo;
\&    use Foo::Util qw( share );
\&
\&    my $dir = share();
\&    my $other_dir => other_share();
.Ve
.SS "build_dist_dir"
.IX Subsection "build_dist_dir"
.Vb 1
\&    use File::ShareDir::ProjectDirDir ( : all );
\&
\&    #  this calls
\&    my $coderef = File::ShareDir::ProjectDistDir\->build_dist_dir(
\&      \*(Aqdist_dir\*(Aq => {},
\&      { defaults => { filename => \*(Aqpath/to/yourcallingfile.pm\*(Aq, projectdir => \*(Aqshare\*(Aq } }
\&    );
\&
\&    use File::ShareDir::ProjectDirDir ( qw( :all ), distname => \*(Aqexample\-dist\*(Aq );
\&
\&    #  this calls
\&    my $coderef = File::ShareDir::ProjectDistDir\->build_dist_dir(
\&      \*(Aqdist_dir\*(Aq => {},
\&      { distname => \*(Aqexample\-dist\*(Aq, defaults => { filename => \*(Aqpath/to/yourcallingfile.pm\*(Aq, projectdir => \*(Aqshare\*(Aq } }
\&    );
\&
\&    use File::ShareDir::ProjectDirDir
\&      dist_dir => { distname => \*(Aqexample\-dist\*(Aq, \-as => \*(Aqmydistdir\*(Aq },
\&      dist_dir => { distname => \*(Aqother\-dist\*(Aq,   \-as => \*(Aqotherdistdir\*(Aq };
\&
\&    # This calls
\&    my $coderef = File::ShareDir::ProjectDistDir\->build_dist_dir(
\&      \*(Aqdist_dir\*(Aq,
\&      { distname => \*(Aqexample\-dist\*(Aq },
\&      { defaults => { filename => \*(Aqpath/to/yourcallingfile.pm\*(Aq, projectdir => \*(Aqshare\*(Aq } },
\&    );
\&    my $othercoderef = File::ShareDir::ProjectDistDir\->build_dist_dir(
\&      \*(Aqdist_dir\*(Aq,
\&      { distname => \*(Aqother\-dist\*(Aq },
\&      { defaults => { filename => \*(Aqpath/to/yourcallingfile.pm\*(Aq, projectdir => \*(Aqshare\*(Aq } },
\&    );
\&
\&    # And leverages Sub::Exporter to create 2 subs in your package.
.Ve
.PP
Generates the exported 'dist_dir' method. In development environments, the generated method will return a path to the
development directories 'share' directory. In non-development environments, this simply returns \f(CW\*(C`File::ShareDir::dist_dir\*(C'\fR.
.PP
As a result of this, specifying the Distribution name is not required during development ( unless in \f(CW\*(C`strict\*(C'\fR mode ), however,
it will start to matter once it is installed. This is a potential avenues for bugs if you happen to name it wrong.
.PP
In \f(CW\*(C`strict\*(C'\fR mode, the distribution name is \fB\s-1ALWAYS REQUIRED\s0\fR, either at least at \f(CW\*(C`import\*(C'\fR or \f(CW\*(C`dist_dir()\*(C'\fR time.
.SS "build_dist_file"
.IX Subsection "build_dist_file"
.Vb 1
\&    use File::ShareDir::ProjectDirDir ( : all );
\&
\&    #  this calls
\&    my $coderef = File::ShareDir::ProjectDistDir\->build_dist_file(
\&      \*(Aqdist_file\*(Aq => {},
\&      { defaults => { filename => \*(Aqpath/to/yourcallingfile.pm\*(Aq, projectdir => \*(Aqshare\*(Aq } }
\&    );
\&
\&    use File::ShareDir::ProjectDirDir ( qw( :all ), distname => \*(Aqexample\-dist\*(Aq );
\&
\&    #  this calls
\&    my $coderef = File::ShareDir::ProjectDistDir\->build_dist_file(
\&      \*(Aqdist_file\*(Aq => {},
\&      { distname => \*(Aqexample\-dist\*(Aq, defaults => { filename => \*(Aqpath/to/yourcallingfile.pm\*(Aq, projectdir => \*(Aqshare\*(Aq } }
\&    );
\&
\&    use File::ShareDir::ProjectDirDir
\&      dist_file => { distname => \*(Aqexample\-dist\*(Aq, \-as => \*(Aqmydistfile\*(Aq },
\&      dist_file => { distname => \*(Aqother\-dist\*(Aq,   \-as => \*(Aqotherdistfile\*(Aq };
\&
\&    # This calls
\&    my $coderef = File::ShareDir::ProjectDistDir\->build_dist_file(
\&      \*(Aqdist_file\*(Aq,
\&      { distname => \*(Aqexample\-dist\*(Aq },
\&      { defaults => { filename => \*(Aqpath/to/yourcallingfile.pm\*(Aq, projectdir => \*(Aqshare\*(Aq } },
\&    );
\&    my $othercoderef = File::ShareDir::ProjectDistDir\->build_dist_file(
\&      \*(Aqdist_file\*(Aq,
\&      { distname => \*(Aqother\-dist\*(Aq },
\&      { defaults => { filename => \*(Aqpath/to/yourcallingfile.pm\*(Aq, projectdir => \*(Aqshare\*(Aq } },
\&    );
\&
\&    # And leverages Sub::Exporter to create 2 subs in your package.
.Ve
.PP
Generates the 'dist_file' method.
.PP
In development environments, the generated method will return
a path to the development directories 'share' directory. In non-development environments, this simply returns
\&\f(CW\*(C`File::ShareDir::dist_file\*(C'\fR.
.PP
Caveats as a result of package-name as stated in \*(L"build_dist_dir\*(R" also apply to this method.
.SH "SIGNIFICANT CHANGES"
.IX Header "SIGNIFICANT CHANGES"
.SS "1.000000"
.IX Subsection "1.000000"
\fIStrict Mode.\fR
.IX Subsection "Strict Mode."
.PP
Using Strict Mode
.IX Subsection "Using Strict Mode"
.PP
.Vb 2
\&    use File::ShareDir::ProjectDistDir \*(Aq:all\*(Aq, strict => 1;
\&    use File::ShareDir::ProjectDistDir \*(Aqdist_dir\*(Aq => { defaults => { strict => 1 }};
.Ve
.PP
Why you should use strict mode
.IX Subsection "Why you should use strict mode"
.PP
Starting with \f(CW1.000000\fR, there is a parameter \f(CW\*(C`strict\*(C'\fR that changes
how \f(CW\*(C`sharedir\*(C'\fR resolution performs.
.PP
Without strict:
.PP
.Vb 2
\&    lib/...
\&    share/...
.Ve
.PP
With strict
.PP
.Vb 2
\&    lib/...
\&    share/dist/Dist\-Name\-Here/...
.Ve
.PP
This technique greatly builds resilience to the long standing problem
with \*(L"develop\*(R" vs \*(L"install\*(R" heuristic ambiguity.
.PP
Here at least,
.PP
.Vb 1
\&    dist_dir(\*(AqDist\-Name\*(Aq)
.Ve
.PP
Will instead fall back to
.PP
.Vb 1
\&    @INC/auto/share/dist/Dist\-Name
.Ve
.PP
When
.PP
.Vb 1
\&    share/dist/Dist\-Name
.Ve
.PP
Does not exist.
.PP
This means if you have a layout like this:
.PP
.Vb 2
\&    <DEVROOT>/inc/<a local::lib path here>
\&    <DEVROOT>/lib/<development files here>
.Ve
.PP
Then when \f(CW\*(C`Foo\-Bar\-Baz\*(C'\fR is installed as:
.PP
.Vb 2
\&    <DEVROOT>/inc/lib/Foo/Bar/Baz.pm
\&    <DEVROOT>/inc/lib/auto/share/dist/Foo\-Bar\-Baz
.Ve
.PP
Then \f(CW\*(C`Baz.pm\*(C'\fR will not see the \f(CW\*(C`DEVROOT\*(C'\fR and assume \*(L"Hey, this is development\*(R" and then proceed to try finding files in
\&\f(CW\*(C`DEVROOT/share\*(C'\fR
.PP
Instead, \f(CW\*(C`DEVROOT\*(C'\fR must have \f(CW\*(C`DEVROOT/share/dist/Foo\-Bar\-Baz\*(C'\fR too, otherwise it reverts
to \f(CW\*(C`DEVROOT/inc/lib/auto...\*(C'\fR
.PP
\fI\f(CI\*(C`Path::Class\*(C'\fI interfaces deprecated and dependency dropped.\fR
.IX Subsection "Path::Class interfaces deprecated and dependency dropped."
.PP
If you have any dependence on this function, now is the time to get yourself off it.
.PP
Minimum Changes to stay with \f(CW\*(C`Path::Class\*(C'\fR short term.
.IX Subsection "Minimum Changes to stay with Path::Class short term."
.PP
As the dependency has been dropped on \f(CW\*(C`Path::Class\*(C'\fR, if you have \f(CW\*(C`CPAN\*(C'\fR
modules relying on \f(CW\*(C`Path::Class\*(C'\fR interface, you should now at a very minimum
start declaring
.PP
.Vb 1
\&    { requires => "Path::Class" }
.Ve
.PP
This will keep your dist working, but will not be future proof against further changes.
.PP
Staying with \f(CW\*(C`Path::Class\*(C'\fR long term.
.IX Subsection "Staying with Path::Class long term."
.PP
Recommended approach if you want to stay using the \f(CW\*(C`Path::Class\*(C'\fR interface:
.PP
.Vb 2
\&    use File::ShareDir::... etc
\&    use Path::Class qw( dir file );
\&
\&    my $dir = dir( dist_dir(\*(AqDist\-Name\*(Aq) );
.Ve
.PP
This should future-proof you against anything File::ShareDir may do in the future.
.PP
\fI\f(CI\*(C`Versioning Scheme arbitrary converted to float\*(C'\fI\fR
.IX Subsection "Versioning Scheme arbitrary converted to float"
.PP
This change is a superficial one, and should have no bearing on how significant you think this release is.
.PP
It is a significant release, but the primary reason for the version change is simply to avoid compatibility issues in
\&\fIversions themselves\fR.
.PP
However, outside that, \f(CW\*(C`x.y.z\*(C'\fR semantics are still intended to be semi-meaningful, just with less \f(CW\*(C`.\*(C'\fR and more \f(CW0\fR X
.PP
\fI\f(CI\*(C`dev\*(C'\fI path determination now deferred to call time instead of \f(CI\*(C`use\*(C'\fI\fR
.IX Subsection "dev path determination now deferred to call time instead of use"
.PP
This was essentially a required change to make \f(CW\*(C`strict\*(C'\fR mode plausible, because strict mode _requires_ the \f(CW\*(C`distname\*(C'\fR to be
known, even in the development environment.
.PP
This should not have any user visible effects, but please, if you have any problems, file a bug.
.PP
\fI\f(CI\*(C`file\*(C'\fI component determination wrested from \f(CI\*(C`File::ShareDir\*(C'\fI.\fR
.IX Subsection "file component determination wrested from File::ShareDir."
.PP
.Vb 1
\&    dist_file(\*(Aqfoo\*(Aq,\*(Aqbar\*(Aq)
.Ve
.PP
Is now simply sugar syntax for
.PP
.Vb 1
\&    path(dist_dir(\*(Aqfoo\*(Aq))\->child(\*(Aqbar\*(Aq)
.Ve
.PP
This should have no side effects in your code, but please file any bugs you experience.
.PP
( return value is still \f(CW\*(C`undef\*(C'\fR if the file does not exist, and still \f(CW\*(C`croak\*(C'\fR's if the file is not a file, or unreadable, but
these may both be subject to change )
.SS "0.5.0 \- Heuristics and Return type changes"
.IX Subsection "0.5.0 - Heuristics and Return type changes"
\fINew \f(CI\*(C`devdir\*(C'\fI heuristic\fR
.IX Subsection "New devdir heuristic"
.PP
Starting with 0.5.0, instead of using our simple \f(CW\*(C`lib/../share\*(C'\fR pattern heuristic, a more
advanced heuristic is used from the new \f(CW\*(C`Path::FindDev\*(C'\fR and \f(CW\*(C`Path::IsDev\*(C'\fR.
.PP
This relies on a more \*(L"concrete\*(R" marker somewhere at the top of your development tree, and more importantly, checks for the
existence of specific files that are not likely to occur outside a project root.
.PP
\&\f(CW\*(C`lib\*(C'\fR and \f(CW\*(C`share\*(C'\fR based heuristics were a little fragile, for a few reasons:
.IP "\(bu" 4
\&\f(CW\*(C`lib\*(C'\fR can, and does appear all over \s-1UNIX\s0 file systems, for purposes \fBother\fR than development project roots.
.Sp
For instance, have a look in \f(CW\*(C`/usr/\*(C'\fR
.Sp
.Vb 3
\&    /usr/bin
\&    /usr/lib
\&    /usr/share  ## UHOH.
.Ve
.Sp
This would have the very bad side effect of anything installed in \f(CW\*(C`/usr/lib\*(C'\fR thinking its \*(L"in development\*(R".
.Sp
Fortunately, nobody seems to have hit this specific bug, which I suspect is due only to \f(CW\*(C`/usr/lib\*(C'\fR being a symbolic link on most
x86_64 systems.
.IP "\(bu" 4
\&\f(CW\*(C`lib\*(C'\fR is also reasonably common within \f(CW\*(C`CPAN\*(C'\fR package names.
.Sp
For instance:
.Sp
.Vb 1
\&    lib::abs
.Ve
.Sp
Which means you'll have a hierarchy like:
.Sp
.Vb 1
\&    $PREFIX/lib/lib/abs
.Ve
.Sp
All you need for something to go horribly wrong would be for somebody to install a \f(CW\*(C`CPAN\*(C'\fR module named:
.Sp
.Vb 1
\&    share::mystuff
.Ve
.Sp
Or similar, and instantly, you have:
.Sp
.Vb 2
\&    $PREFIX/lib/lib/
\&    $PREFIX/lib/share/
.Ve
.Sp
Which would mean any module calling itself \f(CW\*(C`lib::*\*(C'\fR would be unable to use this module.
.PP
So instead, as of \f(CW0.5.0\fR, the heuristic revolves around certain specific files being in the \f(CW\*(C`dev\*(C'\fR directory.
.PP
Which is hopefully a more fault resilient mechanism.
.PP
\fINew Return Types\fR
.IX Subsection "New Return Types"
.PP
Starting with 0.5.0, the internals are now based on \f(CW\*(C`Path::Tiny\*(C'\fR instead of \f(CW\*(C`Path::Class\*(C'\fR,
and as a result, there may be a few glitches in transition.
.PP
Also, previously you could get a \f(CW\*(C`Path::Class::*\*(C'\fR object back from \f(CW\*(C`dist_dir\*(C'\fR and \f(CW\*(C`dist_file\*(C'\fR by importing it as such:
.PP
.Vb 3
\&    use File::ShareDir::ProjectDistDir
\&        qw( dist_dir dist_file ),
\&        defaults => { pathclass => 1 };
.Ve
.PP
Now you can also get \f(CW\*(C`Path::Tiny\*(C'\fR objects back, by passing:
.PP
.Vb 3
\&    use File::ShareDir::ProjectDistDir
\&        qw( dist_dir dist_file ),
\&        defaults => { pathtiny => 1 };
.Ve
.PP
\&\fBFor the time being, you can still get Path::Class objects back, it is deprecated since 1.000000\fR
.PP
( In fact, I may even make 2 specific sub-classes of \f(CW\*(C`PDD\*(C'\fR for people who want objects back, as it will make the \f(CW\*(C`API\*(C'\fR and the
code much cleaner )
.SH "AUTHOR"
.IX Header "AUTHOR"
Kent Fredric <kentnl@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2014 by Kent Fredric <kentnl@cpan.org>.
.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.