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   'Digest::MD5'                   => '0',
  55   'Math::BigInt'                  => '1.80',
  56   'Math::Base36'                  => '0.07',
  57 };
  58
  59 my $rdbms_sqlite = {
  60   'DBD::SQLite'                   => '0',
  61 };
  62 my $rdbms_pg = {
  63   'DBD::Pg'                       => '0',
  64 };
  65 my $rdbms_mssql_odbc = {
  66   'DBD::ODBC'                     => '0',
  67 };
  68 my $rdbms_mssql_sybase = {
  69   'DBD::Sybase'                   => '0',
  70 };
  71 my $rdbms_mssql_ado = {
  72   'DBD::ADO'                      => '0',
  73 };
  74 my $rdbms_msaccess_odbc = {
  75   'DBD::ODBC'                     => '0',
  76 };
  77 my $rdbms_msaccess_ado = {
  78   'DBD::ADO'                      => '0',
  79 };
  80 my $rdbms_mysql = {
  81   'DBD::mysql'                    => '0',
  82 };
  83 my $rdbms_oracle = {
  84   'DBD::Oracle'                   => '0',
  85   %$id_shortener,
  86 };
  87 my $rdbms_ase = {
  88   'DBD::Sybase'                   => '0',
  89 };
  90 my $rdbms_db2 = {
  91   'DBD::DB2'                      => '0',
  92 };
  93 my $rdbms_db2_400 = {
  94   'DBD::ODBC'                     => '0',
  95 };
  96 my $rdbms_informix = {
  97   'DBD::Informix'                 => '0',
  98 };
  99 my $rdbms_sqlanywhere = {
 100   'DBD::SQLAnywhere'              => '0',
 101 };
 102 my $rdbms_sqlanywhere_odbc = {
 103   'DBD::ODBC'                     => '0',
 104 };
 105 my $rdbms_firebird = {
 106   'DBD::Firebird'                 => '0',
 107 };
 108 my $rdbms_firebird_interbase = {
 109   'DBD::InterBase'                => '0',
 110 };
 111 my $rdbms_firebird_odbc = {
 112   'DBD::ODBC'                     => '0',
 113 };
 114
 115 my $reqs = {
 116   replicated => {
 117     req => $replicated,
 118     pod => {
 119       title => 'Storage::Replicated',
 120       desc => 'Modules required for L<DBIx::Class::Storage::DBI::Replicated>',
 121     },
 122   },
 123
 124   test_replicated => {
 125     req => {
 126       %$replicated,
 127       'Test::Moose'               => '0',
 128     },
 129   },
 130
 131
 132   admin => {
 133     req => {
 134       %$admin_basic,
 135     },
 136     pod => {
 137       title => 'DBIx::Class::Admin',
 138       desc => 'Modules required for the DBIx::Class administrative library',
 139     },
 140   },
 141
 142   admin_script => {
 143     req => {
 144       %$admin_script,
 145     },
 146     pod => {
 147       title => 'dbicadmin',
 148       desc => 'Modules required for the CLI DBIx::Class interface dbicadmin',
 149     },
 150   },
 151
 152   deploy => {
 153     req => {
 154       'SQL::Translator'           => '0.11018',
 155     },
 156     pod => {
 157       title => 'Storage::DBI::deploy()',
 158       desc => 'Modules required for L<DBIx::Class::Storage::DBI/deployment_statements> and L<DBIx::Class::Schema/deploy>',
 159     },
 160   },
 161
 162   id_shortener => {
 163     req => $id_shortener,
 164   },
 165
 166   test_component_accessor => {
 167     req => {
 168       'Class::Unload'             => '0.07',
 169     },
 170   },
 171
 172   test_pod => {
 173     req => {
 174       'Test::Pod'                 => '1.42',
 175     },
 176   },
 177
 178   test_podcoverage => {
 179     req => {
 180       'Test::Pod::Coverage'       => '1.08',
 181       'Pod::Coverage'             => '0.20',
 182     },
 183   },
 184
 185   test_whitespace => {
 186     req => {
 187       'Test::EOL'                 => '1.0',
 188       'Test::NoTabs'              => '0.9',
 189     },
 190   },
 191
 192   test_strictures => {
 193     req => {
 194       'Test::Strict'              => '0.20',
 195     },
 196   },
 197
 198   test_prettydebug => {
 199     req => $min_json_any,
 200   },
 201
 202   test_admin_script => {
 203     req => {
 204       %$admin_script,
 205       %$test_and_dist_json_any,
 206       'JSON' => 0,
 207       'JSON::PP' => 0,
 208       'Cpanel::JSON::XS' => 0,
 209       'JSON::XS' => 0,
 210       $^O eq 'MSWin32'
 211         # for t/admin/10script.t
 212         ? ('Win32::ShellQuote' => 0)
 213         # DWIW does not compile (./configure even) on win32
 214         : ('JSON::DWIW' => 0 )
 215       ,
 216     }
 217   },
 218
 219   test_leaks_heavy => {
 220     req => {
 221       'Class::MethodCache' => '0.02',
 222       'PadWalker' => '1.06',
 223     },
 224   },
 225
 226   test_dt => {
 227     req => $datetime_basic,
 228   },
 229
 230   test_dt_sqlite => {
 231     req => {
 232       %$datetime_basic,
 233       # t/36datetime.t
 234       # t/60core.t
 235       'DateTime::Format::SQLite'  => '0',
 236     },
 237   },
 238
 239   test_dt_mysql => {
 240     req => {
 241       %$datetime_basic,
 242       # t/inflate/datetime_mysql.t
 243       # (doesn't need Mysql itself)
 244       'DateTime::Format::MySQL'   => '0',
 245     },
 246   },
 247
 248   test_dt_pg => {
 249     req => {
 250       %$datetime_basic,
 251       # t/inflate/datetime_pg.t
 252       # (doesn't need PG itself)
 253       'DateTime::Format::Pg'      => '0.16004',
 254     },
 255   },
 256
 257   test_cdbicompat => {
 258     req => {
 259       'Class::DBI::Plugin::DeepAbstractSearch' => '0',
 260       %$datetime_basic,
 261       'Time::Piece::MySQL'        => '0',
 262       'Date::Simple'              => '3.03',
 263     },
 264   },
 265
 266   # this is just for completeness as SQLite
 267   # is a core dep of DBIC for testing
 268   rdbms_sqlite => {
 269     req => {
 270       %$rdbms_sqlite,
 271     },
 272     pod => {
 273       title => 'SQLite support',
 274       desc => 'Modules required to connect to SQLite',
 275     },
 276   },
 277
 278   rdbms_pg => {
 279     req => {
 280       # when changing this list make sure to adjust xt/optional_deps.t
 281       %$rdbms_pg,
 282     },
 283     pod => {
 284       title => 'PostgreSQL support',
 285       desc => 'Modules required to connect to PostgreSQL',
 286     },
 287   },
 288
 289   rdbms_mssql_odbc => {
 290     req => {
 291       %$rdbms_mssql_odbc,
 292     },
 293     pod => {
 294       title => 'MSSQL support via DBD::ODBC',
 295       desc => 'Modules required to connect to MSSQL via DBD::ODBC',
 296     },
 297   },
 298
 299   rdbms_mssql_sybase => {
 300     req => {
 301       %$rdbms_mssql_sybase,
 302     },
 303     pod => {
 304       title => 'MSSQL support via DBD::Sybase',
 305       desc => 'Modules required to connect to MSSQL via DBD::Sybase',
 306     },
 307   },
 308
 309   rdbms_mssql_ado => {
 310     req => {
 311       %$rdbms_mssql_ado,
 312     },
 313     pod => {
 314       title => 'MSSQL support via DBD::ADO (Windows only)',
 315       desc => 'Modules required to connect to MSSQL via DBD::ADO. This particular DBD is available on Windows only',
 316     },
 317   },
 318
 319   rdbms_msaccess_odbc => {
 320     req => {
 321       %$rdbms_msaccess_odbc,
 322     },
 323     pod => {
 324       title => 'MS Access support via DBD::ODBC',
 325       desc => 'Modules required to connect to MS Access via DBD::ODBC',
 326     },
 327   },
 328
 329   rdbms_msaccess_ado => {
 330     req => {
 331       %$rdbms_msaccess_ado,
 332     },
 333     pod => {
 334       title => 'MS Access support via DBD::ADO (Windows only)',
 335       desc => 'Modules required to connect to MS Access via DBD::ADO. This particular DBD is available on Windows only',
 336     },
 337   },
 338
 339   rdbms_mysql => {
 340     req => {
 341       %$rdbms_mysql,
 342     },
 343     pod => {
 344       title => 'MySQL support',
 345       desc => 'Modules required to connect to MySQL',
 346     },
 347   },
 348
 349   rdbms_oracle => {
 350     req => {
 351       %$rdbms_oracle,
 352     },
 353     pod => {
 354       title => 'Oracle support',
 355       desc => 'Modules required to connect to Oracle',
 356     },
 357   },
 358
 359   rdbms_ase => {
 360     req => {
 361       %$rdbms_ase,
 362     },
 363     pod => {
 364       title => 'Sybase ASE support',
 365       desc => 'Modules required to connect to Sybase ASE',
 366     },
 367   },
 368
 369   rdbms_db2 => {
 370     req => {
 371       %$rdbms_db2,
 372     },
 373     pod => {
 374       title => 'DB2 support',
 375       desc => 'Modules required to connect to DB2',
 376     },
 377   },
 378
 379   rdbms_db2_400 => {
 380     req => {
 381       %$rdbms_db2_400,
 382     },
 383     pod => {
 384       title => 'DB2 on AS/400 support',
 385       desc => 'Modules required to connect to DB2 on AS/400',
 386     },
 387   },
 388
 389   rdbms_informix => {
 390     req => {
 391       %$rdbms_informix,
 392     },
 393     pod => {
 394       title => 'Informix support',
 395       desc => 'Modules required to connect to Informix',
 396     },
 397   },
 398
 399   rdbms_sqlanywhere => {
 400     req => {
 401       %$rdbms_sqlanywhere,
 402     },
 403     pod => {
 404       title => 'SQLAnywhere support',
 405       desc => 'Modules required to connect to SQLAnywhere',
 406     },
 407   },
 408
 409   rdbms_sqlanywhere_odbc => {
 410     req => {
 411       %$rdbms_sqlanywhere_odbc,
 412     },
 413     pod => {
 414       title => 'SQLAnywhere support via DBD::ODBC',
 415       desc => 'Modules required to connect to SQLAnywhere via DBD::ODBC',
 416     },
 417   },
 418
 419   rdbms_firebird => {
 420     req => {
 421       %$rdbms_firebird,
 422     },
 423     pod => {
 424       title => 'Firebird support',
 425       desc => 'Modules required to connect to Firebird',
 426     },
 427   },
 428
 429   rdbms_firebird_interbase => {
 430     req => {
 431       %$rdbms_firebird_interbase,
 432     },
 433     pod => {
 434       title => 'Firebird support via DBD::InterBase',
 435       desc => 'Modules required to connect to Firebird via DBD::InterBase',
 436     },
 437   },
 438
 439   rdbms_firebird_odbc => {
 440     req => {
 441       %$rdbms_firebird_odbc,
 442     },
 443     pod => {
 444       title => 'Firebird support via DBD::ODBC',
 445       desc => 'Modules required to connect to Firebird via DBD::ODBC',
 446     },
 447   },
 448
 449 # the order does matter because the rdbms support group might require
 450 # a different version that the test group
 451   test_rdbms_pg => {
 452     req => {
 453       $ENV{DBICTEST_PG_DSN}
 454         ? (
 455           # when changing this list make sure to adjust xt/optional_deps.t
 456           %$rdbms_pg,
 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.91',
 626     },
 627   },
 628
 629   dist_upload => {
 630     req => {
 631       'CPAN::Uploader' => '0.103001',
 632     },
 633   },
 634
 635 };
 636
 637
 638
 639 ### Public API
 640
 641 # OO for (mistakenly considered) ease of extensibility, not due to any need to
 642 # carry state of any sort. This API is currently used outside, so leave as-is.
 643 # FIXME - make sure to not propagate this further if module is extracted as a
 644 # standalone library - keep the stupidity to a DBIC-secific shim!
 645 #
 646 sub req_list_for {
 647   my ($class, $group) = @_;
 648
 649   croak "req_list_for() expects a requirement group name"
 650     unless $group;
 651
 652   my $deps = $reqs->{$group}{req}
 653     or croak "Requirement group '$group' does not exist";
 654
 655   return { %$deps };
 656 }
 657
 658 sub req_group_list {
 659   return { map { $_ => { %{ $reqs->{$_}{req} || {} } } } (keys %$reqs) };
 660 }
 661
 662 sub req_errorlist_for {
 663   my ($class, $group) = @_;
 664
 665   croak "req_errorlist_for() expects a requirement group name"
 666     unless $group;
 667
 668   return $class->_check_deps($group)->{errorlist};
 669 }
 670
 671 sub req_ok_for {
 672   my ($class, $group) = @_;
 673
 674   croak "req_ok_for() expects a requirement group name"
 675     unless $group;
 676
 677   return $class->_check_deps($group)->{status};
 678 }
 679
 680 sub req_missing_for {
 681   my ($class, $group) = @_;
 682
 683   croak "req_missing_for() expects a requirement group name"
 684     unless $group;
 685
 686   return $class->_check_deps($group)->{missing};
 687 }
 688
 689 sub die_unless_req_ok_for {
 690   my ($class, $group) = @_;
 691
 692   croak "die_unless_req_ok_for() expects a requirement group name"
 693     unless $group;
 694
 695   $class->_check_deps($group)->{status}
 696     or die sprintf( "Required modules missing, unable to continue: %s\n", $class->_check_deps($group)->{missing} );
 697 }
 698
 699
 700
 701 ### Private API
 702
 703 our %req_availability_cache;
 704 sub _check_deps {
 705   my ($class, $group) = @_;
 706
 707   return $req_availability_cache{$group} ||= do {
 708
 709     my $deps = $class->req_list_for ($group);
 710
 711     my %errors;
 712     for my $mod (keys %$deps) {
 713       my $req_line = "require $mod;";
 714       if (my $ver = $deps->{$mod}) {
 715         $req_line .= "$mod->VERSION($ver);";
 716       }
 717
 718       eval $req_line;
 719
 720       $errors{$mod} = $@ if $@;
 721     }
 722
 723     my $res;
 724
 725     if (keys %errors) {
 726       my $missing = join (', ', map { $deps->{$_} ? "$_ >= $deps->{$_}" : $_ } (sort keys %errors) );
 727       $missing .= " (see $class for details)" if $reqs->{$group}{pod};
 728       $res = {
 729         status => 0,
 730         errorlist => \%errors,
 731         missing => $missing,
 732       };
 733     }
 734     else {
 735       $res = {
 736         status => 1,
 737         errorlist => {},
 738         missing => '',
 739       };
 740     }
 741
 742     $res;
 743   };
 744 }
 745
 746 # This is to be called by the author only (automatically in Makefile.PL)
 747 sub _gen_pod {
 748   my ($class, $distver, $pod_dir) = @_;
 749
 750   die "No POD root dir supplied" unless $pod_dir;
 751
 752   $distver ||=
 753     eval { require DBIx::Class; DBIx::Class->VERSION; }
 754       ||
 755     die
 756 "\n\n---------------------------------------------------------------------\n" .
 757 'Unable to load core DBIx::Class module to determine current version, '.
 758 'possibly due to missing dependencies. Author-mode autodocumentation ' .
 759 "halted\n\n" . $@ .
 760 "\n\n---------------------------------------------------------------------\n"
 761   ;
 762
 763   # do not ask for a recent version, use 1.x API calls
 764   # this *may* execute on a smoker with old perl or whatnot
 765   require File::Path;
 766
 767   (my $modfn = __PACKAGE__ . '.pm') =~ s|::|/|g;
 768
 769   (my $podfn = "$pod_dir/$modfn") =~ s/\.pm$/\.pod/;
 770   (my $dir = $podfn) =~ s|/[^/]+$||;
 771
 772   File::Path::mkpath([$dir]);
 773
 774   my $sqltver = $class->req_list_for ('deploy')->{'SQL::Translator'}
 775     or die "Hrmm? No sqlt dep?";
 776
 777
 778   my @chunks;
 779
 780 #@@
 781 #@@ HEADER
 782 #@@
 783   push @chunks, (
 784     <<"EOC",
 785 #########################################################################
 786 #####################  A U T O G E N E R A T E D ########################
 787 #########################################################################
 788 #
 789 # The contents of this POD file are auto-generated.  Any changes you make
 790 # will be lost. If you need to change the generated text edit _gen_pod()
 791 # at the end of $modfn
 792 #
 793 EOC
 794     '=head1 NAME',
 795     "$class - Optional module dependency specifications (for module authors)",
 796   );
 797
 798
 799 #@@
 800 #@@ SYNOPSIS HEADING
 801 #@@
 802   push @chunks, (
 803     '=head1 SYNOPSIS',
 804     <<"EOS",
 805 Somewhere in your build-file (e.g. L<Module::Install>'s Makefile.PL):
 806
 807   ...
 808
 809   configure_requires 'DBIx::Class' => '$distver';
 810
 811   require $class;
 812
 813   my \$deploy_deps = $class->req_list_for('deploy');
 814
 815   for (keys %\$deploy_deps) {
 816     requires \$_ => \$deploy_deps->{\$_};
 817   }
 818
 819   ...
 820
 821 Note that there are some caveats regarding C<configure_requires()>, more info
 822 can be found at L<Module::Install/configure_requires>
 823 EOS
 824   );
 825
 826
 827 #@@
 828 #@@ DESCRIPTION HEADING
 829 #@@
 830   push @chunks, (
 831     '=head1 DESCRIPTION',
 832     <<'EOD',
 833 Some of the less-frequently used features of L<DBIx::Class> have external
 834 module dependencies on their own. In order not to burden the average user
 835 with modules he will never use, these optional dependencies are not included
 836 in the base Makefile.PL. Instead an exception with a descriptive message is
 837 thrown when a specific feature is missing one or several modules required for
 838 its operation. This module is the central holding place for  the current list
 839 of such dependencies, for DBIx::Class core authors, and DBIx::Class extension
 840 authors alike.
 841 EOD
 842   );
 843
 844
 845 #@@
 846 #@@ REQUIREMENT GROUPLIST HEADING
 847 #@@
 848   push @chunks, (
 849     '=head1 CURRENT REQUIREMENT GROUPS',
 850     <<'EOD',
 851 Dependencies are organized in C<groups> and each group can list one or more
 852 required modules, with an optional minimum version (or 0 for any version).
 853 The group name can be used in the
 854 EOD
 855   );
 856
 857   for my $group (sort keys %$reqs) {
 858     my $p = $reqs->{$group}{pod}
 859       or next;
 860
 861     my $modlist = $reqs->{$group}{req}
 862       or next;
 863
 864     next unless keys %$modlist;
 865
 866     push @chunks, (
 867       "=head2 $p->{title}",
 868       "$p->{desc}",
 869       '=over',
 870       ( map { "=item * $_" . ($modlist->{$_} ? " >= $modlist->{$_}" : '') } (sort keys %$modlist) ),
 871       '=back',
 872       "Requirement group: B<$group>",
 873     );
 874   }
 875
 876
 877 #@@
 878 #@@ API DOCUMENTATION HEADING
 879 #@@
 880   push @chunks, (
 881     '=head1 METHODS',
 882     '=head2 req_group_list',
 883     '=over',
 884     '=item Arguments: none',
 885     '=item Return Value: \%list_of_requirement_groups',
 886     '=back',
 887     <<'EOD',
 888 This method should be used by DBIx::Class packagers, to get a hashref of all
 889 dependencies keyed by dependency group. Each key (group name) can be supplied
 890 to one of the group-specific methods below.
 891 EOD
 892
 893     '=head2 req_list_for',
 894     '=over',
 895     '=item Arguments: $group_name',
 896     '=item Return Value: \%list_of_module_version_pairs',
 897     '=back',
 898     <<'EOD',
 899 This method should be used by DBIx::Class extension authors, to determine the
 900 version of modules a specific feature requires in the B<current> version of
 901 DBIx::Class. See the L</SYNOPSIS> for a real-world
 902 example.
 903 EOD
 904
 905     '=head2 req_ok_for',
 906     '=over',
 907     '=item Arguments: $group_name',
 908     '=item Return Value: 1|0',
 909     '=back',
 910     <<'EOD',
 911 Returns true or false depending on whether all modules required by
 912 C<$group_name> are present on the system and loadable.
 913 EOD
 914
 915     '=head2 req_missing_for',
 916     '=over',
 917     '=item Arguments: $group_name',
 918     '=item Return Value: $error_message_string',
 919     '=back',
 920     <<"EOD",
 921 Returns a single line string suitable for inclusion in larger error messages.
 922 This method would normally be used by DBIx::Class core-module author, to
 923 indicate to the user that he needs to install specific modules before he will
 924 be able to use a specific feature.
 925
 926 For example if some of the requirements for C<deploy> are not available,
 927 the returned string could look like:
 928
 929  SQL::Translator >= $sqltver (see $class for details)
 930
 931 The author is expected to prepend the necessary text to this message before
 932 returning the actual error seen by the user.
 933 EOD
 934
 935     '=head2 die_unless_req_ok_for',
 936     '=over',
 937     '=item Arguments: $group_name',
 938     '=back',
 939     <<'EOD',
 940 Checks if L</req_ok_for> passes for the supplied C<$group_name>, and
 941 in case of failure throws an exception including the information
 942 from L</req_missing_for>.
 943 EOD
 944
 945     '=head2 req_errorlist_for',
 946     '=over',
 947     '=item Arguments: $group_name',
 948     '=item Return Value: \%list_of_loaderrors_per_module',
 949     '=back',
 950     <<'EOD',
 951 Returns a hashref containing the actual errors that occurred while attempting
 952 to load each module in the requirement group.
 953 EOD
 954   );
 955
 956
 957 #@@
 958 #@@ FOOTER
 959 #@@
 960   push @chunks, (
 961     '=head1 FURTHER QUESTIONS?',
 962     'Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.',
 963     '=head1 COPYRIGHT AND LICENSE',
 964     <<'EOL',
 965 This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
 966 by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
 967 redistribute it and/or modify it under the same terms as the
 968 L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.
 969 EOL
 970
 971   );
 972
 973
 974   eval {
 975     open (my $fh, '>', $podfn) or die;
 976     print $fh join ("\n\n", @chunks) or die;
 977     print $fh "\n" or die;
 978     close ($fh) or die;
 979   } or croak( "Unable to write $podfn: " . ( $! || $@ || 'unknown error') );
 980 }
 981
 982 1;