1File::ShareDir(3)     User Contributed Perl Documentation    File::ShareDir(3)
2
3
4

NAME

6       File::ShareDir - Locate per-dist and per-module shared files
7

SYNOPSIS

9         use File::ShareDir ':ALL';
10
11         # Where are distribution-level shared data files kept
12         $dir = dist_dir('File-ShareDir');
13
14         # Where are module-level shared data files kept
15         $dir = module_dir('File::ShareDir');
16
17         # Find a specific file in our dist/module shared dir
18         $file = dist_file(  'File-ShareDir',  'file/name.txt');
19         $file = module_file('File::ShareDir', 'file/name.txt');
20
21         # Like module_file, but search up the inheritance tree
22         $file = class_file( 'Foo::Bar', 'file/name.txt' );
23

DESCRIPTION

25       The intent of File::ShareDir is to provide a companion to
26       Class::Inspector and File::HomeDir, modules that take a process that is
27       well-known by advanced Perl developers but gets a little tricky, and
28       make it more available to the larger Perl community.
29
30       Quite often you want or need your Perl module (CPAN or otherwise) to
31       have access to a large amount of read-only data that is stored on the
32       file-system at run-time.
33
34       On a linux-like system, this would be in a place such as /usr/share,
35       however Perl runs on a wide variety of different systems, and so the
36       use of any one location is unreliable.
37
38       Perl provides a little-known method for doing this, but almost nobody
39       is aware that it exists. As a result, module authors often go through
40       some very strange ways to make the data available to their code.
41
42       The most common of these is to dump the data out to an enormous Perl
43       data structure and save it into the module itself. The result are
44       enormous multi-megabyte .pm files that chew up a lot of memory
45       needlessly.
46
47       Another method is to put the data "file" after the __DATA__ compiler
48       tag and limit yourself to access as a filehandle.
49
50       The problem to solve is really quite simple.
51
52         1. Write the data files to the system at install time.
53
54         2. Know where you put them at run-time.
55
56       Perl's install system creates an "auto" directory for both every
57       distribution and for every module file.
58
59       These are used by a couple of different auto-loading systems to store
60       code fragments generated at install time, and various other modules
61       written by the Perl "ancient masters".
62
63       But the same mechanism is available to any dist or module to store any
64       sort of data.
65
66   Using Data in your Module
67       "File::ShareDir" forms one half of a two part solution.
68
69       Once the files have been installed to the correct directory, you can
70       use "File::ShareDir" to find your files again after the installation.
71
72       For the installation half of the solution, see File::ShareDir::Install
73       and its "install_share" directive.
74
75       Using File::ShareDir::Install together with File::ShareDir allows one
76       to rely on the files in appropriate "dist_dir()" or "module_dir()" in
77       development phase, too.
78

FUNCTIONS

80       "File::ShareDir" provides four functions for locating files and
81       directories.
82
83       For greater maintainability, none of these are exported by default and
84       you are expected to name the ones you want at use-time, or provide the
85       ':ALL' tag. All of the following are equivalent.
86
87         # Load but don't import, and then call directly
88         use File::ShareDir;
89         $dir = File::ShareDir::dist_dir('My-Dist');
90
91         # Import a single function
92         use File::ShareDir 'dist_dir';
93         dist_dir('My-Dist');
94
95         # Import all the functions
96         use File::ShareDir ':ALL';
97         dist_dir('My-Dist');
98
99       All of the functions will check for you that the dir/file actually
100       exists, and that you have read permissions, or they will throw an
101       exception.
102
103   dist_dir
104         # Get a distribution's shared files directory
105         my $dir = dist_dir('My-Distribution');
106
107       The "dist_dir" function takes a single parameter of the name of an
108       installed (CPAN or otherwise) distribution, and locates the shared data
109       directory created at install time for it.
110
111       Returns the directory path as a string, or dies if it cannot be located
112       or is not readable.
113
114   module_dir
115         # Get a module's shared files directory
116         my $dir = module_dir('My::Module');
117
118       The "module_dir" function takes a single parameter of the name of an
119       installed (CPAN or otherwise) module, and locates the shared data
120       directory created at install time for it.
121
122       In order to find the directory, the module must be loaded when calling
123       this function.
124
125       Returns the directory path as a string, or dies if it cannot be located
126       or is not readable.
127
128   dist_file
129         # Find a file in our distribution shared dir
130         my $dir = dist_file('My-Distribution', 'file/name.txt');
131
132       The "dist_file" function takes two parameters of the distribution name
133       and file name, locates the dist directory, and then finds the file
134       within it, verifying that the file actually exists, and that it is
135       readable.
136
137       The filename should be a relative path in the format of your local
138       filesystem. It will simply added to the directory using File::Spec's
139       "catfile" method.
140
141       Returns the file path as a string, or dies if the file or the dist's
142       directory cannot be located, or the file is not readable.
143
144   module_file
145         # Find a file in our module shared dir
146         my $dir = module_file('My::Module', 'file/name.txt');
147
148       The "module_file" function takes two parameters of the module name and
149       file name. It locates the module directory, and then finds the file
150       within it, verifying that the file actually exists, and that it is
151       readable.
152
153       In order to find the directory, the module must be loaded when calling
154       this function.
155
156       The filename should be a relative path in the format of your local
157       filesystem. It will simply added to the directory using File::Spec's
158       "catfile" method.
159
160       Returns the file path as a string, or dies if the file or the dist's
161       directory cannot be located, or the file is not readable.
162
163   class_file
164         # Find a file in our module shared dir, or in our parent class
165         my $dir = class_file('My::Module', 'file/name.txt');
166
167       The "module_file" function takes two parameters of the module name and
168       file name. It locates the module directory, and then finds the file
169       within it, verifying that the file actually exists, and that it is
170       readable.
171
172       In order to find the directory, the module must be loaded when calling
173       this function.
174
175       The filename should be a relative path in the format of your local
176       filesystem. It will simply added to the directory using File::Spec's
177       "catfile" method.
178
179       If the file is NOT found for that module, "class_file" will scan up the
180       module's @ISA tree, looking for the file in all of the parent classes.
181
182       This allows you to, in effect, "subclass" shared files.
183
184       Returns the file path as a string, or dies if the file or the dist's
185       directory cannot be located, or the file is not readable.
186

EXTENDING

188   Overriding Directory Resolution
189       "File::ShareDir" has two convenience hashes for people who have
190       advanced usage requirements of "File::ShareDir" such as using
191       uninstalled "share" directories during development.
192
193         #
194         # Dist-Name => /absolute/path/for/DistName/share/dir
195         #
196         %File::ShareDir::DIST_SHARE
197
198         #
199         # Module::Name => /absolute/path/for/Module/Name/share/dir
200         #
201         %File::ShareDir::MODULE_SHARE
202
203       Setting these values any time before the corresponding calls
204
205         dist_dir('Dist-Name')
206         dist_file('Dist-Name','some/file');
207
208         module_dir('Module::Name');
209         module_file('Module::Name','some/file');
210
211       Will override the base directory for resolving those calls.
212
213       An example of where this would be useful is in a test for a module that
214       depends on files installed into a share directory, to enable the tests
215       to use the development copy without needing to install them first.
216
217         use File::ShareDir;
218         use Cwd qw( getcwd );
219         use File::Spec::Functions qw( rel2abs catdir );
220
221         $File::ShareDir::MODULE_SHARE{'Foo::Module'} = rel2abs(catfile(getcwd,'share'));
222
223         use Foo::Module;
224
225         # interal calls in Foo::Module to module_file('Foo::Module','bar') now resolves to
226         # the source trees share/ directory instead of something in @INC
227

SUPPORT

229       Bugs should always be submitted via the CPAN request tracker, see
230       below.
231
232       You can find documentation for this module with the perldoc command.
233
234           perldoc File::ShareDir
235
236       You can also look for information at:
237
238       ·   RT: CPAN's request tracker
239
240           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=File-ShareDir>
241
242       ·   AnnoCPAN: Annotated CPAN documentation
243
244           <http://annocpan.org/dist/File-ShareDir>
245
246       ·   CPAN Ratings
247
248           <http://cpanratings.perl.org/s/File-ShareDir>
249
250       ·   CPAN Search
251
252           <http://search.cpan.org/dist/File-ShareDir/>
253
254   Where can I go for other help?
255       If you have a bug report, a patch or a suggestion, please open a new
256       report ticket at CPAN (but please check previous reports first in case
257       your issue has already been addressed).
258
259       Report tickets should contain a detailed description of the bug or
260       enhancement request and at least an easily verifiable way of
261       reproducing the issue or fix. Patches are always welcome, too.
262
263   Where can I go for help with a concrete version?
264       Bugs and feature requests are accepted against the latest version only.
265       To get patches for earlier versions, you need to get an agreement with
266       a developer of your choice - who may or not report the issue and a
267       suggested fix upstream (depends on the license you have chosen).
268
269   Business support and maintenance
270       For business support you can contact the maintainer via his CPAN email
271       address. Please keep in mind that business support is neither available
272       for free nor are you eligible to receive any support based on the
273       license distributed with this package.
274

AUTHOR

276       Adam Kennedy <adamk@cpan.org>
277
278   MAINTAINER
279       Jens Rehsack <rehsack@cpan.org>
280

SEE ALSO

282       File::ShareDir::Install, File::ConfigDir, File::HomeDir,
283       Module::Install, Module::Install::Share, File::ShareDir::PAR,
284       Dist::Zilla::Plugin::ShareDir
285
287       Copyright 2005 - 2011 Adam Kennedy, Copyright 2014 - 2018 Jens Rehsack.
288
289       This program is free software; you can redistribute it and/or modify it
290       under the same terms as Perl itself.
291
292       The full text of the license can be found in the LICENSE file included
293       with this module.
294
295
296
297perl v5.30.0                      2019-07-26                 File::ShareDir(3)
Impressum