1DBIx::Class::Schema::LoUasdeDerBrI:Cx:o:On:ptCtrliiaobsnusat:le::dS:cDPheeeprmelan:dD:eoLncocuaimdeeesnr(t:3a:)tOipotnional::Dependencies(3)
2
3
4

NAME

6       $class - Optional module dependency specifications (for module authors)
7       EOC
8
9       #@@ #@@ SYNOPSIS HEADING #@@
10         push @chunks, <<"EOC"; =head1 SYNOPSIS
11
12       Somewhere in your build-file (e.g. ExtUtils::MakeMaker's Makefile.PL):
13
14         ...
15
16         \$EUMM_ARGS{CONFIGURE_REQUIRES} = {
17           \%{ \$EUMM_ARGS{CONFIGURE_REQUIRES} || {} },
18           'DBIx::Class::Schema::Loader' => '$distver',
19         };
20
21         ...
22
23         my %DBIC_CONFIG_AND_ORACLE_DEPS = %{ eval {
24           require $class;
25           $class->req_list_for([qw( dbicdump_config rdbms_oracle )]);
26         } || {} };
27
28         \$EUMM_ARGS{PREREQ_PM} = {
29           \%DBIC_CONFIG_AND_ORACLE_DEPS,
30           \%{ \$EUMM_ARGS{PREREQ_PM} || {} },
31         };
32
33         ...
34
35         ExtUtils::MakeMaker::WriteMakefile(\%EUMM_ARGS);
36
37       Note: The "eval" protection within the example is due to support for
38       requirements during the "configure" build phase not being available on
39       a sufficient portion of production installations of Perl. Robust
40       support for such dependency requirements is available in the CPAN
41       installer only since version "1.94_56" first made available for
42       production with perl version 5.12. It is the belief of the current
43       maintainer that support for requirements during the "configure" build
44       phase will not be sufficiently ubiquitous until the year 2020 at the
45       earliest, hence the extra care demonstrated above. It should also be
46       noted that some 3rd party installers (e.g. cpanminus) do the right
47       thing with configure requirements independent from the versions of perl
48       and CPAN available.  EOC
49
50       #@@ #@@ DESCRIPTION HEADING #@@
51         push @chunks, <<'EOC'; =head1 DESCRIPTION
52
53       Some of the less-frequently used features of
54       DBIx::Class::Schema::Loader have external module dependencies on their
55       own. In order not to burden the average user with modules they will
56       never use, these optional dependencies are not included in the base
57       Makefile.PL. Instead an exception with a descriptive message is thrown
58       when a specific feature can't find one or several modules required for
59       its operation. This module is the central holding place for the current
60       list of such dependencies, for DBIx::Class::Schema::Loader core
61       authors, and DBIx::Class::Schema::Loader extension authors alike.
62
63       Dependencies are organized in groups where each group can list one or
64       more required modules, with an optional minimum version (or 0 for any
65       version). In addition groups prefixed with "test_" can specify a set of
66       environment variables, some (or all) of which are marked as required
67       for the group to be considered by "req_list_for"
68
69       Each group name (or a combination thereof) can be used in the public
70       methods as described below.  EOC
71
72       #@@ #@@ REQUIREMENT GROUPLIST HEADING #@@
73         push @chunks, '=head1 CURRENT REQUIREMENT GROUPS';
74
75         my $standalone_info;
76
77         for my $group (sort keys %$dbic_reqs) {
78
79           my $info = $standalone_info->{$group} ||= $class->_groups_to_reqs($group);
80
81           next unless (
82             $info->{modreqs_fully_documented}
83               and
84             ( $info->{augments} or $info->{modreqs} )
85           );
86
87           my $p = $dbic_reqs->{$group}{pod};
88
89           push @chunks, (
90             "=head2 $p->{title}",
91             "=head3 $group",
92             $p->{desc},
93             '=over',
94           );
95
96           if ( keys %{ $info->{modreqs}||{} } ) {
97             push @chunks, map
98               { "=item * $_" . ($info->{modreqs}{$_} ? " >= $info->{modreqs}{$_}" : '') }
99               ( sort keys %{ $info->{modreqs} } )
100             ;
101           }
102           else {
103             push @chunks, '=item * No standalone requirements',
104           }
105
106           push @chunks, '=back';
107
108           for my $ag ( sort keys %{ $info->{augments} || {} } ) {
109             my $ag_info = $standalone_info->{$ag} ||= $class->_groups_to_reqs($ag);
110
111             my $newreqs = $class->modreq_list_for([ $group, $ag ]);
112             for (keys %$newreqs) {
113               delete $newreqs->{$_} if (
114                 ( defined $info->{modreqs}{$_}    and $info->{modreqs}{$_}    == $newreqs->{$_} )
115                   or
116                 ( defined $ag_info->{modreqs}{$_} and $ag_info->{modreqs}{$_} == $newreqs->{$_} )
117               );
118             }
119
120             if (keys %$newreqs) {
121               push @chunks, (
122                 "Combined with L</$ag> additionally requires:",
123                 '=over',
124                 ( map
125                   { "=item * $_" . ($newreqs->{$_} ? " >= $newreqs->{$_}" : '') }
126                   ( sort keys %$newreqs )
127                 ),
128                 '=back',
129               );
130             }
131           }
132         }
133
134       #@@ #@@ API DOCUMENTATION HEADING #@@
135         push @chunks, <<'EOC';
136

IMPORT-LIKE ACTIONS

138       Even though this module is not an Exporter, it recognizes several
139       "actions" supplied to its "import" method.
140
141   -skip_all_without
142       Arguments: @group_names
143
144       A convenience wrapper for use during testing: EOC
145
146         push @chunks, " use $class -skip_all_without => qw(admin test_rdbms_mysql);";
147
148         push @chunks, 'Roughly equivalent to the following code:';
149
150         push @chunks, sprintf <<'EOS', ($class) x 2;
151
152        BEGIN {
153          require %s;
154          if ( my $missing = %s->req_missing_for(\@group_names_) ) {
155            print "1..0 # SKIP requirements not satisfied: $missing\n";
156            exit 0;
157          }
158        }
159       EOS
160
161         push @chunks, <<'EOC';
162
163       It also takes into account the "RELEASE_TESTING" environment variable
164       and behaves like "-die_without" for any requirement groups marked as
165       "release_testing_mandatory".
166
167   -die_without
168       Arguments: @group_names
169
170       A convenience wrapper around "die_unless_req_ok_for": EOC
171
172         push @chunks, " use $class -die_without => qw(deploy admin);";
173
174         push @chunks, <<'EOC';
175
176   -list_missing
177       Arguments: @group_names
178
179       A convenience wrapper around "modreq_missing_for":
180
181        perl -Ilib -MDBIx::Class::Schema::Loader::Optional::Dependencies=-list_missing,dbicdump_config,rdbms_oracle | cpanm
182

METHODS

184   req_group_list
185       Arguments: none
186       Return Value: \%list_of_requirement_groups
187
188       This method should be used by DBIx::Class::Schema::Loader packagers, to
189       get a hashref of all dependencies keyed by dependency group. Each key
190       (group name), or a combination thereof (as an arrayref) can be supplied
191       to the methods below.  The values of the returned hash are currently a
192       set of options without a well defined structure. If you have use for
193       any of the contents - contact the maintainers, instead of treating this
194       as public (left alone stable) API.
195
196   req_list_for
197       Arguments: $group_name | \@group_names
198       Return Value: \%set_of_module_version_pairs
199
200       This method should be used by DBIx::Class::Schema::Loader extension
201       authors, to determine the version of modules a specific set of features
202       requires for this version of DBIx::Class::Schema::Loader (regardless of
203       their availability on the system).  See the "SYNOPSIS" for a real-world
204       example.
205
206       When handling "test_*" groups this method behaves differently from
207       "modreq_list_for" below (and is the only such inconsistency among the
208       "req_*" methods). If a particular group declares as requirements some
209       "environment variables" and these requirements are not satisfied (the
210       envvars are unset) - then the "module requirements" of this group are
211       not included in the returned list.
212
213   modreq_list_for
214       Arguments: $group_name | \@group_names
215       Return Value: \%set_of_module_version_pairs
216
217       Same as "req_list_for" but does not take into consideration any
218       "environment variable requirements" - returns just the list of required
219       modules.
220
221   req_ok_for
222       Arguments: $group_name | \@group_names
223       Return Value: 1|0
224
225       Returns true or false depending on whether all modules/envvars required
226       by the group(s) are loadable/set on the system.
227
228   req_missing_for
229       Arguments: $group_name | \@group_names
230       Return Value: $error_message_string
231
232       Returns a single-line string suitable for inclusion in larger error
233       messages.  This method would normally be used by
234       DBIx::Class::Schema::Loader core features, to indicate to the user that
235       they need to install specific modules and/or set specific environment
236       variables before being able to use a specific feature set.
237
238       For example if some of the requirements for "deploy" are not available,
239       the returned string could look like: EOC
240
241         push @chunks, qq{ "Moose~$moosever" (see $class documentation for details)};
242
243         push @chunks, <<'EOC';
244       The author is expected to prepend the necessary text to this message before
245       returning the actual error seen by the user. See also L</modreq_missing_for>
246
247   modreq_missing_for
248       Arguments: $group_name | \@group_names
249       Return Value: $error_message_string
250
251       Same as "req_missing_for" except that the error string is guaranteed to
252       be either empty, or contain a set of module requirement specifications
253       suitable for piping to e.g. cpanminus. The method explicitly does not
254       attempt to validate the state of required environment variables (if
255       any).
256
257       For instance if some of the requirements for "deploy" are not
258       available, the returned string could look like: EOC
259
260         push @chunks, qq{ "Moose~$moosever"};
261
262         push @chunks, <<'EOC';
263
264       See also "-list_missing".
265
266   skip_without
267       Arguments: $group_name | \@group_names
268
269       A convenience wrapper around skip. It does not take neither a reason
270       (it is generated by "req_missing_for") nor an amount of skipped tests
271       (it is always 1, thus mandating unconditional use of done_testing).
272       Most useful in combination with ad hoc requirement specifications: EOC
273
274         push @chunks, <<EOC;
275         SKIP: {
276           $class->skip_without([ deploy YAML>=0.90 ]);
277
278           ...
279         }
280       EOC
281
282         push @chunks, <<'EOC';
283
284   die_unless_req_ok_for
285       Arguments: $group_name | \@group_names
286
287       Checks if "req_ok_for" passes for the supplied group(s), and in case of
288       failure throws an exception including the information from
289       "req_missing_for". See also "-die_without".
290
291   modreq_errorlist_for
292       Arguments: $group_name | \@group_names
293       Return Value: \%set_of_loaderrors_per_module
294
295       Returns a hashref containing the actual errors that occurred while
296       attempting to load each module in the requirement group(s).
297
298   req_errorlist_for
299       Deprecated method name, equivalent (via proxy) to
300       "modreq_errorlist_for".
301
302       EOC
303
304       #@@ #@@ FOOTER #@@
305         push @chunks, <<'EOC'; =head1 FURTHER QUESTIONS?
306
307       Check the list of additional DBIC resources.
308
310       This module is free software copyright by the
311       DBIx::Class::Schema::Loader (DBICSL) authors.  You can redistribute it
312       and/or modify it under the same terms as the
313       DBIx::Class::Schema::Loader library.  EOC
314
315         eval {
316           open (my $fh, '>', $podfn) or die;
317           print $fh join ("\n\n", @chunks) or die;
318           print $fh "\n" or die;
319           close ($fh) or die;
320         } or croak( "Unable to write $podfn: " . ( $! || $@ || 'unknown error') );
321       }
322
323       1;
324
325
326
327perl v5.32.0            DBIx::Clas2s0:2:0S-c0h7e-m2a8::Loader::Optional::Dependencies(3)
Impressum