1 package DBIx::Class::Optional::Dependencies;
3 ### This may look crazy, but it in fact tangibly ( by 50(!)% ) shortens
4 # the skip-test time when everything requested is unavailable
5 use if $ENV{RELEASE_TESTING} => 'warnings';
6 use if $ENV{RELEASE_TESTING} => 'strict';
14 # NO EXTERNAL NON-5.8.1 CORE DEPENDENCIES EVER (e.g. C::A::G)
15 # This module is to be loaded by Makefile.PM on a pristine system
17 # POD is generated automatically by calling _gen_pod from the
18 # Makefile.PL in $AUTHOR mode
20 # *DELIBERATELY* not making a group for these - they must disappear
21 # forever as optdeps in the first place
24 'MooseX::Types' => '0.21',
25 'MooseX::Types::LoadableClass' => '0.011',
30 # NOTE: the rationale for 2 JSON::Any versions is that
31 # we need the newer only to work around JSON::XS, which
32 # itself is an optional dep
35 'JSON::Any' => '1.23',
39 _json_xs_compatible_json_any => {
41 'JSON::Any' => '1.31',
45 _rdbms_generic_odbc => {
51 _rdbms_generic_ado => {
60 title => 'Storage::Replicated',
61 desc => 'Modules required for L<DBIx::Class::Storage::DBI::Replicated>',
66 include => 'replicated',
73 include => '_json_any',
76 'MooseX::Types::Path::Class' => '0.05',
77 'MooseX::Types::JSON' => '0.02',
80 title => 'DBIx::Class::Admin',
81 desc => 'Modules required for the DBIx::Class administrative library',
88 'Getopt::Long::Descriptive' => '0.081',
89 'Text::CSV' => '1.16',
93 desc => 'Modules required for the CLI DBIx::Class interface dbicadmin',
99 'SQL::Translator' => '0.11018',
102 title => 'Storage::DBI::deploy()',
103 desc => 'Modules required for L<DBIx::Class::Storage::DBI/deployment_statements> and L<DBIx::Class::Schema/deploy>',
109 'Math::BigInt' => '1.80',
110 'Math::Base36' => '0.07',
114 test_component_accessor => {
116 'Class::Unload' => '0.07',
122 'Test::Pod' => '1.42',
124 release_testing_mandatory => 1,
127 test_podcoverage => {
129 'Test::Pod::Coverage' => '1.08',
130 'Pod::Coverage' => '0.20',
132 release_testing_mandatory => 1,
137 'Test::EOL' => '1.0',
138 'Test::NoTabs' => '0.9',
140 release_testing_mandatory => 1,
145 'Test::Strict' => '0.20',
147 release_testing_mandatory => 1,
150 test_prettydebug => {
151 include => '_json_any',
154 test_admin_script => {
155 include => [qw( admin_script _json_xs_compatible_json_any )],
159 'Cpanel::JSON::XS' => 0,
162 # for t/admin/10script.t
163 ? ('Win32::ShellQuote' => 0)
164 # DWIW does not compile (./configure even) on win32
165 : ('JSON::DWIW' => 0 )
170 test_leaks_heavy => {
172 'Class::MethodCache' => '0.02',
173 'PadWalker' => '1.06',
179 'DateTime' => '0.55',
180 'DateTime::Format::Strptime' => '1.2',
185 include => 'test_dt',
189 'DateTime::Format::SQLite' => '0',
194 include => 'test_dt',
196 # t/inflate/datetime_mysql.t
197 # (doesn't need Mysql itself)
198 'DateTime::Format::MySQL' => '0',
203 include => 'test_dt',
205 # t/inflate/datetime_pg.t
206 # (doesn't need PG itself)
207 'DateTime::Format::Pg' => '0.16004',
212 include => 'test_dt',
214 'Class::DBI::Plugin::DeepAbstractSearch' => '0',
215 'Time::Piece::MySQL' => '0',
216 'Date::Simple' => '3.03',
220 # this is just for completeness as SQLite
221 # is a core dep of DBIC for testing
227 title => 'SQLite support',
228 desc => 'Modules required to connect to SQLite',
234 # when changing this list make sure to adjust xt/optional_deps.t
238 title => 'PostgreSQL support',
239 desc => 'Modules required to connect to PostgreSQL',
243 rdbms_mssql_odbc => {
244 include => '_rdbms_generic_odbc',
246 title => 'MSSQL support via DBD::ODBC',
247 desc => 'Modules required to connect to MSSQL via DBD::ODBC',
251 rdbms_mssql_sybase => {
256 title => 'MSSQL support via DBD::Sybase',
257 desc => 'Modules required to connect to MSSQL via DBD::Sybase',
262 include => '_rdbms_generic_ado',
264 title => 'MSSQL support via DBD::ADO (Windows only)',
265 desc => 'Modules required to connect to MSSQL via DBD::ADO. This particular DBD is available on Windows only',
269 rdbms_msaccess_odbc => {
270 include => '_rdbms_generic_odbc',
272 title => 'MS Access support via DBD::ODBC',
273 desc => 'Modules required to connect to MS Access via DBD::ODBC',
277 rdbms_msaccess_ado => {
278 include => '_rdbms_generic_ado',
280 title => 'MS Access support via DBD::ADO (Windows only)',
281 desc => 'Modules required to connect to MS Access via DBD::ADO. This particular DBD is available on Windows only',
290 title => 'MySQL support',
291 desc => 'Modules required to connect to MySQL',
296 include => 'id_shortener',
301 title => 'Oracle support',
302 desc => 'Modules required to connect to Oracle',
311 title => 'Sybase ASE support',
312 desc => 'Modules required to connect to Sybase ASE',
321 title => 'DB2 support',
322 desc => 'Modules required to connect to DB2',
327 include => '_rdbms_generic_odbc',
329 title => 'DB2 on AS/400 support',
330 desc => 'Modules required to connect to DB2 on AS/400',
336 'DBD::Informix' => 0,
339 title => 'Informix support',
340 desc => 'Modules required to connect to Informix',
344 rdbms_sqlanywhere => {
346 'DBD::SQLAnywhere' => 0,
349 title => 'SQLAnywhere support',
350 desc => 'Modules required to connect to SQLAnywhere',
354 rdbms_sqlanywhere_odbc => {
355 include => '_rdbms_generic_odbc',
357 title => 'SQLAnywhere support via DBD::ODBC',
358 desc => 'Modules required to connect to SQLAnywhere via DBD::ODBC',
364 'DBD::Firebird' => 0,
367 title => 'Firebird support',
368 desc => 'Modules required to connect to Firebird',
372 rdbms_firebird_interbase => {
374 'DBD::InterBase' => 0,
377 title => 'Firebird support via DBD::InterBase',
378 desc => 'Modules required to connect to Firebird via DBD::InterBase',
382 rdbms_firebird_odbc => {
383 include => '_rdbms_generic_odbc',
385 title => 'Firebird support via DBD::ODBC',
386 desc => 'Modules required to connect to Firebird via DBD::ODBC',
390 test_rdbms_sqlite => {
391 include => 'rdbms_sqlite',
394 ### IMPORTANT - do not raise this dependency
395 ### even though many bugfixes are present in newer versions, the general DBIC
396 ### rule is to bend over backwards for available DBDs (given upgrading them is
397 ### often *not* easy or even possible)
399 'DBD::SQLite' => '1.29',
404 include => 'rdbms_pg',
406 DBICTEST_PG_DSN => 1,
407 DBICTEST_PG_USER => 0,
408 DBICTEST_PG_PASS => 0,
411 # the order does matter because the rdbms support group might require
412 # a different version that the test group
414 # when changing this list make sure to adjust xt/optional_deps.t
415 'DBD::Pg' => '2.009002', # specific version to test bytea
419 test_rdbms_mssql_odbc => {
420 include => 'rdbms_mssql_odbc',
422 DBICTEST_MSSQL_ODBC_DSN => 1,
423 DBICTEST_MSSQL_ODBC_USER => 0,
424 DBICTEST_MSSQL_ODBC_PASS => 0,
428 test_rdbms_mssql_ado => {
429 include => 'rdbms_mssql_ado',
431 DBICTEST_MSSQL_ADO_DSN => 1,
432 DBICTEST_MSSQL_ADO_USER => 0,
433 DBICTEST_MSSQL_ADO_PASS => 0,
437 test_rdbms_mssql_sybase => {
438 include => 'rdbms_mssql_sybase',
440 DBICTEST_MSSQL_DSN => 1,
441 DBICTEST_MSSQL_USER => 0,
442 DBICTEST_MSSQL_PASS => 0,
446 test_rdbms_msaccess_odbc => {
447 include => 'rdbms_msaccess_odbc',
449 DBICTEST_MSACCESS_ODBC_DSN => 1,
450 DBICTEST_MSACCESS_ODBC_USER => 0,
451 DBICTEST_MSACCESS_ODBC_PASS => 0,
458 test_rdbms_msaccess_ado => {
459 include => 'rdbms_msaccess_ado',
461 DBICTEST_MSACCESS_ADO_DSN => 1,
462 DBICTEST_MSACCESS_ADO_USER => 0,
463 DBICTEST_MSACCESS_ADO_PASS => 0,
470 test_rdbms_mysql => {
471 include => 'rdbms_mysql',
473 DBICTEST_MYSQL_DSN => 1,
474 DBICTEST_MYSQL_USER => 0,
475 DBICTEST_MYSQL_PASS => 0,
479 test_rdbms_oracle => {
480 include => 'rdbms_oracle',
482 DBICTEST_ORA_DSN => 1,
483 DBICTEST_ORA_USER => 0,
484 DBICTEST_ORA_PASS => 0,
487 'DateTime::Format::Oracle' => '0',
488 'DBD::Oracle' => '1.24',
493 include => 'rdbms_ase',
495 DBICTEST_SYBASE_DSN => 1,
496 DBICTEST_SYBASE_USER => 0,
497 DBICTEST_SYBASE_PASS => 0,
502 include => 'rdbms_db2',
504 DBICTEST_DB2_DSN => 1,
505 DBICTEST_DB2_USER => 0,
506 DBICTEST_DB2_PASS => 0,
510 test_rdbms_db2_400 => {
511 include => 'rdbms_db2_400',
513 DBICTEST_DB2_400_DSN => 1,
514 DBICTEST_DB2_400_USER => 0,
515 DBICTEST_DB2_400_PASS => 0,
519 test_rdbms_informix => {
520 include => 'rdbms_informix',
522 DBICTEST_INFORMIX_DSN => 1,
523 DBICTEST_INFORMIX_USER => 0,
524 DBICTEST_INFORMIX_PASS => 0,
528 test_rdbms_sqlanywhere => {
529 include => 'rdbms_sqlanywhere',
531 DBICTEST_SQLANYWHERE_DSN => 1,
532 DBICTEST_SQLANYWHERE_USER => 0,
533 DBICTEST_SQLANYWHERE_PASS => 0,
537 test_rdbms_sqlanywhere_odbc => {
538 include => 'rdbms_sqlanywhere_odbc',
540 DBICTEST_SQLANYWHERE_ODBC_DSN => 1,
541 DBICTEST_SQLANYWHERE_ODBC_USER => 0,
542 DBICTEST_SQLANYWHERE_ODBC_PASS => 0,
546 test_rdbms_firebird => {
547 include => 'rdbms_firebird',
549 DBICTEST_FIREBIRD_DSN => 1,
550 DBICTEST_FIREBIRD_USER => 0,
551 DBICTEST_FIREBIRD_PASS => 0,
555 test_rdbms_firebird_interbase => {
556 include => 'rdbms_firebird_interbase',
558 DBICTEST_FIREBIRD_INTERBASE_DSN => 1,
559 DBICTEST_FIREBIRD_INTERBASE_USER => 0,
560 DBICTEST_FIREBIRD_INTERBASE_PASS => 0,
564 test_rdbms_firebird_odbc => {
565 include => 'rdbms_firebird_odbc',
567 DBICTEST_FIREBIRD_ODBC_DSN => 1,
568 DBICTEST_FIREBIRD_ODBC_USER => 0,
569 DBICTEST_FIREBIRD_ODBC_PASS => 0,
575 DBICTEST_MEMCACHED => 1,
578 'Cache::Memcached' => 0,
583 # we need to run the dbicadmin so we can self-generate its POD
584 # also we do not want surprises in case JSON::XS is in the path
585 # so make sure we get an always-working JSON::Any
586 include => [qw( admin_script _json_xs_compatible_json_any )],
588 'ExtUtils::MakeMaker' => '6.64',
589 'Pod::Inherit' => '0.91',
595 'CPAN::Uploader' => '0.103001',
611 if ($action eq '-die_without') {
615 eval { $class->die_unless_req_ok_for(\@_); 1 }
618 die "\n$err\n" if $err;
620 elsif ($action eq '-list_missing') {
621 print $class->modreq_missing_for(\@_);
625 elsif ($action eq '-skip_all_without') {
627 # sanity check - make sure ->current_test is 0 and no plan has been declared
631 Test::Builder->new->current_test
633 Test::Builder->new->has_plan
635 } and croak("Unable to invoke -skip_all_without after testing has started");
637 if ( my $missing = $class->req_missing_for(\@_) ) {
639 die ("\nMandatory requirements not satisfied during release-testing: $missing\n\n")
640 if $ENV{RELEASE_TESTING} and $class->_groups_to_reqs(\@_)->{release_testing_mandatory};
642 print "1..0 # SKIP requirements not satisfied: $missing\n";
646 elsif ($action =~ /^-/) {
647 croak "Unknown import-time action '$action'";
650 croak "$class is not an exporter, unable to import '$action'";
658 croak( __PACKAGE__ . " does not implement unimport" );
661 # OO for (mistakenly considered) ease of extensibility, not due to any need to
662 # carry state of any sort. This API is currently used outside, so leave as-is.
663 # FIXME - make sure to not propagate this further if module is extracted as a
664 # standalone library - keep the stupidity to a DBIC-secific shim!
667 shift->_groups_to_reqs(shift)->{effective_modreqs};
670 sub modreq_list_for {
671 shift->_groups_to_reqs(shift)->{modreqs};
676 { $_ => $_[0]->_groups_to_reqs($_) }
677 grep { $_ !~ /^_/ } keys %$dbic_reqs
681 sub req_errorlist_for { shift->modreq_errorlist_for(shift) } # deprecated
682 sub modreq_errorlist_for {
683 my ($self, $groups) = @_;
684 $self->_errorlist_for_modreqs( $self->_groups_to_reqs($groups)->{modreqs} );
688 shift->req_missing_for(shift) ? 0 : 1;
691 sub req_missing_for {
692 my ($self, $groups) = @_;
694 my $reqs = $self->_groups_to_reqs($groups);
695 my $mods_missing = $self->modreq_missing_for($groups);
700 ! $reqs->{missing_envvars}
703 my @res = $mods_missing || ();
705 push @res, 'the following group(s) of environment variables: ' . join ' and ', sort map
706 { __envvar_group_desc($_) }
707 @{$reqs->{missing_envvars}}
708 if $reqs->{missing_envvars};
711 ( join ' as well as ', @res )
713 ( $reqs->{modreqs_fully_documented} ? " (see @{[ ref $self || $self ]} documentation for details)" : '' ),
717 sub modreq_missing_for {
718 my ($self, $groups) = @_;
720 my $reqs = $self->_groups_to_reqs($groups);
721 my $modreq_errors = $self->_errorlist_for_modreqs($reqs->{modreqs})
725 { $reqs->{modreqs}{$_} ? qq("$_~>=$reqs->{modreqs}{$_}") : $_ }
726 sort { lc($a) cmp lc($b) } keys %$modreq_errors
730 sub die_unless_req_ok_for {
731 if (my $err = shift->req_missing_for(shift) ) {
732 die "Unable to continue due to missing requirements: $err\n";
738 ### Private functions
740 # potentially shorten group desc
741 sub __envvar_group_desc {
744 my (@res, $last_prefix);
745 while (my $ev = shift @envs) {
746 my ($pref, $sep, $suff) = split / ([\_\-]) (?= [^\_\-]+ \z )/x, $ev;
748 if ( defined $sep and ($last_prefix||'') eq $pref ) {
749 push @res, "...${sep}${suff}"
755 $last_prefix = $pref if $sep;
762 our %req_unavailability_cache;
764 # this method is just a lister and envvar/metadata checker - it does not try to load anything
765 my $processed_groups = {};
766 sub _groups_to_reqs {
767 my ($self, $groups) = @_;
769 $groups = [ $groups || () ]
770 unless ref $groups eq 'ARRAY';
772 croak "@{[ (caller(1))[3] ]}() expects a requirement group name or arrayref of group names"
777 modreqs_fully_documented => 1,
780 for my $group ( grep { ! $processed_groups->{$_} } @$groups ) {
782 $group =~ /\A [A-Z_a-z][0-9A-Z_a-z]* \z/x
783 or croak "Invalid requirement group name '$group': only ascii alphanumerics and _ are allowed";
785 croak "Requirement group '$group' is not defined" unless defined $dbic_reqs->{$group};
787 my $group_reqs = $dbic_reqs->{$group}{req};
790 for (keys %$group_reqs) {
792 $_ =~ /\A [A-Z_a-z][0-9A-Z_a-z]* (?:::[0-9A-Z_a-z]+)* \z /x
793 or croak "Requirement '$_' in group '$group' is not a valid module name";
795 # !!!DO NOT CHANGE!!!
796 # remember - version.pm may not be available on the system
797 croak "Requirement '$_' in group '$group' specifies an invalid version '$group_reqs->{$_}' (only plain non-underscored floating point decimals are supported)"
798 if ( ($group_reqs->{$_}||0) !~ / \A [0-9]+ (?: \. [0-9]+ )? \z /x );
801 # check if we have all required envvars if such names are defined
802 my ($some_envs_required, $some_envs_missing);
803 if (my @e = @{$dbic_reqs->{$group}{env} || [] }) {
805 croak "Unexpected 'env' attribute under group '$group' (only allowed in test_* groups)"
806 unless $group =~ /^test_/;
808 croak "Unexpected *odd* list in 'env' under group '$group'"
811 my @group_envnames_list;
813 # deconstruct the whole thing
815 push @group_envnames_list, my $envname = shift @e;
817 # env required or not
818 next unless shift @e;
820 $some_envs_required ||= 1;
822 $some_envs_missing ||= (
823 ! defined $ENV{$envname}
825 ! length $ENV{$envname}
829 croak "None of the envvars in group '$group' declared as required, making the requirement moot"
830 unless $some_envs_required;
832 push @{$ret->{missing_envvars}}, \@group_envnames_list if $some_envs_missing;
835 # get the reqs for includes if any
837 if (my $incs = $dbic_reqs->{$group}{include}) {
838 $incs = [ $incs ] unless ref $incs eq 'ARRAY';
840 croak "Malformed 'include' for group '$group': must be another existing group name or arrayref of existing group names"
843 local $processed_groups->{$group} = 1;
845 my $subreqs = $self->_groups_to_reqs($incs);
847 croak "Includes with variable effective_modreqs not yet supported"
848 if $subreqs->{effective_modreqs_differ};
850 $inc_reqs = $subreqs->{modreqs};
854 # assemble into the final ret
857 $some_envs_missing ? () : 'effective_modreqs'
859 for my $req_bag ($group_reqs, $inc_reqs||()) {
860 for my $mod (keys %$req_bag) {
862 $ret->{$type}{$mod} = $req_bag->{$mod}||0 if (
864 ! exists $ret->{$type}{$mod}
866 # we sanitized the version to be numeric above - we can just -gt it
867 ($req_bag->{$mod}||0) > $ret->{$type}{$mod}
874 $ret->{effective_modreqs_differ} ||= !!$some_envs_missing;
876 $ret->{modreqs_fully_documented} &&= !!$dbic_reqs->{$group}{pod};
878 $ret->{release_testing_mandatory} ||= !!$dbic_reqs->{$group}{release_testing_mandatory};
885 # this method tries to load specified modreqs and returns a hashref of
886 # module/loaderror pairs for anything that failed
887 sub _errorlist_for_modreqs {
888 # args supposedly already went through _groups_to_reqs and are therefore sanitized
889 # safe to eval at will
890 my ($self, $reqs) = @_;
894 for my $m ( keys %$reqs ) {
897 if (! exists $req_unavailability_cache{$m}{$v} ) {
899 eval( "require $m;" . ( $v ? "$m->VERSION(q($v))" : '' ) );
900 $req_unavailability_cache{$m}{$v} = $@;
903 $ret->{$m} = $req_unavailability_cache{$m}{$v}
904 if $req_unavailability_cache{$m}{$v};
911 # This is to be called by the author only (automatically in Makefile.PL)
913 my ($class, $distver, $pod_dir) = @_;
915 die "No POD root dir supplied" unless $pod_dir;
918 eval { require DBIx::Class; DBIx::Class->VERSION; }
921 "\n\n---------------------------------------------------------------------\n" .
922 'Unable to load core DBIx::Class module to determine current version, '.
923 'possibly due to missing dependencies. Author-mode autodocumentation ' .
925 "\n\n---------------------------------------------------------------------\n"
928 # do not ask for a recent version, use 1.x API calls
929 # this *may* execute on a smoker with old perl or whatnot
932 (my $modfn = __PACKAGE__ . '.pm') =~ s|::|/|g;
934 (my $podfn = "$pod_dir/$modfn") =~ s/\.pm$/\.pod/;
935 (my $dir = $podfn) =~ s|/[^/]+$||;
937 File::Path::mkpath([$dir]);
939 my $sqltver = $class->req_list_for('deploy')->{'SQL::Translator'}
940 or die "Hrmm? No sqlt dep?";
948 push @chunks, <<"EOC";
949 #########################################################################
950 ##################### A U T O G E N E R A T E D ########################
951 #########################################################################
953 # The contents of this POD file are auto-generated. Any changes you make
954 # will be lost. If you need to change the generated text edit _gen_pod()
955 # at the end of $modfn
960 $class - Optional module dependency specifications (for module authors)
967 push @chunks, <<"EOC";
970 Somewhere in your build-file (e.g. L<ExtUtils::MakeMaker>'s F<Makefile.PL>):
974 \$EUMM_ARGS{CONFIGURE_REQUIRES} = {
975 \%{ \$EUMM_ARGS{CONFIGURE_REQUIRES} || {} },
976 'DBIx::Class' => '$distver',
981 my %DBIC_DEPLOY_DEPS = %{ eval {
983 $class->req_list_for('deploy');
986 \$EUMM_ARGS{PREREQ_PM} = {
988 \%{ \$EUMM_ARGS{PREREQ_PM} || {} },
993 ExtUtils::MakeMaker::WriteMakefile(\%EUMM_ARGS);
995 B<Note>: The C<eval> protection within the example is due to support for
996 requirements during L<the C<configure> build phase|CPAN::Meta::Spec/Phases>
997 not being available on a sufficient portion of production installations of
998 Perl. Robust support for such dependency requirements is available in the
999 L<CPAN> installer only since version C<1.94_56> first made available for
1000 production with perl version C<5.12>. It is the belief of the current
1001 maintainer that support for requirements during the C<configure> build phase
1002 will not be sufficiently ubiquitous until the B<year 2020> at the earliest,
1003 hence the extra care demonstrated above. It should also be noted that some
1004 3rd party installers (e.g. L<cpanminus|App::cpanminus>) do the right thing
1005 with configure requirements independent from the versions of perl and CPAN
1011 #@@ DESCRIPTION HEADING
1013 push @chunks, <<'EOC';
1016 Some of the less-frequently used features of L<DBIx::Class> have external
1017 module dependencies on their own. In order not to burden the average user
1018 with modules they will never use, these optional dependencies are not included
1019 in the base Makefile.PL. Instead an exception with a descriptive message is
1020 thrown when a specific feature can't find one or several modules required for
1021 its operation. This module is the central holding place for the current list
1022 of such dependencies, for DBIx::Class core authors, and DBIx::Class extension
1025 Dependencies are organized in L<groups|/CURRENT REQUIREMENT GROUPS> where each
1026 group can list one or more required modules, with an optional minimum version
1027 (or 0 for any version). In addition groups prefixed with C<test_> can specify
1028 a set of environment variables, some (or all) of which are marked as required
1029 for the group to be considered by L</req_list_for>
1031 Each group name (or a combination thereof) can be used in the
1032 L<public methods|/METHODS> as described below.
1037 #@@ REQUIREMENT GROUPLIST HEADING
1039 push @chunks, '=head1 CURRENT REQUIREMENT GROUPS';
1041 for my $group (sort keys %$dbic_reqs) {
1042 my $p = $dbic_reqs->{$group}{pod}
1045 my $modlist = $class->modreq_list_for($group);
1047 next unless keys %$modlist;
1050 "=head2 $p->{title}",
1053 ( map { "=item * $_" . ($modlist->{$_} ? " >= $modlist->{$_}" : '') } (sort keys %$modlist) ),
1055 "Requirement group: B<$group>",
1061 #@@ API DOCUMENTATION HEADING
1063 push @chunks, <<'EOC';
1065 =head1 IMPORT-LIKE ACTIONS
1067 Even though this module is not an L<Exporter>, it recognizes several C<actions>
1068 supplied to its C<import> method.
1070 =head2 -skip_all_without
1074 =item Arguments: @group_names
1078 A convenience wrapper for use during testing:
1081 push @chunks, " use $class -skip_all_without => qw(admin test_rdbms_mysql);";
1083 push @chunks, 'Roughly equivalent to the following code:';
1085 push @chunks, sprintf <<'EOS', ($class) x 2;
1089 if ( my $missing = %s->req_missing_for(\@group_names_) ) {
1090 print "1..0 # SKIP requirements not satisfied: $missing\n";
1096 push @chunks, <<'EOC';
1098 It also takes into account the C<RELEASE_TESTING> environment variable and
1099 behaves like L</-die_without> for any requirement groups marked as
1100 C<release_testing_mandatory>.
1106 =item Arguments: @group_names
1110 A convenience wrapper around L</die_unless_req_ok_for>:
1113 push @chunks, " use $class -die_without => qw(deploy admin);";
1115 push @chunks, <<'EOC';
1117 =head2 -list_missing
1121 =item Arguments: @group_names
1125 A convenience wrapper around L</modreq_missing_for>:
1127 perl -Ilib -MDBIx::Class::Optional::Dependencies=-list_missing,deploy,admin | cpanm
1131 =head2 req_group_list
1135 =item Arguments: none
1137 =item Return Value: \%list_of_requirement_groups
1141 This method should be used by DBIx::Class packagers, to get a hashref of all
1142 dependencies B<keyed> by dependency group. Each key (group name), or a combination
1143 thereof (as an arrayref) can be supplied to the methods below.
1144 The B<values> of the returned hash are currently a set of options B<without a
1145 well defined structure>. If you have use for any of the contents - contact the
1146 maintainers, instead of treating this as public (left alone stable) API.
1152 =item Arguments: $group_name | \@group_names
1154 =item Return Value: \%set_of_module_version_pairs
1158 This method should be used by DBIx::Class extension authors, to determine the
1159 version of modules a specific set of features requires for this version of
1160 DBIx::Class (regardless of their availability on the system).
1161 See the L</SYNOPSIS> for a real-world example.
1163 When handling C<test_*> groups this method behaves B<differently> from
1164 L</modreq_list_for> below (and is the only such inconsistency among the
1165 C<req_*> methods). If a particular group declares as requirements some
1166 C<environment variables> and these requirements are not satisfied (the envvars
1167 are unset) - then the C<module requirements> of this group are not included in
1170 =head2 modreq_list_for
1174 =item Arguments: $group_name | \@group_names
1176 =item Return Value: \%set_of_module_version_pairs
1180 Same as L</req_list_for> but does not take into consideration any
1181 C<environment variable requirements> - returns just the list of required
1188 =item Arguments: $group_name | \@group_names
1190 =item Return Value: 1|0
1194 Returns true or false depending on whether all modules/envvars required by
1195 the group(s) are loadable/set on the system.
1197 =head2 req_missing_for
1201 =item Arguments: $group_name | \@group_names
1203 =item Return Value: $error_message_string
1207 Returns a single-line string suitable for inclusion in larger error messages.
1208 This method would normally be used by DBIx::Class core features, to indicate to
1209 the user that they need to install specific modules and/or set specific
1210 environment variables before being able to use a specific feature set.
1212 For example if some of the requirements for C<deploy> are not available,
1213 the returned string could look like:
1216 push @chunks, qq{ "SQL::Translator~>=$sqltver" (see $class documentation for details)};
1218 push @chunks, <<'EOC';
1219 The author is expected to prepend the necessary text to this message before
1220 returning the actual error seen by the user. See also L</modreq_missing_for>
1222 =head2 modreq_missing_for
1226 =item Arguments: $group_name | \@group_names
1228 =item Return Value: $error_message_string
1232 Same as L</req_missing_for> except that the error string is guaranteed to be
1233 either empty, or contain a set of module requirement specifications suitable
1234 for piping to e.g. L<cpanminus|App::cpanminus>. The method explicitly does not
1235 attempt to validate the state of required environment variables (if any).
1237 For instance if some of the requirements for C<deploy> are not available,
1238 the returned string could look like:
1241 push @chunks, qq{ "SQL::Translator~>=$sqltver"};
1243 push @chunks, <<'EOC';
1245 See also L</-list_missing>.
1247 =head2 die_unless_req_ok_for
1251 =item Arguments: $group_name | \@group_names
1255 Checks if L</req_ok_for> passes for the supplied group(s), and
1256 in case of failure throws an exception including the information
1257 from L</req_missing_for>. See also L</-die_without>.
1259 =head2 modreq_errorlist_for
1263 =item Arguments: $group_name | \@group_names
1265 =item Return Value: \%set_of_loaderrors_per_module
1269 Returns a hashref containing the actual errors that occurred while attempting
1270 to load each module in the requirement group(s).
1272 =head2 req_errorlist_for
1274 Deprecated method name, equivalent (via proxy) to L</modreq_errorlist_for>.
1281 push @chunks, <<'EOC';
1282 =head1 FURTHER QUESTIONS?
1284 Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
1286 =head1 COPYRIGHT AND LICENSE
1288 This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
1289 by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
1290 redistribute it and/or modify it under the same terms as the
1291 L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.
1295 open (my $fh, '>', $podfn) or die;
1296 print $fh join ("\n\n", @chunks) or die;
1297 print $fh "\n" or die;
1299 } or croak( "Unable to write $podfn: " . ( $! || $@ || 'unknown error') );