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.11016',
 154     },
 155     pod => {
 156       title => 'Storage::DBI::deploy()',
 157       desc => 'Modules required for L<DBIx::Class::Storage::DBI/deploy> and L<DBIx::Class::Storage::DBI/deployment_statements>',
 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       'Class::DBI::Plugin::DeepAbstractSearch' => '0',
 259       %$datetime_basic,
 260       'Time::Piece::MySQL'        => '0',
 261       'Date::Simple'              => '3.03',
 262     },
 263   },
 264
 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 => {
 279       # when changing this list make sure to adjust xt/optional_deps.t
 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',
 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',
 315     },
 316   },
 317
 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
 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
 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     },
 396   },
 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     },
 406   },
 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     },
 416   },
 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     },
 426   },
 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     },
 436   },
 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     },
 446   },
 447
 448 # the order does matter because the rdbms support group might require
 449 # a different version that the test group
 450   test_rdbms_pg => {
 451     req => {
 452       $ENV{DBICTEST_PG_DSN}
 453         ? (
 454           # when changing this list make sure to adjust xt/optional_deps.t
 455           %$rdbms_pg,
 456           ($^O ne 'MSWin32' ? ('Sys::SigAction' => '0') : ()),
 457           'DBD::Pg'               => '2.009002',
 458         ) : ()
 459     },
 460   },
 461
 462   test_rdbms_mssql_odbc => {
 463     req => {
 464       $ENV{DBICTEST_MSSQL_ODBC_DSN}
 465         ? (
 466           %$rdbms_mssql_odbc,
 467         ) : ()
 468     },
 469   },
 470
 471   test_rdbms_mssql_ado => {
 472     req => {
 473       $ENV{DBICTEST_MSSQL_ADO_DSN}
 474         ? (
 475           %$rdbms_mssql_ado,
 476         ) : ()
 477     },
 478   },
 479
 480   test_rdbms_mssql_sybase => {
 481     req => {
 482       $ENV{DBICTEST_MSSQL_DSN}
 483         ? (
 484           %$rdbms_mssql_sybase,
 485         ) : ()
 486     },
 487   },
 488
 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
 511   test_rdbms_mysql => {
 512     req => {
 513       $ENV{DBICTEST_MYSQL_DSN}
 514         ? (
 515           %$rdbms_mysql,
 516         ) : ()
 517     },
 518   },
 519
 520   test_rdbms_oracle => {
 521     req => {
 522       $ENV{DBICTEST_ORA_DSN}
 523         ? (
 524           %$rdbms_oracle,
 525           'DateTime::Format::Oracle' => '0',
 526           'DBD::Oracle'              => '1.24',
 527         ) : ()
 528     },
 529   },
 530
 531   test_rdbms_ase => {
 532     req => {
 533       $ENV{DBICTEST_SYBASE_DSN}
 534         ? (
 535           %$rdbms_ase,
 536         ) : ()
 537     },
 538   },
 539
 540   test_rdbms_db2 => {
 541     req => {
 542       $ENV{DBICTEST_DB2_DSN}
 543         ? (
 544           %$rdbms_db2,
 545         ) : ()
 546     },
 547   },
 548
 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
 603   test_rdbms_firebird_odbc => {
 604     req => {
 605       $ENV{DBICTEST_FIREBIRD_ODBC_DSN}
 606         ? (
 607           %$rdbms_firebird_odbc,
 608         ) : ()
 609     },
 610   },
 611
 612   test_memcached => {
 613     req => {
 614       $ENV{DBICTEST_MEMCACHED}
 615         ? (
 616           'Cache::Memcached' => 0,
 617         ) : ()
 618     },
 619   },
 620
 621   dist_dir => {
 622     req => {
 623       %$test_and_dist_json_any,
 624       'ExtUtils::MakeMaker' => '6.64',
 625       'Pod::Inherit'        => '0.90',
 626       'Pod::Tree'           => '0',
 627     }
 628   },
 629
 630   dist_upload => {
 631     req => {
 632       'CPAN::Uploader' => '0.103001',
 633     },
 634   },
 635
 636 };
 637
 638 our %req_availability_cache;
 639
 640 sub req_list_for {
 641   my ($class, $group) = @_;
 642
 643   Carp::croak "req_list_for() expects a requirement group name"
 644     unless $group;
 645
 646   my $deps = $reqs->{$group}{req}
 647     or Carp::croak "Requirement group '$group' does not exist";
 648
 649   return { %$deps };
 650 }
 651
 652
 653 sub die_unless_req_ok_for {
 654   my ($class, $group) = @_;
 655
 656   Carp::croak "die_unless_req_ok_for() expects a requirement group name"
 657     unless $group;
 658
 659   $class->_check_deps($group)->{status}
 660     or die sprintf( "Required modules missing, unable to continue: %s\n", $class->_check_deps($group)->{missing} );
 661 }
 662
 663 sub req_ok_for {
 664   my ($class, $group) = @_;
 665
 666   Carp::croak "req_ok_for() expects a requirement group name"
 667     unless $group;
 668
 669   return $class->_check_deps($group)->{status};
 670 }
 671
 672 sub req_missing_for {
 673   my ($class, $group) = @_;
 674
 675   Carp::croak "req_missing_for() expects a requirement group name"
 676     unless $group;
 677
 678   return $class->_check_deps($group)->{missing};
 679 }
 680
 681 sub req_errorlist_for {
 682   my ($class, $group) = @_;
 683
 684   Carp::croak "req_errorlist_for() expects a requirement group name"
 685     unless $group;
 686
 687   return $class->_check_deps($group)->{errorlist};
 688 }
 689
 690 sub _check_deps {
 691   my ($class, $group) = @_;
 692
 693   return $req_availability_cache{$group} ||= do {
 694
 695     my $deps = $class->req_list_for ($group);
 696
 697     my %errors;
 698     for my $mod (keys %$deps) {
 699       my $req_line = "require $mod;";
 700       if (my $ver = $deps->{$mod}) {
 701         $req_line .= "$mod->VERSION($ver);";
 702       }
 703
 704       eval $req_line;
 705
 706       $errors{$mod} = $@ if $@;
 707     }
 708
 709     my $res;
 710
 711     if (keys %errors) {
 712       my $missing = join (', ', map { $deps->{$_} ? "$_ >= $deps->{$_}" : $_ } (sort keys %errors) );
 713       $missing .= " (see $class for details)" if $reqs->{$group}{pod};
 714       $res = {
 715         status => 0,
 716         errorlist => \%errors,
 717         missing => $missing,
 718       };
 719     }
 720     else {
 721       $res = {
 722         status => 1,
 723         errorlist => {},
 724         missing => '',
 725       };
 726     }
 727
 728     $res;
 729   };
 730 }
 731
 732 sub req_group_list {
 733   return { map { $_ => { %{ $reqs->{$_}{req} || {} } } } (keys %$reqs) };
 734 }
 735
 736 # This is to be called by the author only (automatically in Makefile.PL)
 737 sub _gen_pod {
 738   my ($class, $distver, $pod_dir) = @_;
 739
 740   die "No POD root dir supplied" unless $pod_dir;
 741
 742   $distver ||=
 743     eval { require DBIx::Class; DBIx::Class->VERSION; }
 744       ||
 745     die
 746 "\n\n---------------------------------------------------------------------\n" .
 747 'Unable to load core DBIx::Class module to determine current version, '.
 748 'possibly due to missing dependencies. Author-mode autodocumentation ' .
 749 "halted\n\n" . $@ .
 750 "\n\n---------------------------------------------------------------------\n"
 751   ;
 752
 753   # do not ask for a recent version, use 1.x API calls
 754   # this *may* execute on a smoker with old perl or whatnot
 755   require File::Path;
 756
 757   (my $modfn = __PACKAGE__ . '.pm') =~ s|::|/|g;
 758
 759   (my $podfn = "$pod_dir/$modfn") =~ s/\.pm$/\.pod/;
 760   (my $dir = $podfn) =~ s|/[^/]+$||;
 761
 762   File::Path::mkpath([$dir]);
 763
 764   my $sqltver = $class->req_list_for ('deploy')->{'SQL::Translator'}
 765     or die "Hrmm? No sqlt dep?";
 766
 767   my @chunks = (
 768     <<"EOC",
 769 #########################################################################
 770 #####################  A U T O G E N E R A T E D ########################
 771 #########################################################################
 772 #
 773 # The contents of this POD file are auto-generated.  Any changes you make
 774 # will be lost. If you need to change the generated text edit _gen_pod()
 775 # at the end of $modfn
 776 #
 777 EOC
 778     '=head1 NAME',
 779     "$class - Optional module dependency specifications (for module authors)",
 780     '=head1 SYNOPSIS',
 781     <<"EOS",
 782 Somewhere in your build-file (e.g. L<Module::Install>'s Makefile.PL):
 783
 784   ...
 785
 786   configure_requires 'DBIx::Class' => '$distver';
 787
 788   require $class;
 789
 790   my \$deploy_deps = $class->req_list_for('deploy');
 791
 792   for (keys %\$deploy_deps) {
 793     requires \$_ => \$deploy_deps->{\$_};
 794   }
 795
 796   ...
 797
 798 Note that there are some caveats regarding C<configure_requires()>, more info
 799 can be found at L<Module::Install/configure_requires>
 800 EOS
 801     '=head1 DESCRIPTION',
 802     <<'EOD',
 803 Some of the less-frequently used features of L<DBIx::Class> have external
 804 module dependencies on their own. In order not to burden the average user
 805 with modules he will never use, these optional dependencies are not included
 806 in the base Makefile.PL. Instead an exception with a descriptive message is
 807 thrown when a specific feature is missing one or several modules required for
 808 its operation. This module is the central holding place for  the current list
 809 of such dependencies, for DBIx::Class core authors, and DBIx::Class extension
 810 authors alike.
 811 EOD
 812     '=head1 CURRENT REQUIREMENT GROUPS',
 813     <<'EOD',
 814 Dependencies are organized in C<groups> and each group can list one or more
 815 required modules, with an optional minimum version (or 0 for any version).
 816 The group name can be used in the
 817 EOD
 818   );
 819
 820   for my $group (sort keys %$reqs) {
 821     my $p = $reqs->{$group}{pod}
 822       or next;
 823
 824     my $modlist = $reqs->{$group}{req}
 825       or next;
 826
 827     next unless keys %$modlist;
 828
 829     push @chunks, (
 830       "=head2 $p->{title}",
 831       "$p->{desc}",
 832       '=over',
 833       ( map { "=item * $_" . ($modlist->{$_} ? " >= $modlist->{$_}" : '') } (sort keys %$modlist) ),
 834       '=back',
 835       "Requirement group: B<$group>",
 836     );
 837   }
 838
 839   push @chunks, (
 840     '=head1 METHODS',
 841     '=head2 req_group_list',
 842     '=over',
 843     '=item Arguments: none',
 844     '=item Return Value: \%list_of_requirement_groups',
 845     '=back',
 846     <<'EOD',
 847 This method should be used by DBIx::Class packagers, to get a hashref of all
 848 dependencies keyed by dependency group. Each key (group name) can be supplied
 849 to one of the group-specific methods below.
 850 EOD
 851
 852     '=head2 req_list_for',
 853     '=over',
 854     '=item Arguments: $group_name',
 855     '=item Return Value: \%list_of_module_version_pairs',
 856     '=back',
 857     <<'EOD',
 858 This method should be used by DBIx::Class extension authors, to determine the
 859 version of modules a specific feature requires in the B<current> version of
 860 DBIx::Class. See the L</SYNOPSIS> for a real-world
 861 example.
 862 EOD
 863
 864     '=head2 req_ok_for',
 865     '=over',
 866     '=item Arguments: $group_name',
 867     '=item Return Value: 1|0',
 868     '=back',
 869     <<'EOD',
 870 Returns true or false depending on whether all modules required by
 871 C<$group_name> are present on the system and loadable.
 872 EOD
 873
 874     '=head2 req_missing_for',
 875     '=over',
 876     '=item Arguments: $group_name',
 877     '=item Return Value: $error_message_string',
 878     '=back',
 879     <<"EOD",
 880 Returns a single line string suitable for inclusion in larger error messages.
 881 This method would normally be used by DBIx::Class core-module author, to
 882 indicate to the user that he needs to install specific modules before he will
 883 be able to use a specific feature.
 884
 885 For example if some of the requirements for C<deploy> are not available,
 886 the returned string could look like:
 887
 888  SQL::Translator >= $sqltver (see $class for details)
 889
 890 The author is expected to prepend the necessary text to this message before
 891 returning the actual error seen by the user.
 892 EOD
 893
 894     '=head2 die_unless_req_ok_for',
 895     '=over',
 896     '=item Arguments: $group_name',
 897     '=back',
 898     <<'EOD',
 899 Checks if L</req_ok_for> passes for the supplied C<$group_name>, and
 900 in case of failure throws an exception including the information
 901 from L</req_missing_for>.
 902 EOD
 903
 904     '=head2 req_errorlist_for',
 905     '=over',
 906     '=item Arguments: $group_name',
 907     '=item Return Value: \%list_of_loaderrors_per_module',
 908     '=back',
 909     <<'EOD',
 910 Returns a hashref containing the actual errors that occurred while attempting
 911 to load each module in the requirement group.
 912 EOD
 913     '=head1 AUTHOR',
 914     'See L<DBIx::Class/CONTRIBUTORS>.',
 915     '=head1 LICENSE',
 916     'You may distribute this code under the same terms as Perl itself',
 917   );
 918
 919   open (my $fh, '>', $podfn) or Carp::croak "Unable to write to $podfn: $!";
 920   print $fh join ("\n\n", @chunks);
 921   print $fh "\n";
 922   close ($fh);
 923 }
 924
 925 1;