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

NAME

6       Test::File::ShareDir - Create a Fake ShareDir for your modules for
7       testing.
8

VERSION

10       version 1.001002
11

SYNOPSIS

13           use Test::More;
14
15           # use FindBin; optional
16
17           use Test::File::ShareDir
18               # -root => "$FindBin::Bin/../" # optional,
19               -share => {
20                   -module => { 'My::Module' => 'share/MyModule' }
21                   -dist   => { 'My-Dist'    => 'share/somefolder' }
22               };
23
24           use My::Module;
25
26           use File::ShareDir qw( module_dir dist_dir );
27
28           module_dir( 'My::Module' ) # dir with files from $dist/share/MyModule
29
30           dist_dir( 'My-Dist' ) # dir with files from $dist/share/somefolder
31

DESCRIPTION

33       "Test::File::ShareDir" is some low level plumbing to enable a
34       distribution to perform tests while consuming its own "share"
35       directories in a manner similar to how they will be once installed.
36
37       This allows "File::ShareDir" to see the latest version of content
38       instead of simply whatever is installed on whichever target system you
39       happen to be testing on.
40
41       Note: This module only has support for creating 'new' style share dirs
42       and are NOT compatible with old File::ShareDirs.
43
44       For this reason, unless you have File::ShareDir 1.00 or later
45       installed, this module will not be usable by you.
46

SIMPLE INTERFACE

48       Starting with version 0.4.0, there are a few extra interfaces you can
49       use.
50
51       These will probably be more useful, and easier to grok, because they
52       don't have a layer of indirection in order to simultaneously support
53       both "Module" and "Dist" "ShareDir"'s.
54
55   Simple Exporter Interfaces
56       "Test::File::ShareDir::Dist"
57
58       "Test::File::ShareDir::Dist" provides a simple export interface for
59       making "TempDir" "ShareDir"'s from a given path:
60
61           use Test::File::ShareDir::Dist { "Dist-Name" => "share/" };
62
63       This will automatically create a "ShareDir" for "Dist-Name" in a
64       "TempDir" based on the contents of "CWD/share/"
65
66       See "Test::File::ShareDir::Dist" for details.
67
68       "Test::File::ShareDir::Module"
69
70       "Test::File::ShareDir::Module" provides a simple export interface for
71       making "TempDir" "ShareDir"'s from a given path:
72
73           use Test::File::ShareDir::Module { "Module::Name" => "share/" };
74
75       This will automatically create a "ShareDir" for "Module::Name" in a
76       "TempDir" based on the contents of "CWD/share/"
77
78       See "Test::File::ShareDir::Module" for details.
79
80   Simple Object Oriented Interfaces
81       "Test::File::ShareDir::Object::Dist"
82
83       "Test::File::ShareDir::Object::Dist" provides a simple object oriented
84       interface for making "TempDir" "ShareDir"'s from a given path:
85
86           use Test::File::ShareDir::Object::Dist;
87
88           my $obj = Test::File::ShareDir::Object::Dist->new( dists => { "Dist-Name" => "share/" } );
89           $obj->install_all_dists;
90           $obj->register;
91
92       This will automatically create a "ShareDir" for "Dist-Name" in a
93       "TempDir" based on the contents of "CWD/share/"
94
95       See "Test::File::ShareDir::Object::Dist" for details.
96
97       "Test::File::ShareDir::Object::Module"
98
99       "Test::File::ShareDir::Object::Module" provides a simple object
100       oriented interface for making "TempDir" "ShareDir"'s from a given path:
101
102           use Test::File::ShareDir::Object::Module;
103
104           my $obj = Test::File::ShareDir::Object::Module->new( modules => { "Module::Name" => "share/" } );
105           $obj->install_all_modules;
106           $obj->register;
107
108       This will automatically create a "ShareDir" for "Module::Name" in a
109       "TempDir" based on the contents of "CWD/share/"
110
111       See "Test::File::ShareDir::Object::Module" for details.
112

SCOPE LIMITED UTILITIES

114       "Test::File::ShareDir" provides a few utility functions to aide in
115       temporarily adjusting "ShareDir" behavior.
116
117           use Test::File::ShareDir qw( with_dist_dir with_module_dir );
118
119           with_dist_dir({ 'Dist-Name' => 'Some/Path' }, sub {
120             # dist_dir() now behaves differently here
121           });
122           with_module_dir({ 'Module::Name' => 'Some/Path' }, sub {
123             # module_dir() now behaves differently here
124           });
125
126       See "EXPORTABLE FUNCTIONS" for details.
127

IMPORTING

129       Since 1.001000, there are 2 ways of passing arguments to "import"
130
131         use Foo { -root => ... options }, qw( functions to import );
132         use Foo -optname => option, -optname => option, qw( functions to import );
133
134       Both should work, but the former might be less prone to accidental
135       issues.
136
137   IMPORT OPTIONS
138       -root
139
140       This parameter is the prefix the other paths are relative to.
141
142       If this parameter is not specified, it defaults to the Current Working
143       Directory ( "CWD" ).
144
145       In versions prior to 0.3.0, this value was mandatory.
146
147       The rationale behind using "CWD" as the default value is as follows.
148
149       •   Most users of this module are likely to be using it to test
150           distributions
151
152       •   Most users of this module will be using it in "$project/t/" to load
153           files from "$project/share/"
154
155       •   Most "CPAN" tools run tests with "CWD" = $project
156
157       Therefor, defaulting to "CWD" is a reasonably sane default for most
158       people, but where it is not it can still be overridden.
159
160         -root => "$FindBin::Bin/../" # resolves to project root from t/ regardless of Cwd.
161
162       -share
163
164       This parameter is mandatory, and contains a "hashref" containing the
165       data that explains what directories you want shared.
166
167         -share =>  { ..... }
168
169       -module
170
171       "-module" contains a "hashref" mapping Module names to path names for
172       module_dir style share dirs.
173
174         -share => {
175           -module => { 'My::Module' => 'share/mymodule/', }
176         }
177
178         ...
179
180         module_dir('My::Module')
181
182       Notedly, it is a "hashref", which means there is a limitation of one
183       share dir per module. This is simply because having more than one share
184       dir per module makes no sense at all.
185
186       -dist
187
188       "-dist" contains a "hashref" mapping Distribution names to path names
189       for dist_dir style share dirs. The same limitation applied to "-module"
190       applies here.
191
192         -share => {
193           -dist => { 'My-Dist' => 'share/mydist' }
194         }
195         ...
196         dist_dir('My-Dist')
197

EXPORTABLE FUNCTIONS

199   with_dist_dir
200       Sets up a "ShareDir" environment with limited context.
201
202         # with_dist_dir(\%config, \&sub);
203         with_dist_dir( { 'Dist-Name' => 'share/' } => sub {
204
205             # File::ShareDir resolves to a copy of share/ in this context.
206
207         } );
208
209       %config can contain anything "Test::File::ShareDir::Dist" accepts.
210
211       "-root": Defaults to $CWD
212       "$distName": Declare $distName's "ShareDir".
213
214       Since 1.001000
215
216   with_module_dir
217       Sets up a "ShareDir" environment with limited context.
218
219         # with_module_dir(\%config, \&sub);
220         with_module_dir( { 'Module::Name' => 'share/' } => sub {
221
222             # File::ShareDir resolves to a copy of share/ in this context.
223
224         } );
225
226       %config can contain anything "Test::File::ShareDir::Module" accepts.
227
228       "-root": Defaults to $CWD
229       "$moduleName": Declare $moduleName's "ShareDir".
230
231       Since 1.001000
232

THANKS

234       Thanks to the "#distzilla" crew for ideas,suggestions, code review and
235       debugging, even though not all of it made it into releases.
236
237       •   DOLMEN <cpan:///author/dolmen>
238
239       •   ETHER <cpan:///author/ether>
240
241       •   HAARG <cpan:///author/haarg>
242
243       •   RJBS <cpan:///author/rjbs>
244

AUTHOR

246       Kent Fredric <kentnl@cpan.org>
247

249       This software is copyright (c) 2017 by Kent Fredric <kentnl@cpan.org>.
250
251       This is free software; you can redistribute it and/or modify it under
252       the same terms as the Perl 5 programming language system itself.
253
254
255
256perl v5.32.1                      2021-01-27           Test::File::ShareDir(3)
Impressum