Deprecate req_errorlist_for, proxy to to modreq_errorlist_for
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class / Optional / Dependencies.pm
CommitLineData
8057ed01 1package DBIx::Class::Optional::Dependencies;
2
3use warnings;
4use strict;
5
3f5e367a 6use Carp;
fb39747c 7
8# NO EXTERNAL NON-5.8.1 CORE DEPENDENCIES EVER (e.g. C::A::G)
8057ed01 9# This module is to be loaded by Makefile.PM on a pristine system
10
f6b26571 11# POD is generated automatically by calling _gen_pod from the
12# Makefile.PL in $AUTHOR mode
13
3ade80ee 14# NOTE: the rationale for 2 JSON::Any versions is that
15# we need the newer only to work around JSON::XS, which
16# itself is an optional dep
17my $min_json_any = {
be855469 18 'JSON::Any' => '1.23',
2a2a7b23 19};
3ade80ee 20my $test_and_dist_json_any = {
21 'JSON::Any' => '1.31',
22};
2a2a7b23 23
2b48ebff 24my $moose_basic = {
68de9438 25 'Moose' => '0.98',
26 'MooseX::Types' => '0.21',
d401ab6b 27 'MooseX::Types::LoadableClass' => '0.011',
68de9438 28};
29
30my $replicated = {
31 %$moose_basic,
2b48ebff 32};
33
ebcd0e4f 34my $admin_basic = {
35 %$moose_basic,
3ade80ee 36 %$min_json_any,
68de9438 37 'MooseX::Types::Path::Class' => '0.05',
38 'MooseX::Types::JSON' => '0.02',
68de9438 39};
40
a0361822 41my $admin_script = {
42 %$moose_basic,
43 %$admin_basic,
44 'Getopt::Long::Descriptive' => '0.081',
45 'Text::CSV' => '1.16',
46};
47
68de9438 48my $datetime_basic = {
49 'DateTime' => '0.55',
50 'DateTime::Format::Strptime' => '1.2',
ebcd0e4f 51};
52
c7d50a7d 53my $id_shortener = {
26022fb5 54 'Math::BigInt' => '1.80',
c7d50a7d 55 'Math::Base36' => '0.07',
56};
57
be68095d 58my $rdbms_sqlite = {
59 'DBD::SQLite' => '0',
60};
61my $rdbms_pg = {
62 'DBD::Pg' => '0',
63};
64my $rdbms_mssql_odbc = {
65 'DBD::ODBC' => '0',
66};
67my $rdbms_mssql_sybase = {
68 'DBD::Sybase' => '0',
69};
56dca25f 70my $rdbms_mssql_ado = {
71 'DBD::ADO' => '0',
72};
726c8f65 73my $rdbms_msaccess_odbc = {
74 'DBD::ODBC' => '0',
75};
76my $rdbms_msaccess_ado = {
77 'DBD::ADO' => '0',
78};
be68095d 79my $rdbms_mysql = {
80 'DBD::mysql' => '0',
81};
82my $rdbms_oracle = {
83 'DBD::Oracle' => '0',
84 %$id_shortener,
85};
86my $rdbms_ase = {
87 'DBD::Sybase' => '0',
88};
89my $rdbms_db2 = {
90 'DBD::DB2' => '0',
91};
199fbc45 92my $rdbms_db2_400 = {
93 'DBD::ODBC' => '0',
94};
95my $rdbms_informix = {
96 'DBD::Informix' => '0',
97};
98my $rdbms_sqlanywhere = {
99 'DBD::SQLAnywhere' => '0',
100};
101my $rdbms_sqlanywhere_odbc = {
102 'DBD::ODBC' => '0',
103};
104my $rdbms_firebird = {
105 'DBD::Firebird' => '0',
106};
107my $rdbms_firebird_interbase = {
108 'DBD::InterBase' => '0',
109};
e02b39b4 110my $rdbms_firebird_odbc = {
111 'DBD::ODBC' => '0',
112};
be68095d 113
31c31b8d 114my $dbic_reqs = {
8057ed01 115 replicated => {
68de9438 116 req => $replicated,
f6b26571 117 pod => {
118 title => 'Storage::Replicated',
119 desc => 'Modules required for L<DBIx::Class::Storage::DBI::Replicated>',
120 },
8057ed01 121 },
122
68de9438 123 test_replicated => {
124 req => {
125 %$replicated,
126 'Test::Moose' => '0',
127 },
128 },
129
130
8057ed01 131 admin => {
2b48ebff 132 req => {
ebcd0e4f 133 %$admin_basic,
134 },
135 pod => {
136 title => 'DBIx::Class::Admin',
137 desc => 'Modules required for the DBIx::Class administrative library',
138 },
139 },
140
a4a02f15 141 admin_script => {
ebcd0e4f 142 req => {
a0361822 143 %$admin_script,
2b48ebff 144 },
e144415f 145 pod => {
146 title => 'dbicadmin',
147 desc => 'Modules required for the CLI DBIx::Class interface dbicadmin',
148 },
8057ed01 149 },
150
151 deploy => {
f6b26571 152 req => {
08ac7648 153 'SQL::Translator' => '0.11018',
f6b26571 154 },
155 pod => {
156 title => 'Storage::DBI::deploy()',
5529838f 157 desc => 'Modules required for L<DBIx::Class::Storage::DBI/deployment_statements> and L<DBIx::Class::Schema/deploy>',
f6b26571 158 },
8057ed01 159 },
160
c7d50a7d 161 id_shortener => {
162 req => $id_shortener,
163 },
164
0d374214 165 test_component_accessor => {
166 req => {
167 'Class::Unload' => '0.07',
168 },
169 },
170
a109c954 171 test_pod => {
f6b26571 172 req => {
cbb19edf 173 'Test::Pod' => '1.42',
a109c954 174 },
175 },
176
177 test_podcoverage => {
178 req => {
f6b26571 179 'Test::Pod::Coverage' => '1.08',
180 'Pod::Coverage' => '0.20',
a109c954 181 },
182 },
183
ffce4b65 184 test_whitespace => {
a109c954 185 req => {
8273e845 186 'Test::EOL' => '1.0',
ffce4b65 187 'Test::NoTabs' => '0.9',
f6b26571 188 },
8057ed01 189 },
190
4a233f30 191 test_strictures => {
192 req => {
b2c1212f 193 'Test::Strict' => '0.20',
4a233f30 194 },
195 },
196
2a2a7b23 197 test_prettydebug => {
3ade80ee 198 req => $min_json_any,
2a2a7b23 199 },
200
99503754 201 test_admin_script => {
202 req => {
203 %$admin_script,
3ade80ee 204 %$test_and_dist_json_any,
99503754 205 'JSON' => 0,
be855469 206 'JSON::PP' => 0,
207 'Cpanel::JSON::XS' => 0,
99503754 208 'JSON::XS' => 0,
209 $^O eq 'MSWin32'
210 # for t/admin/10script.t
211 ? ('Win32::ShellQuote' => 0)
212 # DWIW does not compile (./configure even) on win32
213 : ('JSON::DWIW' => 0 )
214 ,
215 }
216 },
217
556c4fe6 218 test_leaks_heavy => {
f6b26571 219 req => {
556c4fe6 220 'Class::MethodCache' => '0.02',
221 'PadWalker' => '1.06',
a109c954 222 },
223 },
f6b26571 224
68de9438 225 test_dt => {
226 req => $datetime_basic,
227 },
228
229 test_dt_sqlite => {
a109c954 230 req => {
68de9438 231 %$datetime_basic,
f6b26571 232 # t/36datetime.t
233 # t/60core.t
234 'DateTime::Format::SQLite' => '0',
68de9438 235 },
236 },
f6b26571 237
68de9438 238 test_dt_mysql => {
239 req => {
240 %$datetime_basic,
9c92bb1c 241 # t/inflate/datetime_mysql.t
242 # (doesn't need Mysql itself)
68de9438 243 'DateTime::Format::MySQL' => '0',
244 },
245 },
9c92bb1c 246
68de9438 247 test_dt_pg => {
248 req => {
249 %$datetime_basic,
9c92bb1c 250 # t/inflate/datetime_pg.t
251 # (doesn't need PG itself)
ab35aeab 252 'DateTime::Format::Pg' => '0.16004',
f6b26571 253 },
8057ed01 254 },
255
68de9438 256 test_cdbicompat => {
f6b26571 257 req => {
f6b26571 258 'Class::DBI::Plugin::DeepAbstractSearch' => '0',
d9bd5195 259 %$datetime_basic,
f6b26571 260 'Time::Piece::MySQL' => '0',
f6b26571 261 'Date::Simple' => '3.03',
262 },
8057ed01 263 },
264
be68095d 265 # this is just for completeness as SQLite
266 # is a core dep of DBIC for testing
267 rdbms_sqlite => {
268 req => {
269 %$rdbms_sqlite,
270 },
271 pod => {
272 title => 'SQLite support',
273 desc => 'Modules required to connect to SQLite',
274 },
275 },
276
277 rdbms_pg => {
278 req => {
a4fc1239 279 # when changing this list make sure to adjust xt/optional_deps.t
be68095d 280 %$rdbms_pg,
281 },
282 pod => {
283 title => 'PostgreSQL support',
284 desc => 'Modules required to connect to PostgreSQL',
285 },
286 },
287
288 rdbms_mssql_odbc => {
289 req => {
290 %$rdbms_mssql_odbc,
291 },
292 pod => {
293 title => 'MSSQL support via DBD::ODBC',
294 desc => 'Modules required to connect to MSSQL via DBD::ODBC',
295 },
296 },
297
298 rdbms_mssql_sybase => {
299 req => {
300 %$rdbms_mssql_sybase,
301 },
302 pod => {
303 title => 'MSSQL support via DBD::Sybase',
56dca25f 304 desc => 'Modules required to connect to MSSQL via DBD::Sybase',
305 },
306 },
307
308 rdbms_mssql_ado => {
309 req => {
310 %$rdbms_mssql_ado,
311 },
312 pod => {
313 title => 'MSSQL support via DBD::ADO (Windows only)',
314 desc => 'Modules required to connect to MSSQL via DBD::ADO. This particular DBD is available on Windows only',
be68095d 315 },
316 },
317
726c8f65 318 rdbms_msaccess_odbc => {
319 req => {
320 %$rdbms_msaccess_odbc,
321 },
322 pod => {
323 title => 'MS Access support via DBD::ODBC',
324 desc => 'Modules required to connect to MS Access via DBD::ODBC',
325 },
326 },
327
328 rdbms_msaccess_ado => {
329 req => {
330 %$rdbms_msaccess_ado,
331 },
332 pod => {
333 title => 'MS Access support via DBD::ADO (Windows only)',
334 desc => 'Modules required to connect to MS Access via DBD::ADO. This particular DBD is available on Windows only',
335 },
336 },
337
be68095d 338 rdbms_mysql => {
339 req => {
340 %$rdbms_mysql,
341 },
342 pod => {
343 title => 'MySQL support',
344 desc => 'Modules required to connect to MySQL',
345 },
346 },
347
348 rdbms_oracle => {
349 req => {
350 %$rdbms_oracle,
351 },
352 pod => {
353 title => 'Oracle support',
354 desc => 'Modules required to connect to Oracle',
355 },
356 },
357
358 rdbms_ase => {
359 req => {
360 %$rdbms_ase,
361 },
362 pod => {
363 title => 'Sybase ASE support',
364 desc => 'Modules required to connect to Sybase ASE',
365 },
366 },
367
368 rdbms_db2 => {
369 req => {
370 %$rdbms_db2,
371 },
372 pod => {
373 title => 'DB2 support',
374 desc => 'Modules required to connect to DB2',
375 },
376 },
377
199fbc45 378 rdbms_db2_400 => {
379 req => {
380 %$rdbms_db2_400,
381 },
382 pod => {
383 title => 'DB2 on AS/400 support',
384 desc => 'Modules required to connect to DB2 on AS/400',
385 },
386 },
387
388 rdbms_informix => {
389 req => {
390 %$rdbms_informix,
391 },
392 pod => {
393 title => 'Informix support',
394 desc => 'Modules required to connect to Informix',
395 },
8273e845 396 },
199fbc45 397
398 rdbms_sqlanywhere => {
399 req => {
400 %$rdbms_sqlanywhere,
401 },
402 pod => {
403 title => 'SQLAnywhere support',
404 desc => 'Modules required to connect to SQLAnywhere',
405 },
8273e845 406 },
199fbc45 407
408 rdbms_sqlanywhere_odbc => {
409 req => {
410 %$rdbms_sqlanywhere_odbc,
411 },
412 pod => {
413 title => 'SQLAnywhere support via DBD::ODBC',
414 desc => 'Modules required to connect to SQLAnywhere via DBD::ODBC',
415 },
8273e845 416 },
199fbc45 417
418 rdbms_firebird => {
419 req => {
420 %$rdbms_firebird,
421 },
422 pod => {
423 title => 'Firebird support',
424 desc => 'Modules required to connect to Firebird',
425 },
8273e845 426 },
199fbc45 427
428 rdbms_firebird_interbase => {
429 req => {
430 %$rdbms_firebird_interbase,
431 },
432 pod => {
433 title => 'Firebird support via DBD::InterBase',
434 desc => 'Modules required to connect to Firebird via DBD::InterBase',
435 },
8273e845 436 },
199fbc45 437
438 rdbms_firebird_odbc => {
439 req => {
440 %$rdbms_firebird_odbc,
441 },
442 pod => {
443 title => 'Firebird support via DBD::ODBC',
444 desc => 'Modules required to connect to Firebird via DBD::ODBC',
445 },
8273e845 446 },
199fbc45 447
68de9438 448 test_rdbms_pg => {
f6b26571 449 req => {
450 $ENV{DBICTEST_PG_DSN}
451 ? (
31c31b8d 452 # the order does matter because the rdbms support group might require
453 # a different version that the test group
454 #
a4fc1239 455 # when changing this list make sure to adjust xt/optional_deps.t
be68095d 456 %$rdbms_pg,
f6b26571 457 'DBD::Pg' => '2.009002',
f6b26571 458 ) : ()
459 },
8057ed01 460 },
461
afae8507 462 test_rdbms_mssql_odbc => {
463 req => {
464 $ENV{DBICTEST_MSSQL_ODBC_DSN}
465 ? (
be68095d 466 %$rdbms_mssql_odbc,
afae8507 467 ) : ()
468 },
469 },
470
56dca25f 471 test_rdbms_mssql_ado => {
472 req => {
473 $ENV{DBICTEST_MSSQL_ADO_DSN}
474 ? (
475 %$rdbms_mssql_ado,
476 ) : ()
477 },
478 },
479
afae8507 480 test_rdbms_mssql_sybase => {
481 req => {
482 $ENV{DBICTEST_MSSQL_DSN}
483 ? (
be68095d 484 %$rdbms_mssql_sybase,
afae8507 485 ) : ()
486 },
487 },
488
726c8f65 489 test_rdbms_msaccess_odbc => {
490 req => {
491 $ENV{DBICTEST_MSACCESS_ODBC_DSN}
492 ? (
493 %$rdbms_msaccess_odbc,
494 %$datetime_basic,
495 'Data::GUID' => '0',
496 ) : ()
497 },
498 },
499
500 test_rdbms_msaccess_ado => {
501 req => {
502 $ENV{DBICTEST_MSACCESS_ADO_DSN}
503 ? (
504 %$rdbms_msaccess_ado,
505 %$datetime_basic,
506 'Data::GUID' => 0,
507 ) : ()
508 },
509 },
510
68de9438 511 test_rdbms_mysql => {
f6b26571 512 req => {
513 $ENV{DBICTEST_MYSQL_DSN}
514 ? (
be68095d 515 %$rdbms_mysql,
f6b26571 516 ) : ()
517 },
8057ed01 518 },
519
68de9438 520 test_rdbms_oracle => {
f6b26571 521 req => {
522 $ENV{DBICTEST_ORA_DSN}
523 ? (
be68095d 524 %$rdbms_oracle,
f6b26571 525 'DateTime::Format::Oracle' => '0',
e1b7e9b4 526 'DBD::Oracle' => '1.24',
f6b26571 527 ) : ()
528 },
8057ed01 529 },
530
68de9438 531 test_rdbms_ase => {
f6b26571 532 req => {
533 $ENV{DBICTEST_SYBASE_DSN}
534 ? (
be68095d 535 %$rdbms_ase,
f6b26571 536 ) : ()
537 },
8057ed01 538 },
539
68de9438 540 test_rdbms_db2 => {
f58a165c 541 req => {
542 $ENV{DBICTEST_DB2_DSN}
543 ? (
be68095d 544 %$rdbms_db2,
f58a165c 545 ) : ()
546 },
547 },
548
199fbc45 549 test_rdbms_db2_400 => {
550 req => {
551 $ENV{DBICTEST_DB2_400_DSN}
552 ? (
553 %$rdbms_db2_400,
554 ) : ()
555 },
556 },
557
558 test_rdbms_informix => {
559 req => {
560 $ENV{DBICTEST_INFORMIX_DSN}
561 ? (
562 %$rdbms_informix,
563 ) : ()
564 },
565 },
566
567 test_rdbms_sqlanywhere => {
568 req => {
569 $ENV{DBICTEST_SQLANYWHERE_DSN}
570 ? (
571 %$rdbms_sqlanywhere,
572 ) : ()
573 },
574 },
575
576 test_rdbms_sqlanywhere_odbc => {
577 req => {
578 $ENV{DBICTEST_SQLANYWHERE_ODBC_DSN}
579 ? (
580 %$rdbms_sqlanywhere_odbc,
581 ) : ()
582 },
583 },
584
585 test_rdbms_firebird => {
586 req => {
587 $ENV{DBICTEST_FIREBIRD_DSN}
588 ? (
589 %$rdbms_firebird,
590 ) : ()
591 },
592 },
593
594 test_rdbms_firebird_interbase => {
595 req => {
596 $ENV{DBICTEST_FIREBIRD_INTERBASE_DSN}
597 ? (
598 %$rdbms_firebird_interbase,
599 ) : ()
600 },
601 },
602
e02b39b4 603 test_rdbms_firebird_odbc => {
604 req => {
605 $ENV{DBICTEST_FIREBIRD_ODBC_DSN}
606 ? (
607 %$rdbms_firebird_odbc,
608 ) : ()
609 },
610 },
611
42168332 612 test_memcached => {
613 req => {
614 $ENV{DBICTEST_MEMCACHED}
615 ? (
616 'Cache::Memcached' => 0,
617 ) : ()
618 },
619 },
620
344f1f52 621 dist_dir => {
622 req => {
3ade80ee 623 %$test_and_dist_json_any,
b81d8515 624 'ExtUtils::MakeMaker' => '6.64',
06fc872a 625 'Pod::Inherit' => '0.91',
626 },
344f1f52 627 },
628
629 dist_upload => {
630 req => {
631 'CPAN::Uploader' => '0.103001',
632 },
633 },
634
8057ed01 635};
636
f6b26571 637
3ca0dcf0 638
639### Public API
640
641# OO for (mistakenly considered) ease of extensibility, not due to any need to
642# carry state of any sort. This API is currently used outside, so leave as-is.
643# FIXME - make sure to not propagate this further if module is extracted as a
644# standalone library - keep the stupidity to a DBIC-secific shim!
645#
fb39747c 646sub req_list_for {
31c31b8d 647 shift->_groups_to_reqs(@_)->{modreqs};
fb39747c 648}
649
3ca0dcf0 650sub req_group_list {
31c31b8d 651 +{ map
652 { $_ => $_[0]->_groups_to_reqs($_) }
653 keys %$dbic_reqs
654 }
3ca0dcf0 655}
fb39747c 656
5ffa39c7 657sub req_errorlist_for { shift->modreq_errorlist_for(@_) } # deprecated
658sub modreq_errorlist_for {
31c31b8d 659 my $self = shift;
660 $self->_errorlist_for_modreqs( $self->_groups_to_reqs(@_)->{modreqs} );
344f1f52 661}
662
fb39747c 663sub req_ok_for {
31c31b8d 664 my $self = shift;
665 $self->_errorlist_for_modreqs( $self->_groups_to_reqs(@_)->{modreqs} )
666 ? 0
667 : 1
668 ;
fb39747c 669}
670
671sub req_missing_for {
31c31b8d 672 my $self = shift;
fb39747c 673
31c31b8d 674 my $reqs = $self->_groups_to_reqs(@_);
675 my $modreq_errors = $self->_errorlist_for_modreqs($reqs->{modreqs}) or return '';
fb39747c 676
31c31b8d 677 join ' ',
678 (map { $reqs->{modreqs}{$_} ? qq("$_~>=$reqs->{modreqs}{$_}") : $_ } sort keys %$modreq_errors),
679 ( $reqs->{modreqs_fully_documented} ? "(see @{[ ref $self || $self ]} documentation for details)" : () ),
680 ;
fb39747c 681}
682
3ca0dcf0 683sub die_unless_req_ok_for {
31c31b8d 684 if (my $err = shift->req_missing_for(@_) ) {
685 die "Required modules missing, unable to continue: $err\n";
686 }
fb39747c 687}
688
3ca0dcf0 689
690
79b1bf0a 691### Private OO API
31c31b8d 692our %req_unavailability_cache;
693
694# this method is just a lister/metadata checker - it does not try to load anything
695sub _groups_to_reqs {
696 my ($self, $groups) = @_;
697
698 $groups = [ $groups || () ]
699 unless ref $groups eq 'ARRAY';
700
701 croak "@{[ (caller(1))[3] ]}() expects a requirement group name or arrayref of group names"
702 unless @$groups;
703
704 my $ret = {
705 modreqs => {},
706 modreqs_fully_documented => 1,
707 };
3ca0dcf0 708
fb39747c 709
31c31b8d 710 for my $group ( @$groups ) {
d8799bab 711
31c31b8d 712 $group =~ /\A [A-Za-z][0-9A-Z_a-z]* \z/x
713 or croak "Invalid requirement group name '$group': only ascii alphanumerics and _ are allowed";
d8799bab 714
31c31b8d 715 my $group_reqs = ($dbic_reqs->{$group}||{})->{req}
716 or croak "Requirement group '$group' is not defined";
d8799bab 717
31c31b8d 718 # sanity-check
719 for (keys %$group_reqs) {
d8799bab 720
31c31b8d 721 $_ =~ /\A [A-Z_a-z][0-9A-Z_a-z]* (?:::[0-9A-Z_a-z]+)* \z /x
722 or croak "Requirement '$_' in group '$group' is not a valid module name";
723
724 # !!!DO NOT CHANGE!!!
725 # remember - version.pm may not be available on the system
726 croak "Requirement '$_' in group '$group' specifies an invalid version '$group_reqs->{$_}' (only plain non-underscored floating point decimals are supported)"
727 if ( ($group_reqs->{$_}||0) !~ / \A [0-9]+ (?: \. [0-9]+ )? \z /x );
d8799bab 728 }
729
31c31b8d 730 # assemble into the final ret
731 for (keys %$group_reqs) {
732
733 $ret->{modreqs}{$_} = $group_reqs->{$_}||0 if (
734
735 ! exists $ret->{modreqs}{$_}
736 or
737 # we sanitized the version to be numeric above - we can just -gt it
738 ($group_reqs->{$_}||0) > $ret->{modreqs}{$_}
fb39747c 739
31c31b8d 740 );
fb39747c 741 }
31c31b8d 742
743 $ret->{modreqs_fully_documented} &&= !!$dbic_reqs->{$group}{pod};
744 }
745
746 return $ret;
747}
748
749
750# this method tries to load specified modreqs and returns a hashref of
751# module/loaderror pairs for anything that failed
752sub _errorlist_for_modreqs {
753 # args supposedly already went through _groups_to_reqs and are therefore sanitized
754 # safe to eval at will
755 my ($self, $reqs) = @_;
756
757 my $ret;
758
759 for my $m ( keys %$reqs ) {
760 my $v = $reqs->{$m};
761
762 if (! exists $req_unavailability_cache{$m}{$v} ) {
763 local $@;
764 eval( "require $m;" . ( $v ? "$m->VERSION(q($v))" : '' ) );
765 $req_unavailability_cache{$m}{$v} = $@;
fb39747c 766 }
767
31c31b8d 768 $ret->{$m} = $req_unavailability_cache{$m}{$v}
769 if $req_unavailability_cache{$m}{$v};
770 }
771
772 $ret;
fb39747c 773}
774
31c31b8d 775
e3fc11e1 776# This is to be called by the author only (automatically in Makefile.PL)
f6b26571 777sub _gen_pod {
47589465 778 my ($class, $distver, $pod_dir) = @_;
31fa1764 779
47589465 780 die "No POD root dir supplied" unless $pod_dir;
31fa1764 781
ccebe1f1 782 $distver ||=
31fa1764 783 eval { require DBIx::Class; DBIx::Class->VERSION; }
784 ||
ccebe1f1 785 die
31fa1764 786"\n\n---------------------------------------------------------------------\n" .
787'Unable to load core DBIx::Class module to determine current version, '.
788'possibly due to missing dependencies. Author-mode autodocumentation ' .
789"halted\n\n" . $@ .
790"\n\n---------------------------------------------------------------------\n"
31fa1764 791 ;
792
3d4c5a84 793 # do not ask for a recent version, use 1.x API calls
47589465 794 # this *may* execute on a smoker with old perl or whatnot
795 require File::Path;
796
797 (my $modfn = __PACKAGE__ . '.pm') =~ s|::|/|g;
798
799 (my $podfn = "$pod_dir/$modfn") =~ s/\.pm$/\.pod/;
800 (my $dir = $podfn) =~ s|/[^/]+$||;
801
802 File::Path::mkpath([$dir]);
803
31c31b8d 804 my $sqltver = $class->req_list_for('deploy')->{'SQL::Translator'}
e3fc11e1 805 or die "Hrmm? No sqlt dep?";
7e3dc46f 806
3ca0dcf0 807
808 my @chunks;
809
810#@@
811#@@ HEADER
812#@@
79b1bf0a 813 push @chunks, <<"EOC";
af4ac504 814#########################################################################
815##################### A U T O G E N E R A T E D ########################
816#########################################################################
817#
818# The contents of this POD file are auto-generated. Any changes you make
819# will be lost. If you need to change the generated text edit _gen_pod()
820# at the end of $modfn
821#
79b1bf0a 822
823=head1 NAME
824
825$class - Optional module dependency specifications (for module authors)
af4ac504 826EOC
3ca0dcf0 827
828
829#@@
830#@@ SYNOPSIS HEADING
831#@@
79b1bf0a 832 push @chunks, <<"EOC";
833=head1 SYNOPSIS
834
835Somewhere in your build-file (e.g. L<ExtUtils::MakeMaker>'s F<Makefile.PL>):
7e3dc46f 836
837 ...
838
79b1bf0a 839 \$EUMM_ARGS{CONFIGURE_REQUIRES} = {
840 \%{ \$EUMM_ARGS{CONFIGURE_REQUIRES} || {} },
841 'DBIx::Class' => '$distver',
842 };
7e3dc46f 843
79b1bf0a 844 ...
7e3dc46f 845
79b1bf0a 846 my %DBIC_DEPLOY_DEPS = %{ eval {
847 require $class;
848 $class->req_list_for('deploy');
849 } || {} };
7e3dc46f 850
79b1bf0a 851 \$EUMM_ARGS{PREREQ_PM} = {
852 \%DBIC_DEPLOY_DEPS,
853 \%{ \$EUMM_ARGS{PREREQ_PM} || {} },
854 };
7e3dc46f 855
856 ...
857
79b1bf0a 858 ExtUtils::MakeMaker::WriteMakefile(\%EUMM_ARGS);
859
860B<Note>: The C<eval> protection within the example is due to support for
861requirements during L<the C<configure> build phase|CPAN::Meta::Spec/Phases>
862not being available on a sufficient portion of production installations of
863Perl. Robust support for such dependency requirements is available in the
864L<CPAN> installer only since version C<1.94_56> first made available for
865production with perl version C<5.12>. It is the belief of the current
866maintainer that support for requirements during the C<configure> build phase
867will not be sufficiently ubiquitous until the B<year 2020> at the earliest,
868hence the extra care demonstrated above. It should also be noted that some
8693rd party installers (e.g. L<cpanminus|App::cpanminus>) do the right thing
870with configure requirements independent from the versions of perl and CPAN
871available.
872EOC
3ca0dcf0 873
874
875#@@
876#@@ DESCRIPTION HEADING
877#@@
79b1bf0a 878 push @chunks, <<'EOC';
879=head1 DESCRIPTION
880
f6b26571 881Some of the less-frequently used features of L<DBIx::Class> have external
882module dependencies on their own. In order not to burden the average user
79b1bf0a 883with modules they will never use, these optional dependencies are not included
f6b26571 884in the base Makefile.PL. Instead an exception with a descriptive message is
79b1bf0a 885thrown when a specific feature can't find one or several modules required for
886its operation. This module is the central holding place for the current list
7e3dc46f 887of such dependencies, for DBIx::Class core authors, and DBIx::Class extension
888authors alike.
79b1bf0a 889
890Dependencies are organized in L<groups|/CURRENT REQUIREMENT GROUPS> where each
891group can list one or more required modules, with an optional minimum version
31c31b8d 892(or 0 for any version). Each group name (or a combination thereof) can be used
893in the L<public methods|/METHODS> as described below.
79b1bf0a 894EOC
3ca0dcf0 895
896
897#@@
898#@@ REQUIREMENT GROUPLIST HEADING
899#@@
79b1bf0a 900 push @chunks, '=head1 CURRENT REQUIREMENT GROUPS';
f6b26571 901
31c31b8d 902 for my $group (sort keys %$dbic_reqs) {
903 my $p = $dbic_reqs->{$group}{pod}
f6b26571 904 or next;
905
31c31b8d 906 my $modlist = $dbic_reqs->{$group}{req}
f6b26571 907 or next;
908
909 next unless keys %$modlist;
910
911 push @chunks, (
912 "=head2 $p->{title}",
913 "$p->{desc}",
914 '=over',
915 ( map { "=item * $_" . ($modlist->{$_} ? " >= $modlist->{$_}" : '') } (sort keys %$modlist) ),
916 '=back',
917 "Requirement group: B<$group>",
918 );
919 }
920
3ca0dcf0 921
922#@@
923#@@ API DOCUMENTATION HEADING
924#@@
79b1bf0a 925 push @chunks, <<'EOC';
926
927=head1 METHODS
928
929=head2 req_group_list
930
931=over
932
933=item Arguments: none
934
935=item Return Value: \%list_of_requirement_groups
936
937=back
938
e3fc11e1 939This method should be used by DBIx::Class packagers, to get a hashref of all
31c31b8d 940dependencies B<keyed> by dependency group. Each key (group name), or a combination
941thereof (as an arrayref) can be supplied to the methods below.
79b1bf0a 942The B<values> of the returned hash are currently a set of options B<without a
943well defined structure>. If you have use for any of the contents - contact the
944maintainers, instead of treating this as public (left alone stable) API.
945
946=head2 req_list_for
947
948=over
949
31c31b8d 950=item Arguments: $group_name | \@group_names
79b1bf0a 951
31c31b8d 952=item Return Value: \%set_of_module_version_pairs
79b1bf0a 953
954=back
955
f6b26571 956This method should be used by DBIx::Class extension authors, to determine the
31c31b8d 957version of modules a specific set of features requires for this version of
79b1bf0a 958DBIx::Class. See the L</SYNOPSIS> for a real-world example.
959
960=head2 req_ok_for
961
962=over
963
31c31b8d 964=item Arguments: $group_name | \@group_names
79b1bf0a 965
966=item Return Value: 1|0
967
968=back
969
d8799bab 970Returns true or false depending on whether all modules required by
31c31b8d 971the group(s) are present on the system and loadable.
79b1bf0a 972
973=head2 req_missing_for
974
975=over
976
31c31b8d 977=item Arguments: $group_name | \@group_names
79b1bf0a 978
979=item Return Value: $error_message_string
980
981=back
982
31c31b8d 983Returns a single-line string suitable for inclusion in larger error messages.
79b1bf0a 984This method would normally be used by DBIx::Class core-modules, to indicate to
985the user that they need to install specific modules before being able to use a
986specific feature set.
f6b26571 987
e3fc11e1 988For example if some of the requirements for C<deploy> are not available,
989the returned string could look like:
79b1bf0a 990EOC
f6b26571 991
79b1bf0a 992 push @chunks, qq{ "SQL::Translator~>=$sqltver" (see $class documentation for details)};
f6b26571 993
79b1bf0a 994 push @chunks, <<'EOC';
f6b26571 995The author is expected to prepend the necessary text to this message before
996returning the actual error seen by the user.
f6b26571 997
79b1bf0a 998=head2 die_unless_req_ok_for
999
1000=over
1001
31c31b8d 1002=item Arguments: $group_name | \@group_names
79b1bf0a 1003
1004=back
1005
31c31b8d 1006Checks if L</req_ok_for> passes for the supplied group(s), and
344f1f52 1007in case of failure throws an exception including the information
1008from L</req_missing_for>.
79b1bf0a 1009
5ffa39c7 1010=head2 modreq_errorlist_for
79b1bf0a 1011
1012=over
1013
31c31b8d 1014=item Arguments: $group_name | \@group_names
79b1bf0a 1015
31c31b8d 1016=item Return Value: \%set_of_loaderrors_per_module
79b1bf0a 1017
1018=back
1019
4a0eed52 1020Returns a hashref containing the actual errors that occurred while attempting
31c31b8d 1021to load each module in the requirement group(s).
5ffa39c7 1022
1023=head2 req_errorlist_for
1024
1025Deprecated method name, equivalent (via proxy) to L</modreq_errorlist_for>.
1026
79b1bf0a 1027EOC
3ca0dcf0 1028
31c31b8d 1029
3ca0dcf0 1030#@@
1031#@@ FOOTER
1032#@@
79b1bf0a 1033 push @chunks, <<'EOC';
1034=head1 FURTHER QUESTIONS?
1035
1036Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
1037
1038=head1 COPYRIGHT AND LICENSE
1039
a2bd3796 1040This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
1041by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
1042redistribute it and/or modify it under the same terms as the
1043L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.
79b1bf0a 1044EOC
3ca0dcf0 1045
3f5e367a 1046 eval {
1047 open (my $fh, '>', $podfn) or die;
1048 print $fh join ("\n\n", @chunks) or die;
1049 print $fh "\n" or die;
1050 close ($fh) or die;
1051 } or croak( "Unable to write $podfn: " . ( $! || $@ || 'unknown error') );
f6b26571 1052}
1053
8057ed01 10541;