X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FOptional%2FDependencies.pm;h=94b61c4a6371ac0d23a790e90dd940f8fa695338;hb=79b1bf0a9e0d827d5737c389523adb858dff986a;hp=b03ef9c470146903855f507926a5f5d87b6ce9c7;hpb=a036182226af9edc62ef393cebca797030f44a9a;p=dbsrgits%2FDBIx-Class.git diff --git a/lib/DBIx/Class/Optional/Dependencies.pm b/lib/DBIx/Class/Optional/Dependencies.pm index b03ef9c..94b61c4 100644 --- a/lib/DBIx/Class/Optional/Dependencies.pm +++ b/lib/DBIx/Class/Optional/Dependencies.pm @@ -3,7 +3,7 @@ package DBIx::Class::Optional::Dependencies; use warnings; use strict; -use Carp (); +use Carp; # NO EXTERNAL NON-5.8.1 CORE DEPENDENCIES EVER (e.g. C::A::G) # This module is to be loaded by Makefile.PM on a pristine system @@ -11,13 +11,20 @@ use Carp (); # POD is generated automatically by calling _gen_pod from the # Makefile.PL in $AUTHOR mode -my $json_any = { - 'JSON::Any' => '1.22', +# NOTE: the rationale for 2 JSON::Any versions is that +# we need the newer only to work around JSON::XS, which +# itself is an optional dep +my $min_json_any = { + 'JSON::Any' => '1.23', +}; +my $test_and_dist_json_any = { + 'JSON::Any' => '1.31', }; my $moose_basic = { 'Moose' => '0.98', 'MooseX::Types' => '0.21', + 'MooseX::Types::LoadableClass' => '0.011', }; my $replicated = { @@ -26,10 +33,9 @@ my $replicated = { my $admin_basic = { %$moose_basic, - %$json_any, + %$min_json_any, 'MooseX::Types::Path::Class' => '0.05', 'MooseX::Types::JSON' => '0.02', - 'namespace::autoclean' => '0.09', }; my $admin_script = { @@ -106,10 +112,6 @@ my $rdbms_firebird_odbc = { }; my $reqs = { - dist => { - #'Module::Install::Pod::Inherit' => '0.01', - }, - replicated => { req => $replicated, pod => { @@ -146,20 +148,13 @@ my $reqs = { }, }, - test_admin_script => { - req => { - %$admin_script, - ($^O eq 'MSWin32' ? ('Win32::ShellQuote' => 0) : ()), - } - }, - deploy => { req => { - 'SQL::Translator' => '0.11006', + 'SQL::Translator' => '0.11018', }, pod => { title => 'Storage::DBI::deploy()', - desc => 'Modules required for L and L', + desc => 'Modules required for L and L', }, }, @@ -175,7 +170,7 @@ my $reqs = { test_pod => { req => { - 'Test::Pod' => '1.41', + 'Test::Pod' => '1.42', }, }, @@ -186,26 +181,44 @@ my $reqs = { }, }, - test_notabs => { + test_whitespace => { req => { + 'Test::EOL' => '1.0', 'Test::NoTabs' => '0.9', }, }, - test_eol => { + test_strictures => { req => { - 'Test::EOL' => '1.0', + 'Test::Strict' => '0.20', }, }, test_prettydebug => { - req => $json_any, + req => $min_json_any, + }, + + test_admin_script => { + req => { + %$admin_script, + %$test_and_dist_json_any, + 'JSON' => 0, + 'JSON::PP' => 0, + 'Cpanel::JSON::XS' => 0, + 'JSON::XS' => 0, + $^O eq 'MSWin32' + # for t/admin/10script.t + ? ('Win32::ShellQuote' => 0) + # DWIW does not compile (./configure even) on win32 + : ('JSON::DWIW' => 0 ) + , + } }, - test_leaks => { + test_leaks_heavy => { req => { - 'Test::Memory::Cycle' => '0', - 'Devel::Cycle' => '1.10', + 'Class::MethodCache' => '0.02', + 'PadWalker' => '1.06', }, }, @@ -242,7 +255,6 @@ my $reqs = { test_cdbicompat => { req => { - 'Class::DBI' => 0, 'Class::DBI::Plugin::DeepAbstractSearch' => '0', %$datetime_basic, 'Time::Piece::MySQL' => '0', @@ -441,7 +453,6 @@ my $reqs = { ? ( # when changing this list make sure to adjust xt/optional_deps.t %$rdbms_pg, - ($^O ne 'MSWin32' ? ('Sys::SigAction' => '0') : ()), 'DBD::Pg' => '2.009002', ) : () }, @@ -606,27 +617,60 @@ my $reqs = { }, }, + dist_dir => { + req => { + %$test_and_dist_json_any, + 'ExtUtils::MakeMaker' => '6.64', + 'Pod::Inherit' => '0.91', + }, + }, + + dist_upload => { + req => { + 'CPAN::Uploader' => '0.103001', + }, + }, + }; + +### Public API + +# OO for (mistakenly considered) ease of extensibility, not due to any need to +# carry state of any sort. This API is currently used outside, so leave as-is. +# FIXME - make sure to not propagate this further if module is extracted as a +# standalone library - keep the stupidity to a DBIC-secific shim! +# sub req_list_for { my ($class, $group) = @_; - Carp::croak "req_list_for() expects a requirement group name" + croak "req_list_for() expects a requirement group name" unless $group; my $deps = $reqs->{$group}{req} - or Carp::croak "Requirement group '$group' does not exist"; + or croak "Requirement group '$group' does not exist"; return { %$deps }; } +sub req_group_list { + return { map { $_ => { %{ $reqs->{$_}{req} || {} } } } (keys %$reqs) }; +} + +sub req_errorlist_for { + my ($class, $group) = @_; + + croak "req_errorlist_for() expects a requirement group name" + unless $group; + + return $class->_check_deps($group)->{errorlist}; +} -our %req_availability_cache; sub req_ok_for { my ($class, $group) = @_; - Carp::croak "req_ok_for() expects a requirement group name" + croak "req_ok_for() expects a requirement group name" unless $group; return $class->_check_deps($group)->{status}; @@ -635,21 +679,27 @@ sub req_ok_for { sub req_missing_for { my ($class, $group) = @_; - Carp::croak "req_missing_for() expects a requirement group name" + croak "req_missing_for() expects a requirement group name" unless $group; return $class->_check_deps($group)->{missing}; } -sub req_errorlist_for { +sub die_unless_req_ok_for { my ($class, $group) = @_; - Carp::croak "req_errorlist_for() expects a requirement group name" + croak "die_unless_req_ok_for() expects a requirement group name" unless $group; - return $class->_check_deps($group)->{errorlist}; + $class->_check_deps($group)->{status} + or die sprintf( "Required modules missing, unable to continue: %s\n", $class->_check_deps($group)->{missing} ); } + + +### Private OO API + +our %req_availability_cache; sub _check_deps { my ($class, $group) = @_; @@ -672,8 +722,8 @@ sub _check_deps { my $res; if (keys %errors) { - my $missing = join (', ', map { $deps->{$_} ? "$_ >= $deps->{$_}" : $_ } (sort keys %errors) ); - $missing .= " (see $class for details)" if $reqs->{$group}{pod}; + my $missing = join (', ', map { $deps->{$_} ? qq("${_}~>=$deps->{$_}") : $_ } (sort keys %errors) ); + $missing .= " (see $class documentation for details)" if $reqs->{$group}{pod}; $res = { status => 0, errorlist => \%errors, @@ -692,19 +742,11 @@ sub _check_deps { }; } -sub req_group_list { - return { map { $_ => { %{ $reqs->{$_}{req} || {} } } } (keys %$reqs) }; -} - # This is to be called by the author only (automatically in Makefile.PL) sub _gen_pod { - my ($class, $distver) = @_; - - my $modfn = __PACKAGE__ . '.pm'; - $modfn =~ s/\:\:/\//g; + my ($class, $distver, $pod_dir) = @_; - my $podfn = __FILE__; - $podfn =~ s/\.pm$/\.pod/; + die "No POD root dir supplied" unless $pod_dir; $distver ||= eval { require DBIx::Class; DBIx::Class->VERSION; } @@ -717,11 +759,27 @@ sub _gen_pod { "\n\n---------------------------------------------------------------------\n" ; + # do not ask for a recent version, use 1.x API calls + # this *may* execute on a smoker with old perl or whatnot + require File::Path; + + (my $modfn = __PACKAGE__ . '.pm') =~ s|::|/|g; + + (my $podfn = "$pod_dir/$modfn") =~ s/\.pm$/\.pod/; + (my $dir = $podfn) =~ s|/[^/]+$||; + + File::Path::mkpath([$dir]); + my $sqltver = $class->req_list_for ('deploy')->{'SQL::Translator'} or die "Hrmm? No sqlt dep?"; - my @chunks = ( - <<'EOC', + + my @chunks; + +#@@ +#@@ HEADER +#@@ + push @chunks, <<"EOC"; ######################################################################### ##################### A U T O G E N E R A T E D ######################## ######################################################################### @@ -730,48 +788,85 @@ sub _gen_pod { # will be lost. If you need to change the generated text edit _gen_pod() # at the end of $modfn # + +=head1 NAME + +$class - Optional module dependency specifications (for module authors) EOC - '=head1 NAME', - "$class - Optional module dependency specifications (for module authors)", - '=head1 SYNOPSIS', - <<"EOS", -Somewhere in your build-file (e.g. L's Makefile.PL): + + +#@@ +#@@ SYNOPSIS HEADING +#@@ + push @chunks, <<"EOC"; +=head1 SYNOPSIS + +Somewhere in your build-file (e.g. L's F): ... - configure_requires 'DBIx::Class' => '$distver'; + \$EUMM_ARGS{CONFIGURE_REQUIRES} = { + \%{ \$EUMM_ARGS{CONFIGURE_REQUIRES} || {} }, + 'DBIx::Class' => '$distver', + }; - require $class; + ... - my \$deploy_deps = $class->req_list_for('deploy'); + my %DBIC_DEPLOY_DEPS = %{ eval { + require $class; + $class->req_list_for('deploy'); + } || {} }; - for (keys %\$deploy_deps) { - requires \$_ => \$deploy_deps->{\$_}; - } + \$EUMM_ARGS{PREREQ_PM} = { + \%DBIC_DEPLOY_DEPS, + \%{ \$EUMM_ARGS{PREREQ_PM} || {} }, + }; ... -Note that there are some caveats regarding C, more info -can be found at L -EOS - '=head1 DESCRIPTION', - <<'EOD', + ExtUtils::MakeMaker::WriteMakefile(\%EUMM_ARGS); + +B: The C protection within the example is due to support for +requirements during L build phase|CPAN::Meta::Spec/Phases> +not being available on a sufficient portion of production installations of +Perl. Robust support for such dependency requirements is available in the +L installer only since version C<1.94_56> first made available for +production with perl version C<5.12>. It is the belief of the current +maintainer that support for requirements during the C build phase +will not be sufficiently ubiquitous until the B at the earliest, +hence the extra care demonstrated above. It should also be noted that some +3rd party installers (e.g. L) 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 L have external module dependencies on their own. In order not to burden the average user -with modules he will never use, these optional dependencies are not included +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 is missing one or several modules required for -its operation. This module is the central holding place for the current list +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 core authors, and DBIx::Class extension authors alike. -EOD - '=head1 CURRENT REQUIREMENT GROUPS', - <<'EOD', -Dependencies are organized in C and each group can list one or more -required modules, with an optional minimum version (or 0 for any version). -The group name can be used in the -EOD - ); + +Dependencies are organized in L where each +group can list one or more required modules, with an optional minimum version +(or 0 for any version). The group name can be used in the +L as described below. +EOC + + +#@@ +#@@ REQUIREMENT GROUPLIST HEADING +#@@ + push @chunks, '=head1 CURRENT REQUIREMENT GROUPS'; for my $group (sort keys %$reqs) { my $p = $reqs->{$group}{pod} @@ -792,79 +887,130 @@ EOD ); } - push @chunks, ( - '=head1 METHODS', - '=head2 req_group_list', - '=over', - '=item Arguments: none', - '=item Returns: \%list_of_requirement_groups', - '=back', - <<'EOD', + +#@@ +#@@ API DOCUMENTATION HEADING +#@@ + push @chunks, <<'EOC'; + +=head1 METHODS + +=head2 req_group_list + +=over + +=item Arguments: none + +=item Return Value: \%list_of_requirement_groups + +=back + This method should be used by DBIx::Class packagers, to get a hashref of all dependencies keyed by dependency group. Each key (group name) can be supplied to one of the group-specific methods below. -EOD - - '=head2 req_list_for', - '=over', - '=item Arguments: $group_name', - '=item Returns: \%list_of_module_version_pairs', - '=back', - <<'EOD', +The B of the returned hash are currently a set of options B. If you have use for any of the contents - contact the +maintainers, instead of treating this as public (left alone stable) API. + +=head2 req_list_for + +=over + +=item Arguments: $group_name + +=item Return Value: \%list_of_module_version_pairs + +=back + This method should be used by DBIx::Class extension authors, to determine the version of modules a specific feature requires in the B version of -DBIx::Class. See the L for a real-world -example. -EOD - - '=head2 req_ok_for', - '=over', - '=item Arguments: $group_name', - '=item Returns: 1|0', - '=back', - <<'EOD', +DBIx::Class. See the L for a real-world example. + +=head2 req_ok_for + +=over + +=item Arguments: $group_name + +=item Return Value: 1|0 + +=back + Returns true or false depending on whether all modules required by C<$group_name> are present on the system and loadable. -EOD - - '=head2 req_missing_for', - '=over', - '=item Arguments: $group_name', - '=item Returns: $error_message_string', - '=back', - <<"EOD", -Returns a single line string suitable for inclusion in larger error messages. -This method would normally be used by DBIx::Class core-module author, to -indicate to the user that he needs to install specific modules before he will -be able to use a specific feature. + +=head2 req_missing_for + +=over + +=item Arguments: $group_name + +=item Return Value: $error_message_string + +=back + +This method would normally be used by DBIx::Class core-modules, to indicate to +the user that they need to install specific modules before being able to use a +specific feature set. For example if some of the requirements for C are not available, the returned string could look like: +EOC - SQL::Translator >= $sqltver (see $class for details) + push @chunks, qq{ "SQL::Translator~>=$sqltver" (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. -EOD - - '=head2 req_errorlist_for', - '=over', - '=item Arguments: $group_name', - '=item Returns: \%list_of_loaderrors_per_module', - '=back', - <<'EOD', -Returns a hashref containing the actual errors that occured while attempting + +=head2 die_unless_req_ok_for + +=over + +=item Arguments: $group_name + +=back + +Checks if L passes for the supplied C<$group_name>, and +in case of failure throws an exception including the information +from L. + +=head2 req_errorlist_for + +=over + +=item Arguments: $group_name + +=item Return Value: \%list_of_loaderrors_per_module + +=back + +Returns a hashref containing the actual errors that occurred while attempting to load each module in the requirement group. -EOD - '=head1 AUTHOR', - 'See L.', - '=head1 LICENSE', - 'You may distribute this code under the same terms as Perl itself', - ); - - open (my $fh, '>', $podfn) or Carp::croak "Unable to write to $podfn: $!"; - print $fh join ("\n\n", @chunks); - close ($fh); +EOC + +#@@ +#@@ FOOTER +#@@ + push @chunks, <<'EOC'; +=head1 FURTHER QUESTIONS? + +Check the list of L. + +=head1 COPYRIGHT AND LICENSE + +This module is free software L +by the L. You can +redistribute it and/or modify it under the same terms as the +L. +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;