NAME

$class - Optional module dependency specifications (for module authors) EOC

#@@ #@@ SYNOPSIS HEADING #@@
push @chunks, <<"EOC"; =head1 SYNOPSIS

Somewhere in your build-file (e.g. ExtUtils::MakeMaker's Makefile.PL):

  ...
  \$EUMM_ARGS{CONFIGURE_REQUIRES} = {
    \%{ \$EUMM_ARGS{CONFIGURE_REQUIRES} || {} },
    'DBIx::Class::Schema::Loader' => '$distver',
  };
  ...
  my %DBIC_CONFIG_AND_ORACLE_DEPS = %{ eval {
    require $class;
    $class->req_list_for([qw( dbicdump_config rdbms_oracle )]);
  } || {} };
  \$EUMM_ARGS{PREREQ_PM} = {
    \%DBIC_CONFIG_AND_ORACLE_DEPS,
    \%{ \$EUMM_ARGS{PREREQ_PM} || {} },
  };
  ...
  ExtUtils::MakeMaker::WriteMakefile(\%EUMM_ARGS);

Note: The "eval" protection within the example is due to support for requirements during the "configure" build phase not being available on a sufficient portion of production installations of Perl. Robust support for such dependency requirements is available in the CPAN installer only since version "1.94_56" first made available for production with perl version 5.12. It is the belief of the current maintainer that support for requirements during the "configure" build phase will not be sufficiently ubiquitous until the year 2020 at the earliest, hence the extra care demonstrated above. It should also be noted that some 3rd party installers (e.g. cpanminus) do the right thing with configure requirements independent from the versions of perl and CPAN available. EOC

#@@ #@@ DESCRIPTION HEADING #@@
push @chunks, <<'EOC'; =head1 DESCRIPTION

Some of the less-frequently used features of DBIx::Class::Schema::Loader have external module dependencies on their own. In order not to burden the average user with modules they will never use, these optional dependencies are not included in the base Makefile.PL. Instead an exception with a descriptive message is thrown when a specific feature can't find one or several modules required for its operation. This module is the central holding place for the current list of such dependencies, for DBIx::Class::Schema::Loader core authors, and DBIx::Class::Schema::Loader extension authors alike.

Dependencies are organized in groups where each group can list one or more required modules, with an optional minimum version (or 0 for any version). In addition groups prefixed with "test_" can specify a set of environment variables, some (or all) of which are marked as required for the group to be considered by "req_list_for"

Each group name (or a combination thereof) can be used in the public methods as described below. EOC

#@@ #@@ REQUIREMENT GROUPLIST HEADING #@@
push @chunks, '=head1 CURRENT REQUIREMENT GROUPS';

  my $standalone_info;
  for my $group (sort keys %$dbic_reqs) {
    my $info = $standalone_info->{$group} ||= $class->_groups_to_reqs($group);
    next unless (
      $info->{modreqs_fully_documented}
        and
      ( $info->{augments} or $info->{modreqs} )
    );
    my $p = $dbic_reqs->{$group}{pod};
    push @chunks, (
      "=head2 $p->{title}",
      "=head3 $group",
      $p->{desc},
      '=over',
    );
    if ( keys %{ $info->{modreqs}||{} } ) {
      push @chunks, map
        { "=item * $_" . ($info->{modreqs}{$_} ? " >= $info->{modreqs}{$_}" : '') }
        ( sort keys %{ $info->{modreqs} } )
      ;
    }
    else {
      push @chunks, '=item * No standalone requirements',
    }
    push @chunks, '=back';
    for my $ag ( sort keys %{ $info->{augments} || {} } ) {
      my $ag_info = $standalone_info->{$ag} ||= $class->_groups_to_reqs($ag);
      my $newreqs = $class->modreq_list_for([ $group, $ag ]);
      for (keys %$newreqs) {
        delete $newreqs->{$_} if (
          ( defined $info->{modreqs}{$_}    and $info->{modreqs}{$_}    == $newreqs->{$_} )
            or
          ( defined $ag_info->{modreqs}{$_} and $ag_info->{modreqs}{$_} == $newreqs->{$_} )
        );
      }
      if (keys %$newreqs) {
        push @chunks, (
          "Combined with L</$ag> additionally requires:",
          '=over',
          ( map
            { "=item * $_" . ($newreqs->{$_} ? " >= $newreqs->{$_}" : '') }
            ( sort keys %$newreqs )
          ),
          '=back',
        );
      }
    }
  }

#@@ #@@ API DOCUMENTATION HEADING #@@
push @chunks, <<'EOC';

IMPORT-LIKE ACTIONS

Even though this module is not an Exporter, it recognizes several "actions" supplied to its "import" method.

  push @chunks, " use $class -skip_all_without => qw(admin test_rdbms_mysql);";
  push @chunks, 'Roughly equivalent to the following code:';
  push @chunks, sprintf <<'EOS', ($class) x 2;
 BEGIN {
   require %s;
   if ( my $missing = %s->req_missing_for(\@group_names_) ) {
     print "1..0 # SKIP requirements not satisfied: $missing\n";
     exit 0;
   }
 }
EOS
  push @chunks, <<'EOC';

  push @chunks, " use $class -die_without => qw(deploy admin);";
  push @chunks, <<'EOC';

 perl -Ilib -MDBIx::Class::Schema::Loader::Optional::Dependencies=-list_missing,dbicdump_config,rdbms_oracle | cpanm

METHODS

  push @chunks, qq{ "Moose~$moosever" (see $class documentation for details)};
  push @chunks, <<'EOC';
The author is expected to prepend the necessary text to this message before
returning the actual error seen by the user. See also L</modreq_missing_for>

  push @chunks, qq{ "Moose~$moosever"};
  push @chunks, <<'EOC';

  push @chunks, <<EOC;
  SKIP: {
    $class->skip_without([ deploy YAML>=0.90 ]);
    ...
  }
EOC
  push @chunks, <<'EOC';

COPYRIGHT AND LICENSE

This module is free software copyright by the DBIx::Class::Schema::Loader (DBICSL) authors. You can redistribute it and/or modify it under the same terms as the DBIx::Class::Schema::Loader library. EOC

  eval {
    open (my $fh, '>', $podfn) or die;
    print $fh join ("\n\n", @chunks) or die;
    print $fh "\n" or die;
    close ($fh) or die;
  } or croak( "Unable to write $podfn: " . ( $! || $@ || 'unknown error') );
}

1;