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       '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           'DBD::Pg'               => '2.009002',
 457         ) : ()
 458     },
 459   },
 460
 461   test_rdbms_mssql_odbc => {
 462     req => {
 463       $ENV{DBICTEST_MSSQL_ODBC_DSN}
 464         ? (
 465           %$rdbms_mssql_odbc,
 466         ) : ()
 467     },
 468   },
 469
 470   test_rdbms_mssql_ado => {
 471     req => {
 472       $ENV{DBICTEST_MSSQL_ADO_DSN}
 473         ? (
 474           %$rdbms_mssql_ado,
 475         ) : ()
 476     },
 477   },
 478
 479   test_rdbms_mssql_sybase => {
 480     req => {
 481       $ENV{DBICTEST_MSSQL_DSN}
 482         ? (
 483           %$rdbms_mssql_sybase,
 484         ) : ()
 485     },
 486   },
 487
 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
 510   test_rdbms_mysql => {
 511     req => {
 512       $ENV{DBICTEST_MYSQL_DSN}
 513         ? (
 514           %$rdbms_mysql,
 515         ) : ()
 516     },
 517   },
 518
 519   test_rdbms_oracle => {
 520     req => {
 521       $ENV{DBICTEST_ORA_DSN}
 522         ? (
 523           %$rdbms_oracle,
 524           'DateTime::Format::Oracle' => '0',
 525           'DBD::Oracle'              => '1.24',
 526         ) : ()
 527     },
 528   },
 529
 530   test_rdbms_ase => {
 531     req => {
 532       $ENV{DBICTEST_SYBASE_DSN}
 533         ? (
 534           %$rdbms_ase,
 535         ) : ()
 536     },
 537   },
 538
 539   test_rdbms_db2 => {
 540     req => {
 541       $ENV{DBICTEST_DB2_DSN}
 542         ? (
 543           %$rdbms_db2,
 544         ) : ()
 545     },
 546   },
 547
 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
 602   test_rdbms_firebird_odbc => {
 603     req => {
 604       $ENV{DBICTEST_FIREBIRD_ODBC_DSN}
 605         ? (
 606           %$rdbms_firebird_odbc,
 607         ) : ()
 608     },
 609   },
 610
 611   test_memcached => {
 612     req => {
 613       $ENV{DBICTEST_MEMCACHED}
 614         ? (
 615           'Cache::Memcached' => 0,
 616         ) : ()
 617     },
 618   },
 619
 620   dist_dir => {
 621     req => {
 622       %$test_and_dist_json_any,
 623       'ExtUtils::MakeMaker' => '6.64',
 624       'Pod::Inherit'        => '0.91',
 625     },
 626   },
 627
 628   dist_upload => {
 629     req => {
 630       'CPAN::Uploader' => '0.103001',
 631     },
 632   },
 633
 634 };
 635
 636
 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 #
 645 sub req_list_for {
 646   my ($class, $group) = @_;
 647
 648   croak "req_list_for() expects a requirement group name"
 649     unless $group;
 650
 651   my $deps = $reqs->{$group}{req}
 652     or croak "Requirement group '$group' does not exist";
 653
 654   return { %$deps };
 655 }
 656
 657 sub req_group_list {
 658   return { map { $_ => { %{ $reqs->{$_}{req} || {} } } } (keys %$reqs) };
 659 }
 660
 661 sub req_errorlist_for {
 662   my ($class, $group) = @_;
 663
 664   croak "req_errorlist_for() expects a requirement group name"
 665     unless $group;
 666
 667   return $class->_check_deps($group)->{errorlist};
 668 }
 669
 670 sub req_ok_for {
 671   my ($class, $group) = @_;
 672
 673   croak "req_ok_for() expects a requirement group name"
 674     unless $group;
 675
 676   return $class->_check_deps($group)->{status};
 677 }
 678
 679 sub req_missing_for {
 680   my ($class, $group) = @_;
 681
 682   croak "req_missing_for() expects a requirement group name"
 683     unless $group;
 684
 685   return $class->_check_deps($group)->{missing};
 686 }
 687
 688 sub die_unless_req_ok_for {
 689   my ($class, $group) = @_;
 690
 691   croak "die_unless_req_ok_for() expects a requirement group name"
 692     unless $group;
 693
 694   $class->_check_deps($group)->{status}
 695     or die sprintf( "Required modules missing, unable to continue: %s\n", $class->_check_deps($group)->{missing} );
 696 }
 697
 698
 699
 700 ### Private OO API
 701
 702 our %req_availability_cache;
 703 sub _check_deps {
 704   my ($class, $group) = @_;
 705
 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;
 723
 724     if (keys %errors) {
 725       my $missing = join (', ', map { $deps->{$_} ? qq("${_}~>=$deps->{$_}") : $_ } (sort keys %errors) );
 726       $missing .= " (see $class documentation for details)" if $reqs->{$group}{pod};
 727       $res = {
 728         status => 0,
 729         errorlist => \%errors,
 730         missing => $missing,
 731       };
 732     }
 733     else {
 734       $res = {
 735         status => 1,
 736         errorlist => {},
 737         missing => '',
 738       };
 739     }
 740
 741     $res;
 742   };
 743 }
 744
 745 # This is to be called by the author only (automatically in Makefile.PL)
 746 sub _gen_pod {
 747   my ($class, $distver, $pod_dir) = @_;
 748
 749   die "No POD root dir supplied" unless $pod_dir;
 750
 751   $distver ||=
 752     eval { require DBIx::Class; DBIx::Class->VERSION; }
 753       ||
 754     die
 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"
 760   ;
 761
 762   # do not ask for a recent version, use 1.x API calls
 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
 773   my $sqltver = $class->req_list_for ('deploy')->{'SQL::Translator'}
 774     or die "Hrmm? No sqlt dep?";
 775
 776
 777   my @chunks;
 778
 779 #@@
 780 #@@ HEADER
 781 #@@
 782   push @chunks, <<"EOC";
 783 #########################################################################
 784 #####################  A U T O G E N E R A T E D ########################
 785 #########################################################################
 786 #
 787 # The contents of this POD file are auto-generated.  Any changes you make
 788 # will be lost. If you need to change the generated text edit _gen_pod()
 789 # at the end of $modfn
 790 #
 791
 792 =head1 NAME
 793
 794 $class - Optional module dependency specifications (for module authors)
 795 EOC
 796
 797
 798 #@@
 799 #@@ SYNOPSIS HEADING
 800 #@@
 801   push @chunks, <<"EOC";
 802 =head1 SYNOPSIS
 803
 804 Somewhere in your build-file (e.g. L<ExtUtils::MakeMaker>'s F<Makefile.PL>):
 805
 806   ...
 807
 808   \$EUMM_ARGS{CONFIGURE_REQUIRES} = {
 809     \%{ \$EUMM_ARGS{CONFIGURE_REQUIRES} || {} },
 810     'DBIx::Class' => '$distver',
 811   };
 812
 813   ...
 814
 815   my %DBIC_DEPLOY_DEPS = %{ eval {
 816     require $class;
 817     $class->req_list_for('deploy');
 818   } || {} };
 819
 820   \$EUMM_ARGS{PREREQ_PM} = {
 821     \%DBIC_DEPLOY_DEPS,
 822     \%{ \$EUMM_ARGS{PREREQ_PM} || {} },
 823   };
 824
 825   ...
 826
 827   ExtUtils::MakeMaker::WriteMakefile(\%EUMM_ARGS);
 828
 829 B<Note>: The C<eval> protection within the example is due to support for
 830 requirements during L<the C<configure> build phase|CPAN::Meta::Spec/Phases>
 831 not being available on a sufficient portion of production installations of
 832 Perl. Robust support for such dependency requirements is available in the
 833 L<CPAN> installer only since version C<1.94_56> first made available for
 834 production with perl version C<5.12>. It is the belief of the current
 835 maintainer that support for requirements during the C<configure> build phase
 836 will not be sufficiently ubiquitous until the B<year 2020> at the earliest,
 837 hence the extra care demonstrated above. It should also be noted that some
 838 3rd party installers (e.g. L<cpanminus|App::cpanminus>) do the right thing
 839 with configure requirements independent from the versions of perl and CPAN
 840 available.
 841 EOC
 842
 843
 844 #@@
 845 #@@ DESCRIPTION HEADING
 846 #@@
 847   push @chunks, <<'EOC';
 848 =head1 DESCRIPTION
 849
 850 Some of the less-frequently used features of L<DBIx::Class> have external
 851 module dependencies on their own. In order not to burden the average user
 852 with modules they will never use, these optional dependencies are not included
 853 in the base Makefile.PL. Instead an exception with a descriptive message is
 854 thrown when a specific feature can't find one or several modules required for
 855 its operation. This module is the central holding place for the current list
 856 of such dependencies, for DBIx::Class core authors, and DBIx::Class extension
 857 authors alike.
 858
 859 Dependencies are organized in L<groups|/CURRENT REQUIREMENT GROUPS> where each
 860 group can list one or more required modules, with an optional minimum version
 861 (or 0 for any version). The group name can be used in the
 862 L<public methods|/METHODS> as described below.
 863 EOC
 864
 865
 866 #@@
 867 #@@ REQUIREMENT GROUPLIST HEADING
 868 #@@
 869   push @chunks, '=head1 CURRENT REQUIREMENT GROUPS';
 870
 871   for my $group (sort keys %$reqs) {
 872     my $p = $reqs->{$group}{pod}
 873       or next;
 874
 875     my $modlist = $reqs->{$group}{req}
 876       or next;
 877
 878     next unless keys %$modlist;
 879
 880     push @chunks, (
 881       "=head2 $p->{title}",
 882       "$p->{desc}",
 883       '=over',
 884       ( map { "=item * $_" . ($modlist->{$_} ? " >= $modlist->{$_}" : '') } (sort keys %$modlist) ),
 885       '=back',
 886       "Requirement group: B<$group>",
 887     );
 888   }
 889
 890
 891 #@@
 892 #@@ API DOCUMENTATION HEADING
 893 #@@
 894   push @chunks, <<'EOC';
 895
 896 =head1 METHODS
 897
 898 =head2 req_group_list
 899
 900 =over
 901
 902 =item Arguments: none
 903
 904 =item Return Value: \%list_of_requirement_groups
 905
 906 =back
 907
 908 This method should be used by DBIx::Class packagers, to get a hashref of all
 909 dependencies keyed by dependency group. Each key (group name) can be supplied
 910 to one of the group-specific methods below.
 911 The B<values> of the returned hash are currently a set of options B<without a
 912 well defined structure>. If you have use for any of the contents - contact the
 913 maintainers, instead of treating this as public (left alone stable) API.
 914
 915 =head2 req_list_for
 916
 917 =over
 918
 919 =item Arguments: $group_name
 920
 921 =item Return Value: \%list_of_module_version_pairs
 922
 923 =back
 924
 925 This method should be used by DBIx::Class extension authors, to determine the
 926 version of modules a specific feature requires in the B<current> version of
 927 DBIx::Class. See the L</SYNOPSIS> for a real-world example.
 928
 929 =head2 req_ok_for
 930
 931 =over
 932
 933 =item Arguments: $group_name
 934
 935 =item Return Value: 1|0
 936
 937 =back
 938
 939 Returns true or false depending on whether all modules required by
 940 C<$group_name> are present on the system and loadable.
 941
 942 =head2 req_missing_for
 943
 944 =over
 945
 946 =item Arguments: $group_name
 947
 948 =item Return Value: $error_message_string
 949
 950 =back
 951
 952 This method would normally be used by DBIx::Class core-modules, to indicate to
 953 the user that they need to install specific modules before being able to use a
 954 specific feature set.
 955
 956 For example if some of the requirements for C<deploy> are not available,
 957 the returned string could look like:
 958 EOC
 959
 960   push @chunks, qq{ "SQL::Translator~>=$sqltver" (see $class documentation for details)};
 961
 962   push @chunks, <<'EOC';
 963 The author is expected to prepend the necessary text to this message before
 964 returning the actual error seen by the user.
 965
 966 =head2 die_unless_req_ok_for
 967
 968 =over
 969
 970 =item Arguments: $group_name
 971
 972 =back
 973
 974 Checks if L</req_ok_for> passes for the supplied C<$group_name>, and
 975 in case of failure throws an exception including the information
 976 from L</req_missing_for>.
 977
 978 =head2 req_errorlist_for
 979
 980 =over
 981
 982 =item Arguments: $group_name
 983
 984 =item Return Value: \%list_of_loaderrors_per_module
 985
 986 =back
 987
 988 Returns a hashref containing the actual errors that occurred while attempting
 989 to load each module in the requirement group.
 990 EOC
 991
 992 #@@
 993 #@@ FOOTER
 994 #@@
 995   push @chunks, <<'EOC';
 996 =head1 FURTHER QUESTIONS?
 997
 998 Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
 999
1000 =head1 COPYRIGHT AND LICENSE
1001
1002 This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
1003 by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
1004 redistribute it and/or modify it under the same terms as the
1005 L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.
1006 EOC
1007
1008   eval {
1009     open (my $fh, '>', $podfn) or die;
1010     print $fh join ("\n\n", @chunks) or die;
1011     print $fh "\n" or die;
1012     close ($fh) or die;
1013   } or croak( "Unable to write $podfn: " . ( $! || $@ || 'unknown error') );
1014 }
1015
1016 1;