1######################################################################### 2##################### A U T O G E N E R A T E D ######################## 3######################################################################### 4# 5# The contents of this POD file are auto-generated. Any changes you make 6# will be lost. If you need to change the generated text edit _gen_pod() 7# at the end of DBIx/Class/Schema/Loader/Optional/Dependencies.pm 8# 9 10=head1 NAME 11 12DBIx::Class::Schema::Loader::Optional::Dependencies - Optional module dependency specifications (for module authors) 13 14 15=head1 SYNOPSIS 16 17Somewhere in your build-file (e.g. L<ExtUtils::MakeMaker>'s F<Makefile.PL>): 18 19 ... 20 21 $EUMM_ARGS{CONFIGURE_REQUIRES} = { 22 %{ $EUMM_ARGS{CONFIGURE_REQUIRES} || {} }, 23 'DBIx::Class::Schema::Loader' => '0.07049', 24 }; 25 26 ... 27 28 my %DBIC_CONFIG_AND_ORACLE_DEPS = %{ eval { 29 require DBIx::Class::Schema::Loader::Optional::Dependencies; 30 DBIx::Class::Schema::Loader::Optional::Dependencies->req_list_for([qw( dbicdump_config rdbms_oracle )]); 31 } || {} }; 32 33 $EUMM_ARGS{PREREQ_PM} = { 34 %DBIC_CONFIG_AND_ORACLE_DEPS, 35 %{ $EUMM_ARGS{PREREQ_PM} || {} }, 36 }; 37 38 ... 39 40 ExtUtils::MakeMaker::WriteMakefile(%EUMM_ARGS); 41 42B<Note>: The C<eval> protection within the example is due to support for 43requirements during L<the C<configure> build phase|CPAN::Meta::Spec/Phases> 44not being available on a sufficient portion of production installations of 45Perl. Robust support for such dependency requirements is available in the 46L<CPAN> installer only since version C<1.94_56> first made available for 47production with perl version C<5.12>. It is the belief of the current 48maintainer that support for requirements during the C<configure> build phase 49will not be sufficiently ubiquitous until the B<year 2020> at the earliest, 50hence the extra care demonstrated above. It should also be noted that some 513rd party installers (e.g. L<cpanminus|App::cpanminus>) do the right thing 52with configure requirements independent from the versions of perl and CPAN 53available. 54 55 56=head1 DESCRIPTION 57 58Some of the less-frequently used features of L<DBIx::Class::Schema::Loader> have external 59module dependencies on their own. In order not to burden the average user 60with modules they will never use, these optional dependencies are not included 61in the base Makefile.PL. Instead an exception with a descriptive message is 62thrown when a specific feature can't find one or several modules required for 63its operation. This module is the central holding place for the current list 64of such dependencies, for DBIx::Class::Schema::Loader core authors, and DBIx::Class::Schema::Loader extension 65authors alike. 66 67Dependencies are organized in L<groups|/CURRENT REQUIREMENT GROUPS> where each 68group can list one or more required modules, with an optional minimum version 69(or 0 for any version). In addition groups prefixed with C<test_> can specify 70a set of environment variables, some (or all) of which are marked as required 71for the group to be considered by L</req_list_for> 72 73Each group name (or a combination thereof) can be used in the 74L<public methods|/METHODS> as described below. 75 76 77=head1 CURRENT REQUIREMENT GROUPS 78 79=head2 dbicdump config file 80 81=head3 dbicdump_config 82 83Modules required for using a config file with dbicdump 84 85=over 86 87=item * Config::Any 88 89=back 90 91=head2 Sybase ASE support 92 93=head3 rdbms_ase 94 95Modules required to connect to Sybase ASE 96 97=over 98 99=item * DBD::Sybase 100 101=back 102 103=head2 DB2 support 104 105=head3 rdbms_db2 106 107Modules required to connect to DB2 108 109=over 110 111=item * DBD::DB2 112 113=back 114 115=head2 Firebird support 116 117=head3 rdbms_firebird 118 119Modules required to connect to Firebird 120 121=over 122 123=item * DBD::Firebird 124 125=back 126 127=head2 Firebird support via DBD::InterBase 128 129=head3 rdbms_firebird_interbase 130 131Modules required to connect to Firebird via DBD::InterBase 132 133=over 134 135=item * DBD::InterBase 136 137=back 138 139=head2 Firebird support via DBD::ODBC 140 141=head3 rdbms_firebird_odbc 142 143Modules required to connect to Firebird via DBD::ODBC 144 145=over 146 147=item * DBD::ODBC 148 149=back 150 151=head2 Informix support 152 153=head3 rdbms_informix 154 155Modules required to connect to Informix 156 157=over 158 159=item * DBD::Informix 160 161=back 162 163=head2 MS Access support via DBD::ADO (Windows only) 164 165=head3 rdbms_msaccess_ado 166 167Modules required to connect to MS Access via DBD::ADO. This particular DBD is available on Windows only 168 169=over 170 171=item * DBD::ADO 172 173=back 174 175=head2 MS Access support via DBD::ODBC 176 177=head3 rdbms_msaccess_odbc 178 179Modules required to connect to MS Access via DBD::ODBC 180 181=over 182 183=item * DBD::ODBC 184 185=back 186 187=head2 MSSQL support via DBD::ADO (Windows only) 188 189=head3 rdbms_mssql_ado 190 191Modules required to connect to MSSQL via DBD::ADO. This particular DBD is available on Windows only 192 193=over 194 195=item * DBD::ADO 196 197=back 198 199=head2 MSSQL support via DBD::ODBC 200 201=head3 rdbms_mssql_odbc 202 203Modules required to connect to MSSQL via DBD::ODBC 204 205=over 206 207=item * DBD::ODBC 208 209=back 210 211=head2 MSSQL support via DBD::Sybase 212 213=head3 rdbms_mssql_sybase 214 215Modules required to connect to MSSQL via DBD::Sybase 216 217=over 218 219=item * DBD::Sybase 220 221=back 222 223=head2 MySQL support 224 225=head3 rdbms_mysql 226 227Modules required to connect to MySQL 228 229=over 230 231=item * DBD::mysql 232 233=back 234 235=head2 Oracle support 236 237=head3 rdbms_oracle 238 239Modules required to connect to Oracle 240 241=over 242 243=item * DBD::Oracle 244 245=item * Math::Base36 >= 0.07 246 247=item * Math::BigInt >= 1.80 248 249=back 250 251=head2 PostgreSQL support 252 253=head3 rdbms_pg 254 255Modules required to connect to PostgreSQL 256 257=over 258 259=item * DBD::Pg 260 261=back 262 263=head2 SQLAnywhere support 264 265=head3 rdbms_sqlanywhere 266 267Modules required to connect to SQLAnywhere 268 269=over 270 271=item * DBD::SQLAnywhere 272 273=back 274 275=head2 SQLAnywhere support via DBD::ODBC 276 277=head3 rdbms_sqlanywhere_odbc 278 279Modules required to connect to SQLAnywhere via DBD::ODBC 280 281=over 282 283=item * DBD::ODBC 284 285=back 286 287=head2 SQLite support 288 289=head3 rdbms_sqlite 290 291Modules required to connect to SQLite 292 293=over 294 295=item * DBD::SQLite 296 297=back 298 299=head2 dbicdump config file testing 300 301=head3 test_dbicdump_config 302 303Modules required for using testing using a config file with dbicdump 304 305=over 306 307=item * Config::Any 308 309=item * Config::General 310 311=back 312 313=head2 POD testing 314 315=head3 test_pod 316 317Modules required for testing POD in this distribution 318 319=over 320 321=item * Pod::Simple >= 3.22 322 323=item * Test::Pod >= 1.14 324 325=back 326 327=head2 use_moose 328 329=head3 use_moose 330 331Modules required for the use_moose option 332 333=over 334 335=item * Moose >= 1.12 336 337=item * MooseX::MarkAsMethods >= 0.13 338 339=item * MooseX::NonMoose >= 0.25 340 341=item * namespace::autoclean >= 0.09 342 343=back 344 345 346=head1 IMPORT-LIKE ACTIONS 347 348Even though this module is not an L<Exporter>, it recognizes several C<actions> 349supplied to its C<import> method. 350 351=head2 -skip_all_without 352 353=over 354 355=item Arguments: @group_names 356 357=back 358 359A convenience wrapper for use during testing: 360 361 362 use DBIx::Class::Schema::Loader::Optional::Dependencies -skip_all_without => qw(admin test_rdbms_mysql); 363 364Roughly equivalent to the following code: 365 366 367 BEGIN { 368 require DBIx::Class::Schema::Loader::Optional::Dependencies; 369 if ( my $missing = DBIx::Class::Schema::Loader::Optional::Dependencies->req_missing_for(\@group_names_) ) { 370 print "1..0 # SKIP requirements not satisfied: $missing\n"; 371 exit 0; 372 } 373 } 374 375 376 377It also takes into account the C<RELEASE_TESTING> environment variable and 378behaves like L</-die_without> for any requirement groups marked as 379C<release_testing_mandatory>. 380 381=head2 -die_without 382 383=over 384 385=item Arguments: @group_names 386 387=back 388 389A convenience wrapper around L</die_unless_req_ok_for>: 390 391 392 use DBIx::Class::Schema::Loader::Optional::Dependencies -die_without => qw(deploy admin); 393 394 395=head2 -list_missing 396 397=over 398 399=item Arguments: @group_names 400 401=back 402 403A convenience wrapper around L</modreq_missing_for>: 404 405 perl -Ilib -MDBIx::Class::Schema::Loader::Optional::Dependencies=-list_missing,dbicdump_config,rdbms_oracle | cpanm 406 407=head1 METHODS 408 409=head2 req_group_list 410 411=over 412 413=item Arguments: none 414 415=item Return Value: \%list_of_requirement_groups 416 417=back 418 419This method should be used by DBIx::Class::Schema::Loader packagers, to get a hashref of all 420dependencies B<keyed> by dependency group. Each key (group name), or a combination 421thereof (as an arrayref) can be supplied to the methods below. 422The B<values> of the returned hash are currently a set of options B<without a 423well defined structure>. If you have use for any of the contents - contact the 424maintainers, instead of treating this as public (left alone stable) API. 425 426=head2 req_list_for 427 428=over 429 430=item Arguments: $group_name | \@group_names 431 432=item Return Value: \%set_of_module_version_pairs 433 434=back 435 436This method should be used by DBIx::Class::Schema::Loader extension authors, to determine the 437version of modules a specific set of features requires for this version of 438DBIx::Class::Schema::Loader (regardless of their availability on the system). 439See the L</SYNOPSIS> for a real-world example. 440 441When handling C<test_*> groups this method behaves B<differently> from 442L</modreq_list_for> below (and is the only such inconsistency among the 443C<req_*> methods). If a particular group declares as requirements some 444C<environment variables> and these requirements are not satisfied (the envvars 445are unset) - then the C<module requirements> of this group are not included in 446the returned list. 447 448=head2 modreq_list_for 449 450=over 451 452=item Arguments: $group_name | \@group_names 453 454=item Return Value: \%set_of_module_version_pairs 455 456=back 457 458Same as L</req_list_for> but does not take into consideration any 459C<environment variable requirements> - returns just the list of required 460modules. 461 462=head2 req_ok_for 463 464=over 465 466=item Arguments: $group_name | \@group_names 467 468=item Return Value: 1|0 469 470=back 471 472Returns true or false depending on whether all modules/envvars required by 473the group(s) are loadable/set on the system. 474 475=head2 req_missing_for 476 477=over 478 479=item Arguments: $group_name | \@group_names 480 481=item Return Value: $error_message_string 482 483=back 484 485Returns a single-line string suitable for inclusion in larger error messages. 486This method would normally be used by DBIx::Class::Schema::Loader core features, to indicate to 487the user that they need to install specific modules and/or set specific 488environment variables before being able to use a specific feature set. 489 490For example if some of the requirements for C<deploy> are not available, 491the returned string could look like: 492 493 494 "Moose~1.12" (see DBIx::Class::Schema::Loader::Optional::Dependencies documentation for details) 495 496The author is expected to prepend the necessary text to this message before 497returning the actual error seen by the user. See also L</modreq_missing_for> 498 499=head2 modreq_missing_for 500 501=over 502 503=item Arguments: $group_name | \@group_names 504 505=item Return Value: $error_message_string 506 507=back 508 509Same as L</req_missing_for> except that the error string is guaranteed to be 510either empty, or contain a set of module requirement specifications suitable 511for piping to e.g. L<cpanminus|App::cpanminus>. The method explicitly does not 512attempt to validate the state of required environment variables (if any). 513 514For instance if some of the requirements for C<deploy> are not available, 515the returned string could look like: 516 517 518 "Moose~1.12" 519 520 521See also L</-list_missing>. 522 523=head2 skip_without 524 525=over 526 527=item Arguments: $group_name | \@group_names 528 529=back 530 531A convenience wrapper around L<skip|Test::More/SKIP>. It does not take neither 532a reason (it is generated by L</req_missing_for>) nor an amount of skipped tests 533(it is always C<1>, thus mandating unconditional use of 534L<done_testing|Test::More/done_testing>). Most useful in combination with ad hoc 535requirement specifications: 536 537 538 SKIP: { 539 DBIx::Class::Schema::Loader::Optional::Dependencies->skip_without([ deploy YAML>=0.90 ]); 540 541 ... 542 } 543 544 545 546=head2 die_unless_req_ok_for 547 548=over 549 550=item Arguments: $group_name | \@group_names 551 552=back 553 554Checks if L</req_ok_for> passes for the supplied group(s), and 555in case of failure throws an exception including the information 556from L</req_missing_for>. See also L</-die_without>. 557 558=head2 modreq_errorlist_for 559 560=over 561 562=item Arguments: $group_name | \@group_names 563 564=item Return Value: \%set_of_loaderrors_per_module 565 566=back 567 568Returns a hashref containing the actual errors that occurred while attempting 569to load each module in the requirement group(s). 570 571=head2 req_errorlist_for 572 573Deprecated method name, equivalent (via proxy) to L</modreq_errorlist_for>. 574 575 576 577=head1 FURTHER QUESTIONS? 578 579Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>. 580 581=head1 COPYRIGHT AND LICENSE 582 583This module is free software L<copyright|DBIx::Class::Schema::Loader/COPYRIGHT AND LICENSE> 584by the L<DBIx::Class::Schema::Loader (DBICSL) authors|DBIx::Class::Schema::Loader/AUTHORS>. 585You can redistribute it and/or modify it under the same terms as the 586L<DBIx::Class::Schema::Loader library|DBIx::Class::Schema::Loader/COPYRIGHT AND LICENSE>. 587 588