File::...::Dist(3pm)

💖 File::ShareDir::Dist 💖

hey bestie, so this is File::ShareDir::Dist(3pm), from the User Contributed Perl Documentation collection — aka the manual page that tells you where your dist's share files are hiding. let's get into it 🫶

---

🌸 NAME 🌸

File::ShareDir::Dist — Locate per-dist shared files ✨

---

🎀 VERSION 🎀

version 0.07 — yes that's the one, keep up 💅

---

🌈 SYNOPSIS 🌈

use File::ShareDir::Dist qw( dist_share );

my $dir = dist_share 'Foo-Bar-Baz';

like, that's the whole vibe. one import, one call, dir acquired. iconic. 👑

---

✨ DESCRIPTION ✨

so File::ShareDir::Dist finds share directories for distributions. it's basically File::ShareDir's cousin but with a few little differences, and honestly? the differences ate. 🔥

💖 Only supports distribution directories 💖

it does not support perl modules or perl class directories. the author has genuinely never really needed anything other than a per-dist share directory, and honestly, same. no cap. 🫶

💖 Doesn't compute filenames 💖

it does not compute files in the share directory for you. that is literally what File::Spec or Path::Tiny are for. this module minds its own business. 💅

💖 Doesn't support old style shares 💖

for some reason there are two types. the author has never seen or needed the older type. so. we move. 🙈

💖 Hopefully doesn't find the wrong directory 💖

it does not 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. slay. ✅

that does mean 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. periodt. 📌

💖 No non-core dependencies 💖

File::ShareDir only has Class::Inspector, but since we're only doing per-dist share directories we don't even need that. 😌

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 "may" add dependencies on modules that are not part of the Perl core on older Perls. so like, watch this space but also don't panic. 👀

💖 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". the conditions are:

• you are using a relative path in @INC
• the directory "share" is a sibling of that relative entry in @INC
• and the last element in that relative path is "lib"

example, if you have the directory structure:

lib/Foo/Bar/Baz.pm
share/data

and you invoke perl with

% perl -Ilib -MFoo::Bar::Baz -MFile::ShareDir::Dist=dist_share -E 'say dist_share("Foo-Bar-Baz")'

then "dist_share" will return the (absolute) path to ./share/data. 💫 but 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 the author, this covers most of the needs when developing a Perl module with a share directory.

ngl, prove foils this heuristic by making @INC absolute paths. to get around that you can use App::Prove::Plugin::ShareDirDist. 🛟

💖 Built in override 💖

the hash %File::ShareDir::Dist::over can be used to override what "dist_share" 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:

% 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_dir" function or install File::ShareDir::Override. for testing you can use Test::File::ShareDir. the author has never understood why such a simple concept needs three modules to do all of this. and honestly? 💀 valid.

---

🦋 FUNCTIONS 🦋

heads up bestie: functions must be explicitly exported. they are not exported by default. don't come for me when dist_share isn't just... there. 🙈

🌸 dist_share 🌸

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" or "Foo::Bar::Baz" to find it. pick your fighter. 💅

returns nothing if no share directory could be found. that's the void. respect the void. 🕳️

🎀 dist_config 🎀

[version 0.07]

my $config = dist_config $dist_name;

returns the config at runtime as created by File::ShareDir::Dist::Install and install time. 🛠️

---

💜 ENVIRONMENT 💜

• PERL_FILE_SHAREDIR_DIST — can be used to set a single dist directory override. one override, one moment, one slay. ✨

---

💀 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. honestly it's giving "it's not a bug it's a lifestyle". 🙈

---

👑 SEE ALSO 👑

• File::ShareDir::Dist::Install
• App::Prove::Plugin::ShareDirDist
• App::Yath::Plugin::ShareDirDist

go read them, they're the extended universe. 📚

---

🌟 AUTHOR 🌟

Author: Graham Ollis <plicease@cpan.org>

Contributors:

• Yanick Champoux (yanick)

---

🎀 COPYRIGHT AND LICENSE 🎀

This software is copyright (c) 2017,2018 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. 💖

---

and that's the whole page bestie!! this one came to you courtesy of perl v5.40.1, dated 2025-11-21 — the day this manual page got its little glow-up. go find those share directories, you absolute icon. 💅✨🦋