lib/DBIx/Class/Optional/Dependencies.pm

   1 package DBIx::Class::Optional::Dependencies;
   2
   3 use warnings;
   4 use strict;
   5
   6 use Carp ();
   7
   8 # NO EXTERNAL NON-5.8.1 CORE DEPENDENCIES EVER (e.g. C::A::G)
   9 # This module is to be loaded by Makefile.PM on a pristine system
  10
  11 # POD is generated automatically by calling _gen_pod from the
  12 # Makefile.PL in $AUTHOR mode
  13
  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
  17 my $min_json_any = {
  18   'JSON::Any'                     => '1.23',
  19 };
  20 my $test_and_dist_json_any = {
  21   'JSON::Any'                     => '1.31',
  22 };
  23
  24 my $moose_basic = {
  25   'Moose'                         => '0.98',
  26   'MooseX::Types'                 => '0.21',
  27   'MooseX::Types::LoadableClass'  => '0.011',
  28 };
  29
  30 my $replicated = {
  31   %$moose_basic,
  32 };
  33
  34 my $admin_basic = {
  35   %$moose_basic,
  36   %$min_json_any,
  37   'MooseX::Types::Path::Class'    => '0.05',
  38   'MooseX::Types::JSON'           => '0.02',
  39 };
  40
  41 my $admin_script = {
  42   %$moose_basic,
  43   %$admin_basic,
  44   'Getopt::Long::Descriptive' => '0.081',
  45   'Text::CSV'                 => '1.16',
  46 };
  47
  48 my $datetime_basic = {
  49   'DateTime'                      => '0.55',
  50   'DateTime::Format::Strptime'    => '1.2',
  51 };
  52
  53 my $id_shortener = {
  54   'Math::BigInt'                  => '1.80',
  55   'Math::Base36'                  => '0.07',
  56 };
  57
  58 my $rdbms_sqlite = {
  59   'DBD::SQLite'                   => '0',
  60 };
  61 my $rdbms_pg = {
  62   'DBD::Pg'                       => '0',
  63 };
  64 my $rdbms_mssql_odbc = {
  65   'DBD::ODBC'                     => '0',
  66 };
  67 my $rdbms_mssql_sybase = {
  68   'DBD::Sybase'                   => '0',
  69 };
  70 my $rdbms_mssql_ado = {
  71   'DBD::ADO'                      => '0',
  72 };
  73 my $rdbms_msaccess_odbc = {
  74   'DBD::ODBC'                     => '0',
  75 };
  76 my $rdbms_msaccess_ado = {
  77   'DBD::ADO'                      => '0',
  78 };
  79 my $rdbms_mysql = {
  80   'DBD::mysql'                    => '0',
  81 };
  82 my $rdbms_oracle = {
  83   'DBD::Oracle'                   => '0',
  84   %$id_shortener,
  85 };
  86 my $rdbms_ase = {
  87   'DBD::Sybase'                   => '0',
  88 };
  89 my $rdbms_db2 = {
  90   'DBD::DB2'                      => '0',
  91 };
  92 my $rdbms_db2_400 = {
  93   'DBD::ODBC'                     => '0',
  94 };
  95 my $rdbms_informix = {
  96   'DBD::Informix'                 => '0',
  97 };
  98 my $rdbms_sqlanywhere = {
  99   'DBD::SQLAnywhere'              => '0',
 100 };
 101 my $rdbms_sqlanywhere_odbc = {
 102   'DBD::ODBC'                     => '0',
 103 };
 104 my $rdbms_firebird = {
 105   'DBD::Firebird'                 => '0',
 106 };
 107 my $rdbms_firebird_interbase = {
 108   'DBD::InterBase'                => '0',
 109 };
 110 my $rdbms_firebird_odbc = {
 111   'DBD::ODBC'                     => '0',
 112 };
 113
 114 my $reqs = {
 115   replicated => {
 116     req => $replicated,
 117     pod => {
 118       title => 'Storage::Replicated',
 119       desc => 'Modules required for L<DBIx::Class::Storage::DBI::Replicated>',
 120     },
 121   },
 122
 123   test_replicated => {
 124     req => {
 125       %$replicated,
 126       'Test::Moose'               => '0',
 127     },
 128   },
 129
 130
 131   admin => {
 132     req => {
 133       %$admin_basic,
 134     },
 135     pod => {
 136       title => 'DBIx::Class::Admin',
 137       desc => 'Modules required for the DBIx::Class administrative library',
 138     },
 139   },
 140
 141   admin_script => {
 142     req => {
 143       %$admin_script,
 144     },
 145     pod => {
 146       title => 'dbicadmin',
 147       desc => 'Modules required for the CLI DBIx::Class interface dbicadmin',
 148     },
 149   },
 150
 151   deploy => {
 152     req => {
 153       'SQL::Translator'           => '0.11018',
 154     },
 155     pod => {
 156       title => 'Storage::DBI::deploy()',
 157       desc => 'Modules required for L<DBIx::Class::Storage::DBI/deployment_statements> and L<DBIx::Class::Schema/deploy>',
 158     },
 159   },
 160
 161   id_shortener => {
 162     req => $id_shortener,
 163   },
 164
 165   test_component_accessor => {
 166     req => {
 167       'Class::Unload'             => '0.07',
 168     },
 169   },
 170
 171   test_pod => {
 172     req => {
 173       'Test::Pod'                 => '1.42',
 174     },
 175   },
 176
 177   test_podcoverage => {
 178     req => {
 179       'Test::Pod::Coverage'       => '1.08',
 180       'Pod::Coverage'             => '0.20',
 181     },
 182   },
 183
 184   test_whitespace => {
 185     req => {
 186       'Test::EOL'                 => '1.0',
 187       'Test::NoTabs'              => '0.9',
 188     },
 189   },
 190
 191   test_strictures => {
 192     req => {
 193       'Test::Strict'              => '0.20',
 194     },
 195   },
 196
 197   test_prettydebug => {
 198     req => $min_json_any,
 199   },
 200
 201   test_admin_script => {
 202     req => {
 203       %$admin_script,
 204       %$test_and_dist_json_any,
 205       'JSON' => 0,
 206       'JSON::PP' => 0,
 207       'Cpanel::JSON::XS' => 0,
 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
 218   test_leaks_heavy => {
 219     req => {
 220       'Class::MethodCache' => '0.02',
 221       'PadWalker' => '1.06',
 222     },
 223   },
 224
 225   test_dt => {
 226     req => $datetime_basic,
 227   },
 228
 229   test_dt_sqlite => {
 230     req => {
 231       %$datetime_basic,
 232       # t/36datetime.t
 233       # t/60core.t
 234       'DateTime::Format::SQLite'  => '0',
 235     },
 236   },
 237
 238   test_dt_mysql => {
 239     req => {
 240       %$datetime_basic,
 241       # t/inflate/datetime_mysql.t
 242       # (doesn't need Mysql itself)
 243       'DateTime::Format::MySQL'   => '0',
 244     },
 245   },
 246
 247   test_dt_pg => {
 248     req => {
 249       %$datetime_basic,
 250       # t/inflate/datetime_pg.t
 251       # (doesn't need PG itself)
 252       'DateTime::Format::Pg'      => '0.16004',
 253     },
 254   },
 255
 256   test_cdbicompat => {
 257     req => {
 258       %$datetime_basic,
 259       'Time::Piece::MySQL'        => '0',
 260       'Date::Simple'              => '3.03',
 261     },
 262   },
 263
 264   test_cdbicompat_deepabstractsearch => {
 265     req => {
 266       'Class::DBI::Plugin::DeepAbstractSearch' => '0',
 267     },
 268   },
 269
 270   cdbicompat => {
 271     req => {
 272       'Class::Trigger'        => '0',
 273       'DBIx::ContextualFetch' => '0',
 274       'Clone'                 => '0',
 275     },
 276   },
 277
 278   cdbicompat => {
 279     req => {
 280       'Class::Trigger'        => '0',
 281       'DBIx::ContextualFetch' => '0',
 282       'Clone'                 => '0',
 283     },
 284   },
 285
 286   # this is just for completeness as SQLite
 287   # is a core dep of DBIC for testing
 288   rdbms_sqlite => {
 289     req => {
 290       %$rdbms_sqlite,
 291     },
 292     pod => {
 293       title => 'SQLite support',
 294       desc => 'Modules required to connect to SQLite',
 295     },
 296   },
 297
 298   rdbms_pg => {
 299     req => {
 300       # when changing this list make sure to adjust xt/optional_deps.t
 301       %$rdbms_pg,
 302     },
 303     pod => {
 304       title => 'PostgreSQL support',
 305       desc => 'Modules required to connect to PostgreSQL',
 306     },
 307   },
 308
 309   rdbms_mssql_odbc => {
 310     req => {
 311       %$rdbms_mssql_odbc,
 312     },
 313     pod => {
 314       title => 'MSSQL support via DBD::ODBC',
 315       desc => 'Modules required to connect to MSSQL via DBD::ODBC',
 316     },
 317   },
 318
 319   rdbms_mssql_sybase => {
 320     req => {
 321       %$rdbms_mssql_sybase,
 322     },
 323     pod => {
 324       title => 'MSSQL support via DBD::Sybase',
 325       desc => 'Modules required to connect to MSSQL via DBD::Sybase',
 326     },
 327   },
 328
 329   rdbms_mssql_ado => {
 330     req => {
 331       %$rdbms_mssql_ado,
 332     },
 333     pod => {
 334       title => 'MSSQL support via DBD::ADO (Windows only)',
 335       desc => 'Modules required to connect to MSSQL via DBD::ADO. This particular DBD is available on Windows only',
 336     },
 337   },
 338
 339   rdbms_msaccess_odbc => {
 340     req => {
 341       %$rdbms_msaccess_odbc,
 342     },
 343     pod => {
 344       title => 'MS Access support via DBD::ODBC',
 345       desc => 'Modules required to connect to MS Access via DBD::ODBC',
 346     },
 347   },
 348
 349   rdbms_msaccess_ado => {
 350     req => {
 351       %$rdbms_msaccess_ado,
 352     },
 353     pod => {
 354       title => 'MS Access support via DBD::ADO (Windows only)',
 355       desc => 'Modules required to connect to MS Access via DBD::ADO. This particular DBD is available on Windows only',
 356     },
 357   },
 358
 359   rdbms_mysql => {
 360     req => {
 361       %$rdbms_mysql,
 362     },
 363     pod => {
 364       title => 'MySQL support',
 365       desc => 'Modules required to connect to MySQL',
 366     },
 367   },
 368
 369   rdbms_oracle => {
 370     req => {
 371       %$rdbms_oracle,
 372     },
 373     pod => {
 374       title => 'Oracle support',
 375       desc => 'Modules required to connect to Oracle',
 376     },
 377   },
 378
 379   rdbms_ase => {
 380     req => {
 381       %$rdbms_ase,
 382     },
 383     pod => {
 384       title => 'Sybase ASE support',
 385       desc => 'Modules required to connect to Sybase ASE',
 386     },
 387   },
 388
 389   rdbms_db2 => {
 390     req => {
 391       %$rdbms_db2,
 392     },
 393     pod => {
 394       title => 'DB2 support',
 395       desc => 'Modules required to connect to DB2',
 396     },
 397   },
 398
 399   rdbms_db2_400 => {
 400     req => {
 401       %$rdbms_db2_400,
 402     },
 403     pod => {
 404       title => 'DB2 on AS/400 support',
 405       desc => 'Modules required to connect to DB2 on AS/400',
 406     },
 407   },
 408
 409   rdbms_informix => {
 410     req => {
 411       %$rdbms_informix,
 412     },
 413     pod => {
 414       title => 'Informix support',
 415       desc => 'Modules required to connect to Informix',
 416     },
 417   },
 418
 419   rdbms_sqlanywhere => {
 420     req => {
 421       %$rdbms_sqlanywhere,
 422     },
 423     pod => {
 424       title => 'SQLAnywhere support',
 425       desc => 'Modules required to connect to SQLAnywhere',
 426     },
 427   },
 428
 429   rdbms_sqlanywhere_odbc => {
 430     req => {
 431       %$rdbms_sqlanywhere_odbc,
 432     },
 433     pod => {
 434       title => 'SQLAnywhere support via DBD::ODBC',
 435       desc => 'Modules required to connect to SQLAnywhere via DBD::ODBC',
 436     },
 437   },
 438
 439   rdbms_firebird => {
 440     req => {
 441       %$rdbms_firebird,
 442     },
 443     pod => {
 444       title => 'Firebird support',
 445       desc => 'Modules required to connect to Firebird',
 446     },
 447   },
 448
 449   rdbms_firebird_interbase => {
 450     req => {
 451       %$rdbms_firebird_interbase,
 452     },
 453     pod => {
 454       title => 'Firebird support via DBD::InterBase',
 455       desc => 'Modules required to connect to Firebird via DBD::InterBase',
 456     },
 457   },
 458
 459   rdbms_firebird_odbc => {
 460     req => {
 461       %$rdbms_firebird_odbc,
 462     },
 463     pod => {
 464       title => 'Firebird support via DBD::ODBC',
 465       desc => 'Modules required to connect to Firebird via DBD::ODBC',
 466     },
 467   },
 468
 469 # the order does matter because the rdbms support group might require
 470 # a different version that the test group
 471   test_rdbms_pg => {
 472     req => {
 473       $ENV{DBICTEST_PG_DSN}
 474         ? (
 475           # when changing this list make sure to adjust xt/optional_deps.t
 476           %$rdbms_pg,
 477           'DBD::Pg'               => '2.009002',
 478         ) : ()
 479     },
 480   },
 481
 482   test_rdbms_mssql_odbc => {
 483     req => {
 484       $ENV{DBICTEST_MSSQL_ODBC_DSN}
 485         ? (
 486           %$rdbms_mssql_odbc,
 487         ) : ()
 488     },
 489   },
 490
 491   test_rdbms_mssql_ado => {
 492     req => {
 493       $ENV{DBICTEST_MSSQL_ADO_DSN}
 494         ? (
 495           %$rdbms_mssql_ado,
 496         ) : ()
 497     },
 498   },
 499
 500   test_rdbms_mssql_sybase => {
 501     req => {
 502       $ENV{DBICTEST_MSSQL_DSN}
 503         ? (
 504           %$rdbms_mssql_sybase,
 505         ) : ()
 506     },
 507   },
 508
 509   test_rdbms_msaccess_odbc => {
 510     req => {
 511       $ENV{DBICTEST_MSACCESS_ODBC_DSN}
 512         ? (
 513           %$rdbms_msaccess_odbc,
 514           %$datetime_basic,
 515           'Data::GUID' => '0',
 516         ) : ()
 517     },
 518   },
 519
 520   test_rdbms_msaccess_ado => {
 521     req => {
 522       $ENV{DBICTEST_MSACCESS_ADO_DSN}
 523         ? (
 524           %$rdbms_msaccess_ado,
 525           %$datetime_basic,
 526           'Data::GUID' => 0,
 527         ) : ()
 528     },
 529   },
 530
 531   test_rdbms_mysql => {
 532     req => {
 533       $ENV{DBICTEST_MYSQL_DSN}
 534         ? (
 535           %$rdbms_mysql,
 536         ) : ()
 537     },
 538   },
 539
 540   test_rdbms_oracle => {
 541     req => {
 542       $ENV{DBICTEST_ORA_DSN}
 543         ? (
 544           %$rdbms_oracle,
 545           'DateTime::Format::Oracle' => '0',
 546           'DBD::Oracle'              => '1.24',
 547         ) : ()
 548     },
 549   },
 550
 551   test_rdbms_ase => {
 552     req => {
 553       $ENV{DBICTEST_SYBASE_DSN}
 554         ? (
 555           %$rdbms_ase,
 556         ) : ()
 557     },
 558   },
 559
 560   test_rdbms_db2 => {
 561     req => {
 562       $ENV{DBICTEST_DB2_DSN}
 563         ? (
 564           %$rdbms_db2,
 565         ) : ()
 566     },
 567   },
 568
 569   test_rdbms_db2_400 => {
 570     req => {
 571       $ENV{DBICTEST_DB2_400_DSN}
 572         ? (
 573           %$rdbms_db2_400,
 574         ) : ()
 575     },
 576   },
 577
 578   test_rdbms_informix => {
 579     req => {
 580       $ENV{DBICTEST_INFORMIX_DSN}
 581         ? (
 582           %$rdbms_informix,
 583         ) : ()
 584     },
 585   },
 586
 587   test_rdbms_sqlanywhere => {
 588     req => {
 589       $ENV{DBICTEST_SQLANYWHERE_DSN}
 590         ? (
 591           %$rdbms_sqlanywhere,
 592         ) : ()
 593     },
 594   },
 595
 596   test_rdbms_sqlanywhere_odbc => {
 597     req => {
 598       $ENV{DBICTEST_SQLANYWHERE_ODBC_DSN}
 599         ? (
 600           %$rdbms_sqlanywhere_odbc,
 601         ) : ()
 602     },
 603   },
 604
 605   test_rdbms_firebird => {
 606     req => {
 607       $ENV{DBICTEST_FIREBIRD_DSN}
 608         ? (
 609           %$rdbms_firebird,
 610         ) : ()
 611     },
 612   },
 613
 614   test_rdbms_firebird_interbase => {
 615     req => {
 616       $ENV{DBICTEST_FIREBIRD_INTERBASE_DSN}
 617         ? (
 618           %$rdbms_firebird_interbase,
 619         ) : ()
 620     },
 621   },
 622
 623   test_rdbms_firebird_odbc => {
 624     req => {
 625       $ENV{DBICTEST_FIREBIRD_ODBC_DSN}
 626         ? (
 627           %$rdbms_firebird_odbc,
 628         ) : ()
 629     },
 630   },
 631
 632   test_memcached => {
 633     req => {
 634       $ENV{DBICTEST_MEMCACHED}
 635         ? (
 636           'Cache::Memcached' => 0,
 637         ) : ()
 638     },
 639   },
 640
 641   dist_dir => {
 642     req => {
 643       %$test_and_dist_json_any,
 644       'ExtUtils::MakeMaker' => '6.64',
 645       'Pod::Inherit'        => '0.91',
 646     },
 647   },
 648
 649   dist_upload => {
 650     req => {
 651       'CPAN::Uploader' => '0.103001',
 652     },
 653   },
 654
 655 };
 656
 657 our %req_availability_cache;
 658
 659 sub req_list_for {
 660   my ($class, $group) = @_;
 661
 662   Carp::croak "req_list_for() expects a requirement group name"
 663     unless $group;
 664
 665   my $deps = $reqs->{$group}{req}
 666     or Carp::croak "Requirement group '$group' does not exist";
 667
 668   return { %$deps };
 669 }
 670
 671
 672 sub die_unless_req_ok_for {
 673   my ($class, $group) = @_;
 674
 675   Carp::croak "die_unless_req_ok_for() expects a requirement group name"
 676     unless $group;
 677
 678   $class->_check_deps($group)->{status}
 679     or die sprintf( "Required modules missing, unable to continue: %s\n", $class->_check_deps($group)->{missing} );
 680 }
 681
 682 sub req_ok_for {
 683   my ($class, $group) = @_;
 684
 685   Carp::croak "req_ok_for() expects a requirement group name"
 686     unless $group;
 687
 688   return $class->_check_deps($group)->{status};
 689 }
 690
 691 sub req_missing_for {
 692   my ($class, $group) = @_;
 693
 694   Carp::croak "req_missing_for() expects a requirement group name"
 695     unless $group;
 696
 697   return $class->_check_deps($group)->{missing};
 698 }
 699
 700 sub req_errorlist_for {
 701   my ($class, $group) = @_;
 702
 703   Carp::croak "req_errorlist_for() expects a requirement group name"
 704     unless $group;
 705
 706   return $class->_check_deps($group)->{errorlist};
 707 }
 708
 709 sub _check_deps {
 710   my ($class, $group) = @_;
 711
 712   return $req_availability_cache{$group} ||= do {
 713
 714     my $deps = $class->req_list_for ($group);
 715
 716     my %errors;
 717     for my $mod (keys %$deps) {
 718       my $req_line = "require $mod;";
 719       if (my $ver = $deps->{$mod}) {
 720         $req_line .= "$mod->VERSION($ver);";
 721       }
 722
 723       eval $req_line;
 724
 725       $errors{$mod} = $@ if $@;
 726     }
 727
 728     my $res;
 729
 730     if (keys %errors) {
 731       my $missing = join (', ', map { $deps->{$_} ? "$_ >= $deps->{$_}" : $_ } (sort keys %errors) );
 732       $missing .= " (see $class for details)" if $reqs->{$group}{pod};
 733       $res = {
 734         status => 0,
 735         errorlist => \%errors,
 736         missing => $missing,
 737       };
 738     }
 739     else {
 740       $res = {
 741         status => 1,
 742         errorlist => {},
 743         missing => '',
 744       };
 745     }
 746
 747     $res;
 748   };
 749 }
 750
 751 sub req_group_list {
 752   return { map { $_ => { %{ $reqs->{$_}{req} || {} } } } (keys %$reqs) };
 753 }
 754
 755 # This is to be called by the author only (automatically in Makefile.PL)
 756 sub _gen_pod {
 757   my ($class, $distver, $pod_dir) = @_;
 758
 759   die "No POD root dir supplied" unless $pod_dir;
 760
 761   $distver ||=
 762     eval { require DBIx::Class; DBIx::Class->VERSION; }
 763       ||
 764     die
 765 "\n\n---------------------------------------------------------------------\n" .
 766 'Unable to load core DBIx::Class module to determine current version, '.
 767 'possibly due to missing dependencies. Author-mode autodocumentation ' .
 768 "halted\n\n" . $@ .
 769 "\n\n---------------------------------------------------------------------\n"
 770   ;
 771
 772   # do not ask for a recent version, use 1.x API calls
 773   # this *may* execute on a smoker with old perl or whatnot
 774   require File::Path;
 775
 776   (my $modfn = __PACKAGE__ . '.pm') =~ s|::|/|g;
 777
 778   (my $podfn = "$pod_dir/$modfn") =~ s/\.pm$/\.pod/;
 779   (my $dir = $podfn) =~ s|/[^/]+$||;
 780
 781   File::Path::mkpath([$dir]);
 782
 783   my $sqltver = $class->req_list_for ('deploy')->{'SQL::Translator'}
 784     or die "Hrmm? No sqlt dep?";
 785
 786   my @chunks = (
 787     <<"EOC",
 788 #########################################################################
 789 #####################  A U T O G E N E R A T E D ########################
 790 #########################################################################
 791 #
 792 # The contents of this POD file are auto-generated.  Any changes you make
 793 # will be lost. If you need to change the generated text edit _gen_pod()
 794 # at the end of $modfn
 795 #
 796 EOC
 797     '=head1 NAME',
 798     "$class - Optional module dependency specifications (for module authors)",
 799     '=head1 SYNOPSIS',
 800     <<"EOS",
 801 Somewhere in your build-file (e.g. L<Module::Install>'s Makefile.PL):
 802
 803   ...
 804
 805   configure_requires 'DBIx::Class' => '$distver';
 806
 807   require $class;
 808
 809   my \$deploy_deps = $class->req_list_for('deploy');
 810
 811   for (keys %\$deploy_deps) {
 812     requires \$_ => \$deploy_deps->{\$_};
 813   }
 814
 815   ...
 816
 817 Note that there are some caveats regarding C<configure_requires()>, more info
 818 can be found at L<Module::Install/configure_requires>
 819 EOS
 820     '=head1 DESCRIPTION',
 821     <<'EOD',
 822 Some of the less-frequently used features of L<DBIx::Class> have external
 823 module dependencies on their own. In order not to burden the average user
 824 with modules he will never use, these optional dependencies are not included
 825 in the base Makefile.PL. Instead an exception with a descriptive message is
 826 thrown when a specific feature is missing one or several modules required for
 827 its operation. This module is the central holding place for  the current list
 828 of such dependencies, for DBIx::Class core authors, and DBIx::Class extension
 829 authors alike.
 830 EOD
 831     '=head1 CURRENT REQUIREMENT GROUPS',
 832     <<'EOD',
 833 Dependencies are organized in C<groups> and each group can list one or more
 834 required modules, with an optional minimum version (or 0 for any version).
 835 The group name can be used in the
 836 EOD
 837   );
 838
 839   for my $group (sort keys %$reqs) {
 840     my $p = $reqs->{$group}{pod}
 841       or next;
 842
 843     my $modlist = $reqs->{$group}{req}
 844       or next;
 845
 846     next unless keys %$modlist;
 847
 848     push @chunks, (
 849       "=head2 $p->{title}",
 850       "$p->{desc}",
 851       '=over',
 852       ( map { "=item * $_" . ($modlist->{$_} ? " >= $modlist->{$_}" : '') } (sort keys %$modlist) ),
 853       '=back',
 854       "Requirement group: B<$group>",
 855     );
 856   }
 857
 858   push @chunks, (
 859     '=head1 METHODS',
 860     '=head2 req_group_list',
 861     '=over',
 862     '=item Arguments: none',
 863     '=item Return Value: \%list_of_requirement_groups',
 864     '=back',
 865     <<'EOD',
 866 This method should be used by DBIx::Class packagers, to get a hashref of all
 867 dependencies keyed by dependency group. Each key (group name) can be supplied
 868 to one of the group-specific methods below.
 869 EOD
 870
 871     '=head2 req_list_for',
 872     '=over',
 873     '=item Arguments: $group_name',
 874     '=item Return Value: \%list_of_module_version_pairs',
 875     '=back',
 876     <<'EOD',
 877 This method should be used by DBIx::Class extension authors, to determine the
 878 version of modules a specific feature requires in the B<current> version of
 879 DBIx::Class. See the L</SYNOPSIS> for a real-world
 880 example.
 881 EOD
 882
 883     '=head2 req_ok_for',
 884     '=over',
 885     '=item Arguments: $group_name',
 886     '=item Return Value: 1|0',
 887     '=back',
 888     <<'EOD',
 889 Returns true or false depending on whether all modules required by
 890 C<$group_name> are present on the system and loadable.
 891 EOD
 892
 893     '=head2 req_missing_for',
 894     '=over',
 895     '=item Arguments: $group_name',
 896     '=item Return Value: $error_message_string',
 897     '=back',
 898     <<"EOD",
 899 Returns a single line string suitable for inclusion in larger error messages.
 900 This method would normally be used by DBIx::Class core-module author, to
 901 indicate to the user that he needs to install specific modules before he will
 902 be able to use a specific feature.
 903
 904 For example if some of the requirements for C<deploy> are not available,
 905 the returned string could look like:
 906
 907  SQL::Translator >= $sqltver (see $class for details)
 908
 909 The author is expected to prepend the necessary text to this message before
 910 returning the actual error seen by the user.
 911 EOD
 912
 913     '=head2 die_unless_req_ok_for',
 914     '=over',
 915     '=item Arguments: $group_name',
 916     '=back',
 917     <<'EOD',
 918 Checks if L</req_ok_for> passes for the supplied C<$group_name>, and
 919 in case of failure throws an exception including the information
 920 from L</req_missing_for>.
 921 EOD
 922
 923     '=head2 req_errorlist_for',
 924     '=over',
 925     '=item Arguments: $group_name',
 926     '=item Return Value: \%list_of_loaderrors_per_module',
 927     '=back',
 928     <<'EOD',
 929 Returns a hashref containing the actual errors that occurred while attempting
 930 to load each module in the requirement group.
 931 EOD
 932     '=head1 FURTHER QUESTIONS?',
 933     'Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.',
 934     '=head1 COPYRIGHT AND LICENSE',
 935     <<'EOL',
 936 This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
 937 by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
 938 redistribute it and/or modify it under the same terms as the
 939 L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.
 940 EOL
 941
 942   );
 943
 944   open (my $fh, '>', $podfn) or Carp::croak "Unable to write to $podfn: $!";
 945   print $fh join ("\n\n", @chunks);
 946   print $fh "\n";
 947   close ($fh);
 948 }
 949
 950 1;