1DBIx::Class::Schema::LoUasdeDerBrI:Cx:o:On:ptCtrliiaobsnusat:le::dS:cDPheeeprmelan:dD:eoLncocuaimdeeesnr(t:3a:)tOipotnional::Dependencies(3)
2
6 $class - Optional module dependency specifications (for module authors)
7 EOC
8 #@@ #@@ SYNOPSIS HEADING #@@
10 push @chunks, <<"EOC"; =head1 SYNOPSIS
11 Somewhere in your build-file (e.g. ExtUtils::MakeMaker's Makefile.PL):
13 ...
15 \$EUMM_ARGS{CONFIGURE_REQUIRES} = {
17 \%{ \$EUMM_ARGS{CONFIGURE_REQUIRES} || {} },
18 'DBIx::Class::Schema::Loader' => '$distver',
19 };
20 ...
22 my %DBIC_CONFIG_AND_ORACLE_DEPS = %{ eval {
24 require $class;
25 $class->req_list_for([qw( dbicdump_config rdbms_oracle )]);
26 } || {} };
27 \$EUMM_ARGS{PREREQ_PM} = {
29 \%DBIC_CONFIG_AND_ORACLE_DEPS,
30 \%{ \$EUMM_ARGS{PREREQ_PM} || {} },
31 };
32 ...
34 ExtUtils::MakeMaker::WriteMakefile(\%EUMM_ARGS);
36 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 #@@ #@@ DESCRIPTION HEADING #@@
51 push @chunks, <<'EOC'; =head1 DESCRIPTION
52 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 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 Each group name (or a combination thereof) can be used in the public
70 methods as described below. EOC
71 #@@ #@@ REQUIREMENT GROUPLIST HEADING #@@
73 push @chunks, '=head1 CURRENT REQUIREMENT GROUPS';
74 my $standalone_info;
76 for my $group (sort keys %$dbic_reqs) {
78 my $info = $standalone_info->{$group} ||= $class->_groups_to_reqs($group);
80 next unless (
82 $info->{modreqs_fully_documented}
83 and
84 ( $info->{augments} or $info->{modreqs} )
85 );
86 my $p = $dbic_reqs->{$group}{pod};
88 push @chunks, (
90 "=head2 $p->{title}",
91 "=head3 $group",
92 $p->{desc},
93 '=over',
94 );
95 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 push @chunks, '=back';
107 for my $ag ( sort keys %{ $info->{augments} || {} } ) {
109 my $ag_info = $standalone_info->{$ag} ||= $class->_groups_to_reqs($ag);
110 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 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 #@@ #@@ API DOCUMENTATION HEADING #@@
135 push @chunks, <<'EOC';
136
138 Even though this module is not an Exporter, it recognizes several
139 "actions" supplied to its "import" method.
140 -skip_all_without
142 Arguments: @group_names
143 A convenience wrapper for use during testing: EOC
145 push @chunks, " use $class -skip_all_without => qw(admin test_rdbms_mysql);";
147 push @chunks, 'Roughly equivalent to the following code:';
149 push @chunks, sprintf <<'EOS', ($class) x 2;
151 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 push @chunks, <<'EOC';
162 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 -die_without
168 Arguments: @group_names
169 A convenience wrapper around "die_unless_req_ok_for": EOC
171 push @chunks, " use $class -die_without => qw(deploy admin);";
173 push @chunks, <<'EOC';
175 -list_missing
177 Arguments: @group_names
178 A convenience wrapper around "modreq_missing_for":
180 perl -Ilib -MDBIx::Class::Schema::Loader::Optional::Dependencies=-list_missing,dbicdump_config,rdbms_oracle | cpanm
182
184 req_group_list
185 Arguments: none
186 Return Value: \%list_of_requirement_groups
187 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 req_list_for
197 Arguments: $group_name | \@group_names
198 Return Value: \%set_of_module_version_pairs
199 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 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 modreq_list_for
214 Arguments: $group_name | \@group_names
215 Return Value: \%set_of_module_version_pairs
216 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 req_ok_for
222 Arguments: $group_name | \@group_names
223 Return Value: 1|0
224 Returns true or false depending on whether all modules/envvars required
226 by the group(s) are loadable/set on the system.
227 req_missing_for
229 Arguments: $group_name | \@group_names
230 Return Value: $error_message_string
231 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 For example if some of the requirements for "deploy" are not available,
239 the returned string could look like: EOC
240 push @chunks, qq{ "Moose~$moosever" (see $class documentation for details)};
242 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 modreq_missing_for
248 Arguments: $group_name | \@group_names
249 Return Value: $error_message_string
250 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 For instance if some of the requirements for "deploy" are not
258 available, the returned string could look like: EOC
259 push @chunks, qq{ "Moose~$moosever"};
261 push @chunks, <<'EOC';
263 See also "-list_missing".
265 skip_without
267 Arguments: $group_name | \@group_names
268 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 push @chunks, <<EOC;
275 SKIP: {
276 $class->skip_without([ deploy YAML>=0.90 ]);
277 ...
279 }
280 EOC
281 push @chunks, <<'EOC';
283 die_unless_req_ok_for
285 Arguments: $group_name | \@group_names
286 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 modreq_errorlist_for
292 Arguments: $group_name | \@group_names
293 Return Value: \%set_of_loaderrors_per_module
294 Returns a hashref containing the actual errors that occurred while
296 attempting to load each module in the requirement group(s).
297 req_errorlist_for
299 Deprecated method name, equivalent (via proxy) to
300 "modreq_errorlist_for".
301 EOC
303 #@@ #@@ FOOTER #@@
305 push @chunks, <<'EOC'; =head1 FURTHER QUESTIONS?
306 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 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 1;
324perl v5.36.0 DBIx::Clas2s0:2:3S-c0h1e-m2a0::Loader::Optional::Dependencies(3)