Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DBIx::Class::Schema::LUserIContributedcPerl:Documentatptional::Dependencies(3)

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.

   -skip_all_without
       Arguments: @group_names

       A convenience wrapper for use during testing: EOC

	 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';

       It also takes into account the "RELEASE_TESTING"	environment variable
       and behaves like	"-die_without" for any requirement groups marked as
       "release_testing_mandatory".

   -die_without
       Arguments: @group_names

       A convenience wrapper around "die_unless_req_ok_for": EOC

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

	 push @chunks, <<'EOC';

   -list_missing
       Arguments: @group_names

       A convenience wrapper around "modreq_missing_for":

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

METHODS
   req_group_list
       Arguments: none
       Return Value: \%list_of_requirement_groups

       This method should be used by DBIx::Class::Schema::Loader packagers, to
       get a hashref of	all dependencies keyed by dependency group. Each key
       (group name), or	a combination thereof (as an arrayref) can be supplied
       to the methods below.  The values of the	returned hash are currently a
       set of options without a	well defined structure.	If you have use	for
       any of the contents - contact the maintainers, instead of treating this
       as public (left alone stable) API.

   req_list_for
       Arguments: $group_name |	\@group_names
       Return Value: \%set_of_module_version_pairs

       This method should be used by DBIx::Class::Schema::Loader extension
       authors,	to determine the version of modules a specific set of features
       requires	for this version of DBIx::Class::Schema::Loader	(regardless of
       their availability on the system).  See the "SYNOPSIS" for a real-world
       example.

       When handling "test_*" groups this method behaves differently from
       "modreq_list_for" below (and is the only	such inconsistency among the
       "req_*" methods). If a particular group declares	as requirements	some
       "environment variables" and these requirements are not satisfied	(the
       envvars are unset) - then the "module requirements" of this group are
       not included in the returned list.

   modreq_list_for
       Arguments: $group_name |	\@group_names
       Return Value: \%set_of_module_version_pairs

       Same as "req_list_for" but does not take	into consideration any
       "environment variable requirements" - returns just the list of required
       modules.

   req_ok_for
       Arguments: $group_name |	\@group_names
       Return Value: 1|0

       Returns true or false depending on whether all modules/envvars required
       by the group(s) are loadable/set	on the system.

   req_missing_for
       Arguments: $group_name |	\@group_names
       Return Value: $error_message_string

       Returns a single-line string suitable for inclusion in larger error
       messages.  This method would normally be	used by
       DBIx::Class::Schema::Loader core	features, to indicate to the user that
       they need to install specific modules and/or set	specific environment
       variables before	being able to use a specific feature set.

       For example if some of the requirements for "deploy" are	not available,
       the returned string could look like: EOC

	 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>

   modreq_missing_for
       Arguments: $group_name |	\@group_names
       Return Value: $error_message_string

       Same as "req_missing_for" except	that the error string is guaranteed to
       be either empty,	or contain a set of module requirement specifications
       suitable	for piping to e.g. cpanminus. The method explicitly does not
       attempt to validate the state of	required environment variables (if
       any).

       For instance if some of the requirements	for "deploy" are not
       available, the returned string could look like: EOC

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

	 push @chunks, <<'EOC';

       See also	"-list_missing".

   skip_without
       Arguments: $group_name |	\@group_names

       A convenience wrapper around skip. It does not take neither a reason
       (it is generated	by "req_missing_for") nor an amount of skipped tests
       (it is always 1,	thus mandating unconditional use of done_testing).
       Most useful in combination with ad hoc requirement specifications: EOC

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

	   ...
	 }
       EOC

	 push @chunks, <<'EOC';

   die_unless_req_ok_for
       Arguments: $group_name |	\@group_names

       Checks if "req_ok_for" passes for the supplied group(s),	and in case of
       failure throws an exception including the information from
       "req_missing_for". See also "-die_without".

   modreq_errorlist_for
       Arguments: $group_name |	\@group_names
       Return Value: \%set_of_loaderrors_per_module

       Returns a hashref containing the	actual errors that occurred while
       attempting to load each module in the requirement group(s).

   req_errorlist_for
       Deprecated method name, equivalent (via proxy) to
       "modreq_errorlist_for".

       EOC

       #@@ #@@ FOOTER #@@
	 push @chunks, <<'EOC';	=head1 FURTHER QUESTIONS?

       Check the list of additional DBIC resources.

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;

perl v5.32.0		DBIx::Class::Schema::Loader::Optional::Dependencies(3)

NAME | IMPORT-LIKE ACTIONS | METHODS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=DBIx::Class::Schema::Loader::Optional::Dependencies&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help