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