1File::ShareDir(3) User Contributed Perl Documentation File::ShareDir(3)
2
6 File::ShareDir - Locate per-dist and per-module shared files
7
9 use File::ShareDir ':ALL';
10 # Where are distribution-level shared data files kept
12 $dir = dist_dir('File-ShareDir');
13 # Where are module-level shared data files kept
15 $dir = module_dir('File::ShareDir');
16 # 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 # Like module_file, but search up the inheritance tree
22 $file = class_file( 'Foo::Bar', 'file/name.txt' );
23
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 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 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 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 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 Another method is to put the data "file" after the __DATA__ compiler
48 tag and limit yourself to access as a filehandle.
49 The problem to solve is really quite simple.
51 1. Write the data files to the system at install time.
53 2. Know where you put them at run-time.
55 Perl's install system creates an "auto" directory for both every
57 distribution and for every module file.
58 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 But the same mechanism is available to any dist or module to store any
64 sort of data.
65 Using Data in your Module
67 "File::ShareDir" forms one half of a two part solution.
68 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 For the installation half of the solution, see File::ShareDir::Install
73 and its "install_share" directive.
74 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
80 "File::ShareDir" provides four functions for locating files and
81 directories.
82 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 # Load but don't import, and then call directly
88 use File::ShareDir;
89 $dir = File::ShareDir::dist_dir('My-Dist');
90 # Import a single function
92 use File::ShareDir 'dist_dir';
93 dist_dir('My-Dist');
94 # Import all the functions
96 use File::ShareDir ':ALL';
97 dist_dir('My-Dist');
98 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 dist_dir
104 # Get a distribution's shared files directory
105 my $dir = dist_dir('My-Distribution');
106 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 Returns the directory path as a string, or dies if it cannot be located
112 or is not readable.
113 module_dir
115 # Get a module's shared files directory
116 my $dir = module_dir('My::Module');
117 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 In order to find the directory, the module must be loaded when calling
123 this function.
124 Returns the directory path as a string, or dies if it cannot be located
126 or is not readable.
127 dist_file
129 # Find a file in our distribution shared dir
130 my $dir = dist_file('My-Distribution', 'file/name.txt');
131 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 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 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 module_file
145 # Find a file in our module shared dir
146 my $dir = module_file('My::Module', 'file/name.txt');
147 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 In order to find the directory, the module must be loaded when calling
154 this function.
155 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 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 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 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 In order to find the directory, the module must be loaded when calling
173 this function.
174 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 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 This allows you to, in effect, "subclass" shared files.
183 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
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 #
194 # Dist-Name => /absolute/path/for/DistName/share/dir
195 #
196 %File::ShareDir::DIST_SHARE
197 #
199 # Module::Name => /absolute/path/for/Module/Name/share/dir
200 #
201 %File::ShareDir::MODULE_SHARE
202 Setting these values any time before the corresponding calls
204 dist_dir('Dist-Name')
206 dist_file('Dist-Name','some/file');
207 module_dir('Module::Name');
209 module_file('Module::Name','some/file');
210 Will override the base directory for resolving those calls.
212 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 use File::ShareDir;
218 use Cwd qw( getcwd );
219 use File::Spec::Functions qw( rel2abs catdir );
220 $File::ShareDir::MODULE_SHARE{'Foo::Module'} = rel2abs(catfile(getcwd,'share'));
222 use Foo::Module;
224 # internal 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
229 Bugs should always be submitted via the CPAN request tracker, see
230 below.
231 You can find documentation for this module with the perldoc command.
233 perldoc File::ShareDir
235 You can also look for information at:
237 • RT: CPAN's request tracker
239 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=File-ShareDir>
241 • AnnoCPAN: Annotated CPAN documentation
243 <http://annocpan.org/dist/File-ShareDir>
245 • CPAN Ratings
247 <http://cpanratings.perl.org/s/File-ShareDir>
249 • CPAN Search
251 <http://search.cpan.org/dist/File-ShareDir/>
253 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 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 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 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
276 Adam Kennedy <adamk@cpan.org>
277 MAINTAINER
279 Jens Rehsack <rehsack@cpan.org>
280
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 This program is free software; you can redistribute it and/or modify it
290 under the same terms as Perl itself.
291 The full text of the license can be found in the LICENSE file included
293 with this module.
294perl v5.36.0 2023-01-20 File::ShareDir(3)