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