Minor streamline of optdeps usage (no functional changes)
[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
8057ed01 114my $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
be68095d 448# the order does matter because the rdbms support group might require
449# a different version that the test group
68de9438 450 test_rdbms_pg => {
f6b26571 451 req => {
452 $ENV{DBICTEST_PG_DSN}
453 ? (
a4fc1239 454 # when changing this list make sure to adjust xt/optional_deps.t
be68095d 455 %$rdbms_pg,
f6b26571 456 'DBD::Pg' => '2.009002',
f6b26571 457 ) : ()
458 },
8057ed01 459 },
460
afae8507 461 test_rdbms_mssql_odbc => {
462 req => {
463 $ENV{DBICTEST_MSSQL_ODBC_DSN}
464 ? (
be68095d 465 %$rdbms_mssql_odbc,
afae8507 466 ) : ()
467 },
468 },
469
56dca25f 470 test_rdbms_mssql_ado => {
471 req => {
472 $ENV{DBICTEST_MSSQL_ADO_DSN}
473 ? (
474 %$rdbms_mssql_ado,
475 ) : ()
476 },
477 },
478
afae8507 479 test_rdbms_mssql_sybase => {
480 req => {
481 $ENV{DBICTEST_MSSQL_DSN}
482 ? (
be68095d 483 %$rdbms_mssql_sybase,
afae8507 484 ) : ()
485 },
486 },
487
726c8f65 488 test_rdbms_msaccess_odbc => {
489 req => {
490 $ENV{DBICTEST_MSACCESS_ODBC_DSN}
491 ? (
492 %$rdbms_msaccess_odbc,
493 %$datetime_basic,
494 'Data::GUID' => '0',
495 ) : ()
496 },
497 },
498
499 test_rdbms_msaccess_ado => {
500 req => {
501 $ENV{DBICTEST_MSACCESS_ADO_DSN}
502 ? (
503 %$rdbms_msaccess_ado,
504 %$datetime_basic,
505 'Data::GUID' => 0,
506 ) : ()
507 },
508 },
509
68de9438 510 test_rdbms_mysql => {
f6b26571 511 req => {
512 $ENV{DBICTEST_MYSQL_DSN}
513 ? (
be68095d 514 %$rdbms_mysql,
f6b26571 515 ) : ()
516 },
8057ed01 517 },
518
68de9438 519 test_rdbms_oracle => {
f6b26571 520 req => {
521 $ENV{DBICTEST_ORA_DSN}
522 ? (
be68095d 523 %$rdbms_oracle,
f6b26571 524 'DateTime::Format::Oracle' => '0',
e1b7e9b4 525 'DBD::Oracle' => '1.24',
f6b26571 526 ) : ()
527 },
8057ed01 528 },
529
68de9438 530 test_rdbms_ase => {
f6b26571 531 req => {
532 $ENV{DBICTEST_SYBASE_DSN}
533 ? (
be68095d 534 %$rdbms_ase,
f6b26571 535 ) : ()
536 },
8057ed01 537 },
538
68de9438 539 test_rdbms_db2 => {
f58a165c 540 req => {
541 $ENV{DBICTEST_DB2_DSN}
542 ? (
be68095d 543 %$rdbms_db2,
f58a165c 544 ) : ()
545 },
546 },
547
199fbc45 548 test_rdbms_db2_400 => {
549 req => {
550 $ENV{DBICTEST_DB2_400_DSN}
551 ? (
552 %$rdbms_db2_400,
553 ) : ()
554 },
555 },
556
557 test_rdbms_informix => {
558 req => {
559 $ENV{DBICTEST_INFORMIX_DSN}
560 ? (
561 %$rdbms_informix,
562 ) : ()
563 },
564 },
565
566 test_rdbms_sqlanywhere => {
567 req => {
568 $ENV{DBICTEST_SQLANYWHERE_DSN}
569 ? (
570 %$rdbms_sqlanywhere,
571 ) : ()
572 },
573 },
574
575 test_rdbms_sqlanywhere_odbc => {
576 req => {
577 $ENV{DBICTEST_SQLANYWHERE_ODBC_DSN}
578 ? (
579 %$rdbms_sqlanywhere_odbc,
580 ) : ()
581 },
582 },
583
584 test_rdbms_firebird => {
585 req => {
586 $ENV{DBICTEST_FIREBIRD_DSN}
587 ? (
588 %$rdbms_firebird,
589 ) : ()
590 },
591 },
592
593 test_rdbms_firebird_interbase => {
594 req => {
595 $ENV{DBICTEST_FIREBIRD_INTERBASE_DSN}
596 ? (
597 %$rdbms_firebird_interbase,
598 ) : ()
599 },
600 },
601
e02b39b4 602 test_rdbms_firebird_odbc => {
603 req => {
604 $ENV{DBICTEST_FIREBIRD_ODBC_DSN}
605 ? (
606 %$rdbms_firebird_odbc,
607 ) : ()
608 },
609 },
610
42168332 611 test_memcached => {
612 req => {
613 $ENV{DBICTEST_MEMCACHED}
614 ? (
615 'Cache::Memcached' => 0,
616 ) : ()
617 },
618 },
619
344f1f52 620 dist_dir => {
621 req => {
3ade80ee 622 %$test_and_dist_json_any,
b81d8515 623 'ExtUtils::MakeMaker' => '6.64',
06fc872a 624 'Pod::Inherit' => '0.91',
625 },
344f1f52 626 },
627
628 dist_upload => {
629 req => {
630 'CPAN::Uploader' => '0.103001',
631 },
632 },
633
8057ed01 634};
635
f6b26571 636
3ca0dcf0 637
638### Public API
639
640# OO for (mistakenly considered) ease of extensibility, not due to any need to
641# carry state of any sort. This API is currently used outside, so leave as-is.
642# FIXME - make sure to not propagate this further if module is extracted as a
643# standalone library - keep the stupidity to a DBIC-secific shim!
644#
fb39747c 645sub req_list_for {
646 my ($class, $group) = @_;
647
3f5e367a 648 croak "req_list_for() expects a requirement group name"
fb39747c 649 unless $group;
650
f6b26571 651 my $deps = $reqs->{$group}{req}
3f5e367a 652 or croak "Requirement group '$group' does not exist";
fb39747c 653
654 return { %$deps };
655}
656
3ca0dcf0 657sub req_group_list {
658 return { map { $_ => { %{ $reqs->{$_}{req} || {} } } } (keys %$reqs) };
659}
fb39747c 660
3ca0dcf0 661sub req_errorlist_for {
344f1f52 662 my ($class, $group) = @_;
663
3ca0dcf0 664 croak "req_errorlist_for() expects a requirement group name"
344f1f52 665 unless $group;
666
3ca0dcf0 667 return $class->_check_deps($group)->{errorlist};
344f1f52 668}
669
fb39747c 670sub req_ok_for {
671 my ($class, $group) = @_;
672
3f5e367a 673 croak "req_ok_for() expects a requirement group name"
fb39747c 674 unless $group;
675
d8799bab 676 return $class->_check_deps($group)->{status};
fb39747c 677}
678
679sub req_missing_for {
680 my ($class, $group) = @_;
681
3f5e367a 682 croak "req_missing_for() expects a requirement group name"
fb39747c 683 unless $group;
684
d8799bab 685 return $class->_check_deps($group)->{missing};
fb39747c 686}
687
3ca0dcf0 688sub die_unless_req_ok_for {
fb39747c 689 my ($class, $group) = @_;
690
3ca0dcf0 691 croak "die_unless_req_ok_for() expects a requirement group name"
fb39747c 692 unless $group;
693
3ca0dcf0 694 $class->_check_deps($group)->{status}
695 or die sprintf( "Required modules missing, unable to continue: %s\n", $class->_check_deps($group)->{missing} );
fb39747c 696}
697
3ca0dcf0 698
699
700### Private API
701
702our %req_availability_cache;
fb39747c 703sub _check_deps {
704 my ($class, $group) = @_;
705
d8799bab 706 return $req_availability_cache{$group} ||= do {
707
708 my $deps = $class->req_list_for ($group);
709
710 my %errors;
711 for my $mod (keys %$deps) {
712 my $req_line = "require $mod;";
713 if (my $ver = $deps->{$mod}) {
714 $req_line .= "$mod->VERSION($ver);";
715 }
716
717 eval $req_line;
718
719 $errors{$mod} = $@ if $@;
720 }
721
722 my $res;
fb39747c 723
d8799bab 724 if (keys %errors) {
34d2deae 725 my $missing = join (', ', map { $deps->{$_} ? qq("${_}~>=$deps->{$_}") : $_ } (sort keys %errors) );
726 $missing .= " (see $class documentation for details)" if $reqs->{$group}{pod};
d8799bab 727 $res = {
728 status => 0,
729 errorlist => \%errors,
730 missing => $missing,
731 };
fb39747c 732 }
733 else {
d8799bab 734 $res = {
735 status => 1,
736 errorlist => {},
737 missing => '',
738 };
fb39747c 739 }
740
d8799bab 741 $res;
742 };
fb39747c 743}
744
e3fc11e1 745# This is to be called by the author only (automatically in Makefile.PL)
f6b26571 746sub _gen_pod {
47589465 747 my ($class, $distver, $pod_dir) = @_;
31fa1764 748
47589465 749 die "No POD root dir supplied" unless $pod_dir;
31fa1764 750
ccebe1f1 751 $distver ||=
31fa1764 752 eval { require DBIx::Class; DBIx::Class->VERSION; }
753 ||
ccebe1f1 754 die
31fa1764 755"\n\n---------------------------------------------------------------------\n" .
756'Unable to load core DBIx::Class module to determine current version, '.
757'possibly due to missing dependencies. Author-mode autodocumentation ' .
758"halted\n\n" . $@ .
759"\n\n---------------------------------------------------------------------\n"
31fa1764 760 ;
761
3d4c5a84 762 # do not ask for a recent version, use 1.x API calls
47589465 763 # this *may* execute on a smoker with old perl or whatnot
764 require File::Path;
765
766 (my $modfn = __PACKAGE__ . '.pm') =~ s|::|/|g;
767
768 (my $podfn = "$pod_dir/$modfn") =~ s/\.pm$/\.pod/;
769 (my $dir = $podfn) =~ s|/[^/]+$||;
770
771 File::Path::mkpath([$dir]);
772
e3fc11e1 773 my $sqltver = $class->req_list_for ('deploy')->{'SQL::Translator'}
774 or die "Hrmm? No sqlt dep?";
7e3dc46f 775
3ca0dcf0 776
777 my @chunks;
778
779#@@
780#@@ HEADER
781#@@
782 push @chunks, (
6343a203 783 <<"EOC",
af4ac504 784#########################################################################
785##################### A U T O G E N E R A T E D ########################
786#########################################################################
787#
788# The contents of this POD file are auto-generated. Any changes you make
789# will be lost. If you need to change the generated text edit _gen_pod()
790# at the end of $modfn
791#
792EOC
f6b26571 793 '=head1 NAME',
7e3dc46f 794 "$class - Optional module dependency specifications (for module authors)",
3ca0dcf0 795 );
796
797
798#@@
799#@@ SYNOPSIS HEADING
800#@@
801 push @chunks, (
e3fc11e1 802 '=head1 SYNOPSIS',
d8799bab 803 <<"EOS",
7e3dc46f 804Somewhere in your build-file (e.g. L<Module::Install>'s Makefile.PL):
805
806 ...
807
808 configure_requires 'DBIx::Class' => '$distver';
809
810 require $class;
811
be68095d 812 my \$deploy_deps = $class->req_list_for('deploy');
7e3dc46f 813
814 for (keys %\$deploy_deps) {
815 requires \$_ => \$deploy_deps->{\$_};
816 }
817
818 ...
819
820Note that there are some caveats regarding C<configure_requires()>, more info
821can be found at L<Module::Install/configure_requires>
822EOS
3ca0dcf0 823 );
824
825
826#@@
827#@@ DESCRIPTION HEADING
828#@@
829 push @chunks, (
f6b26571 830 '=head1 DESCRIPTION',
831 <<'EOD',
832Some of the less-frequently used features of L<DBIx::Class> have external
833module dependencies on their own. In order not to burden the average user
834with modules he will never use, these optional dependencies are not included
835in the base Makefile.PL. Instead an exception with a descriptive message is
836thrown when a specific feature is missing one or several modules required for
837its operation. This module is the central holding place for the current list
7e3dc46f 838of such dependencies, for DBIx::Class core authors, and DBIx::Class extension
839authors alike.
f6b26571 840EOD
3ca0dcf0 841 );
842
843
844#@@
845#@@ REQUIREMENT GROUPLIST HEADING
846#@@
847 push @chunks, (
f6b26571 848 '=head1 CURRENT REQUIREMENT GROUPS',
849 <<'EOD',
850Dependencies are organized in C<groups> and each group can list one or more
851required modules, with an optional minimum version (or 0 for any version).
ecb68746 852The group name can be used in the
f6b26571 853EOD
854 );
855
856 for my $group (sort keys %$reqs) {
857 my $p = $reqs->{$group}{pod}
858 or next;
859
860 my $modlist = $reqs->{$group}{req}
861 or next;
862
863 next unless keys %$modlist;
864
865 push @chunks, (
866 "=head2 $p->{title}",
867 "$p->{desc}",
868 '=over',
869 ( map { "=item * $_" . ($modlist->{$_} ? " >= $modlist->{$_}" : '') } (sort keys %$modlist) ),
870 '=back',
871 "Requirement group: B<$group>",
872 );
873 }
874
3ca0dcf0 875
876#@@
877#@@ API DOCUMENTATION HEADING
878#@@
f6b26571 879 push @chunks, (
880 '=head1 METHODS',
e3fc11e1 881 '=head2 req_group_list',
882 '=over',
d8799bab 883 '=item Arguments: none',
fb13a49f 884 '=item Return Value: \%list_of_requirement_groups',
e3fc11e1 885 '=back',
d8799bab 886 <<'EOD',
e3fc11e1 887This method should be used by DBIx::Class packagers, to get a hashref of all
888dependencies keyed by dependency group. Each key (group name) can be supplied
889to one of the group-specific methods below.
890EOD
891
f6b26571 892 '=head2 req_list_for',
893 '=over',
894 '=item Arguments: $group_name',
fb13a49f 895 '=item Return Value: \%list_of_module_version_pairs',
f6b26571 896 '=back',
d8799bab 897 <<'EOD',
f6b26571 898This method should be used by DBIx::Class extension authors, to determine the
7e3dc46f 899version of modules a specific feature requires in the B<current> version of
e3fc11e1 900DBIx::Class. See the L</SYNOPSIS> for a real-world
7e3dc46f 901example.
f6b26571 902EOD
903
904 '=head2 req_ok_for',
905 '=over',
906 '=item Arguments: $group_name',
fb13a49f 907 '=item Return Value: 1|0',
f6b26571 908 '=back',
d8799bab 909 <<'EOD',
910Returns true or false depending on whether all modules required by
911C<$group_name> are present on the system and loadable.
912EOD
f6b26571 913
914 '=head2 req_missing_for',
915 '=over',
916 '=item Arguments: $group_name',
fb13a49f 917 '=item Return Value: $error_message_string',
f6b26571 918 '=back',
d8799bab 919 <<"EOD",
f6b26571 920Returns a single line string suitable for inclusion in larger error messages.
921This method would normally be used by DBIx::Class core-module author, to
922indicate to the user that he needs to install specific modules before he will
923be able to use a specific feature.
924
e3fc11e1 925For example if some of the requirements for C<deploy> are not available,
926the returned string could look like:
f6b26571 927
34d2deae 928 "SQL::Translator~>=$sqltver" (see $class documentation for details)
f6b26571 929
930The author is expected to prepend the necessary text to this message before
931returning the actual error seen by the user.
932EOD
933
344f1f52 934 '=head2 die_unless_req_ok_for',
935 '=over',
936 '=item Arguments: $group_name',
937 '=back',
938 <<'EOD',
939Checks if L</req_ok_for> passes for the supplied C<$group_name>, and
940in case of failure throws an exception including the information
941from L</req_missing_for>.
942EOD
943
f6b26571 944 '=head2 req_errorlist_for',
945 '=over',
946 '=item Arguments: $group_name',
fb13a49f 947 '=item Return Value: \%list_of_loaderrors_per_module',
f6b26571 948 '=back',
949 <<'EOD',
4a0eed52 950Returns a hashref containing the actual errors that occurred while attempting
f6b26571 951to load each module in the requirement group.
952EOD
3ca0dcf0 953 );
954
955
956#@@
957#@@ FOOTER
958#@@
959 push @chunks, (
a2bd3796 960 '=head1 FURTHER QUESTIONS?',
961 'Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.',
962 '=head1 COPYRIGHT AND LICENSE',
963 <<'EOL',
964This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
965by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
966redistribute it and/or modify it under the same terms as the
967L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.
968EOL
969
f6b26571 970 );
971
3ca0dcf0 972
3f5e367a 973 eval {
974 open (my $fh, '>', $podfn) or die;
975 print $fh join ("\n\n", @chunks) or die;
976 print $fh "\n" or die;
977 close ($fh) or die;
978 } or croak( "Unable to write $podfn: " . ( $! || $@ || 'unknown error') );
f6b26571 979}
980
8057ed01 9811;