[gentoo-dev] [PATCH 0/6] perl-functions.eclass: new utility functions

[gentoo-dev] [PATCH 0/6] perl-functions.eclass: new utility functions

[kentnl]

From: Kent Fredric <kentnl@gentoo.org>

Greetings,

Following are a series of suggested utilities I want to add to
perl-functions.eclass and additional eyes and feedback are desired
before I finally commit them.

Included are 3 utilities for varying levels of detail in querying
the status of installed Perl Modules from the context of the Perl
runtime ( which in certain circumstances can differ from the state
portage has, especially when they're only build dependencies )

Two additional utilities are in place to simplify the effort
involved with discovering the installation target paths.

And the final utility, serves as a straight foward "I'm not a perl
wizard, I just have some .pm files, put them somewhere?" tool.

Any enhancements welcome.

NB: Apologies if anyone gets dupes... I had some problems with email
configuration and git send-email

Kent Fredric (6):
  perl-functions.eclass: Add perl_has_module
  perl-functions.eclass: add perl_has_module_version
  perl-functions.eclass: add perl_get_module_version
  perl-functions.eclass: add perl_get_raw_vendorlib
  perl-functions.eclass: add perl_get_vendorlib
  perl-functions.eclass: add perl_domodule

 eclass/perl-functions.eclass | 222 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 222 insertions(+)

-- 
2.11.0

[gentoo-dev] [PATCH 1/6] perl-functions.eclass: Add perl_has_module

[kentnl]

From: Kent Fredric <kentnl@gentoo.org>

This is an incredibly fast way to check if Perl considers a module
of the given name installed in any capacity, including broken.

As long as "Foo.pm" is somewhere in @INC, `perl_has_module Foo` will
return true.

Even `perl_has_module threads` will return true on non-threaded perls,
due to that module still being present, and the module only fataling
when loaded.

Whereas `perl_has_module_version threads 0` will always fail on
non-threaded perls.
---
 eclass/perl-functions.eclass | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/eclass/perl-functions.eclass b/eclass/perl-functions.eclass
index 1542b98cd4..10d19e859d 100644
--- a/eclass/perl-functions.eclass
+++ b/eclass/perl-functions.eclass
@@ -319,3 +319,31 @@ perl_doexamples() {
 
 	# is there a way to undo "docinto" ?
 }
+
+# @FUNCTION: perl_has_module
+# @USAGE: perl_has_module "Test::Tester"
+# @DESCRIPTION:
+# Query the installed system Perl to see if a given module is installed.
+# This does **not** load the module in question, only anticipates if it *might* load.
+#
+# This is primarily for the purposes of dependency weakening so that conditional
+# behaviour can be triggered without adding dependencies to portage which would confuse
+# a dependency resolver.
+#
+# returns 'true' if the module is available, returns error if the module is not available
+
+perl_has_module() {
+	debug-print-function $FUNCNAME "$@"
+
+	[[ $# -gt 0 ]] || die "${FUNCNAME}: No module name provided"
+	[[ $# -lt 2 ]] || die "${FUNCNAME}: Too many parameters ($#)"
+
+	perl -we 'my $mn = $ARGV[0];
+		$mn =~ s{(::|\x{27})}{/}g;
+		for(@INC){
+			next if ref $_;
+			exit 0 if -r $_ . q[/] . $mn . q[.pm]
+		}
+		exit 1' "$@";
+}
+
-- 
2.11.0

[gentoo-dev] [PATCH 2/6] perl-functions.eclass: add perl_has_module_version

[kentnl]

From: Kent Fredric <kentnl@gentoo.org>

This is a utility for runtime checking if a module of a given version
is installed from the perspective of Perl, whos opinion could be
different than portage in the event of perl-core/* dual life effects
shortly after a major Perl upgrade.

Use this only if perl_has_module is insufficient, as the overheads
and risk of side effects from this approach are high, given the module
has to be actually loaded for the version comparison to happen.

exits "true" if Perl has the given module installed at the given
version ( or later ), exits "false" otherwise.
---
 eclass/perl-functions.eclass | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/eclass/perl-functions.eclass b/eclass/perl-functions.eclass
index 10d19e859d..c3a0e1ee30 100644
--- a/eclass/perl-functions.eclass
+++ b/eclass/perl-functions.eclass
@@ -347,3 +347,36 @@ perl_has_module() {
 		exit 1' "$@";
 }
 
+# @FUNCTION: perl_has_module_version
+# @USAGE: perl_has_module_version "Test::Tester" "0.017"
+# @DESCRIPTION:
+# Query the installed system Perl to see if a given module is installed
+# and is at least a given version.
+#
+# This requires more caution to use than perl_has_module as it requires
+# loading the module in question to determine version compatibility,
+# which can be SLOW, and can have side effects (ie: compilation fails in
+# require due to some dependency, resulting in a "Fail")
+#
+# Also take care to note the module version is a *minimum*, *must* be
+# written in upstream versions format and should be a a legal upstream version
+#
+# returns a true exit code if the module is both available and is at least
+# the specified version
+
+perl_has_module_version() {
+	debug-print-function $FUNCNAME "$@"
+
+	[[ $# -gt 0 ]] || die "${FUNCNAME}: No module name provided"
+	[[ $# -gt 1 ]] || die "${FUNCNAME}: No module version provided"
+	[[ $# -lt 3 ]] || die "${FUNCNAME}: Too many parameters ($#)"
+
+	perl -we 'my $mn = $ARGV[0];
+		$mn =~ s{(::|\x{27})}{/}g;
+		exit ( eval {
+			require qq[${mn}.pm];
+			$ARGV[0]->VERSION($ARGV[1]);
+			1
+		} ? 0 : 1 )' "$@"
+}
+
-- 
2.11.0

[gentoo-dev] [PATCH 3/6] perl-functions.eclass: add perl_get_module_version

[kentnl]

From: Kent Fredric <kentnl@gentoo.org>

This utility provides informational data describing the given module
names state of installation, either as a version, or as an error
message describing the grade of failure incurred in module loading.

It has the side effect that it most load the module (and its
dependencies) into memory to give a report value, and can be expensive
and have side-effects from Perl code execuring while the module loads,
including (but not limited to) people calling POSIX::_exit

This is the slowest way of inspecting state about a module, as
it must load the module
---
 eclass/perl-functions.eclass | 51 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/eclass/perl-functions.eclass b/eclass/perl-functions.eclass
index c3a0e1ee30..027cb0cf7e 100644
--- a/eclass/perl-functions.eclass
+++ b/eclass/perl-functions.eclass
@@ -380,3 +380,54 @@ perl_has_module_version() {
 		} ? 0 : 1 )' "$@"
 }
 
+# @FUNCTION: perl_get_module_version
+# @USAGE: MODVER=$(perl_get_module_version "Test::Simple")
+# @DESCRIPTION:
+# Query the installed system perl to report the version of the installed
+# module.
+#
+# Note this should be strictly for diagnostic purposes to the end user,
+# and may be of selective use in pkg_info to enhance
+# emerge --info reports.
+#
+# Anything that does version comparisons **must not** use the return value
+# from this function
+#
+# Also note that this **must** at least attempt load the module in
+# question as part of its operation, and is subsequently prone to SLOWness.
+#
+# Return codes return error in both compilation-failure and not-installed cases.
+
+perl_get_module_version() {
+	debug-print-function $FUNCNAME "$@"
+
+	[[ $# -gt 0 ]] || die "${FUNCNAME}: No module name provided"
+	[[ $# -lt 2 ]] || die "${FUNCNAME}: Too many parameters ($#)"
+
+	if ! perl_has_module "$@" ; then
+		echo "(Not Installed)";
+		return 1;
+	fi
+
+	# Todo: What do we do if require fails? spew to stderr
+	# or stay silent?
+
+	perl -we 'my $mn = $ARGV[0];
+		$mn =~ s{(::|\x{27})}{/}g;
+		local $@;
+		eval { require qq[${mn}.pm]; 1 } or do {
+			print q[(Compilation failed in require)];
+			exit 1;
+		};
+		my $stash = \%{ $ARGV[0] . q[::] };
+		if ( not exists $stash->{VERSION} ) {
+			print q[(No VERSION property)];
+			exit 0;
+		}
+		if ( not defined ${$stash->{VERSION}} ) {
+			print q[(undef)];
+			exit 0;
+		}
+		print ${$stash->{VERSION}};
+		exit 0; ' "$@"
+}
-- 
2.11.0

[gentoo-dev] [PATCH 4/6] perl-functions.eclass: add perl_get_raw_vendorlib

[kentnl]

From: Kent Fredric <kentnl@gentoo.org>

---
 eclass/perl-functions.eclass | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/eclass/perl-functions.eclass b/eclass/perl-functions.eclass
index 027cb0cf7e..3f73ac87c7 100644
--- a/eclass/perl-functions.eclass
+++ b/eclass/perl-functions.eclass
@@ -431,3 +431,21 @@ perl_get_module_version() {
 		print ${$stash->{VERSION}};
 		exit 0; ' "$@"
 }
+
+# @FUNCTION: perl_get_raw_vendorlib
+# @USAGE: perl_get_raw_vendorlib
+# @DESCRIPTION:
+# Convenience function to optimise for a common case without double-handling
+# variables everywhere.
+#
+# Note: Will include EPREFIX where relevant
+perl_get_raw_vendorlib() {
+	debug-print-function $FUNCNAME "$@"
+
+	[[ $# -lt 0 ]] || die "${FUNCNAME}: Too many parameters ($#)"
+
+	perl -MConfig \
+		-e'exists $Config{$ARGV[0]} || die qq{No such Config key "$ARGV[0]"};
+		   print $Config{$ARGV[0]};
+		   exit 0' -- "installvendorlib" || die "Can't extract installvendorlib from Perl Configuration"
+}
\ No newline at end of file
-- 
2.11.0

[gentoo-dev] [PATCH 5/6] perl-functions.eclass: add perl_get_vendorlib

[kentnl]

From: Kent Fredric <kentnl@gentoo.org>

---
 eclass/perl-functions.eclass | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/eclass/perl-functions.eclass b/eclass/perl-functions.eclass
index 3f73ac87c7..1652ceaa10 100644
--- a/eclass/perl-functions.eclass
+++ b/eclass/perl-functions.eclass
@@ -448,4 +448,23 @@ perl_get_raw_vendorlib() {
 		-e'exists $Config{$ARGV[0]} || die qq{No such Config key "$ARGV[0]"};
 		   print $Config{$ARGV[0]};
 		   exit 0' -- "installvendorlib" || die "Can't extract installvendorlib from Perl Configuration"
+}
+
+# @FUNCTION: perl_get_vendorlib
+# @USAGE: perl_get_vendorlib
+# @DESCRIPTION:
+#
+# Convenience helper for returning Perls' vendor install root
+# without EPREFIXing.
+perl_get_vendorlib() {
+	debug-print-function $FUNCNAME "$@"
+
+	[[ $# -lt 0 ]] || die "${FUNCNAME}: Too many parameters ($#)"
+
+	# Requires perl 5.14 for /r attribute of s///
+	# Just in case somebody out there is stuck in a time warp: upgrade perl first
+	perl -M5.014 -MConfig \
+		-e'exists $Config{$ARGV[0]} || die qq{No such Config key "$ARGV[0]"};
+		   print $Config{$ARGV[0]} =~ s{\A\Q$ARGV[1]\E}{}r;
+		   exit 0' -- "installvendorlib" "$EPREFIX" || die "Can't extract installvendorlib from Perl Configuration"
 }
\ No newline at end of file
-- 
2.11.0

[gentoo-dev] [PATCH 6/6] perl-functions.eclass: add perl_domodule

[kentnl]

From: Kent Fredric <kentnl@gentoo.org>

---
 eclass/perl-functions.eclass | 75 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 74 insertions(+), 1 deletion(-)

diff --git a/eclass/perl-functions.eclass b/eclass/perl-functions.eclass
index 1652ceaa10..9eed888f75 100644
--- a/eclass/perl-functions.eclass
+++ b/eclass/perl-functions.eclass
@@ -467,4 +467,77 @@ perl_get_vendorlib() {
 		-e'exists $Config{$ARGV[0]} || die qq{No such Config key "$ARGV[0]"};
 		   print $Config{$ARGV[0]} =~ s{\A\Q$ARGV[1]\E}{}r;
 		   exit 0' -- "installvendorlib" "$EPREFIX" || die "Can't extract installvendorlib from Perl Configuration"
-}
\ No newline at end of file
+}
+
+# @FUNCTION: perl_domodule
+# @USAGE: perl_domodule [options] <files>
+# @DESCRIPTION:
+# Installs files in paths where they can be found in the default
+# Perl runtime.
+#
+# The contents of the <files> list are copied into Perls Vendor library path
+# as follows:
+# @CODE
+#   # install perl/File.pm as Samba::File
+# 	pushd perl/
+# 	perl_domodule -C Samba File.pm
+#
+#   # install perl/ recursively under VENDORLIB/Samba/
+#   pushd perl/
+#   perl_domodule -C Samba -r .
+# @CODE
+#
+# @CODE
+# 	options:
+# 		-C Target/Name
+#			The subdirectory relative to the Perl VENDOR_LIB
+#			to install into.
+#
+#			defaults to ""
+#       -r
+#			Install directories recursively ( see doins )
+#   files:
+#			list of .pm files to install to VENDORLIB
+# @CODE
+
+perl_domodule() {
+	local target_prefix=""
+	local files=()
+	local doins_opts=()
+
+	local recursive=false
+	local target
+	local file
+
+	while [[ $# -gt 0 ]] ; do
+		case $1 in
+			-C|--target-prefix)
+				[[ -z "${2}" || "${2:0:1}" == "-" ]] && die "${FUNCNAME}: -C|--target-prefix expects an argument, got \"$2\"!"
+				target_prefix="${2}";
+				shift 2;;
+			-r)
+				recursive=true
+				shift;;
+			*)
+				[[ -z "${1}" || "${1:0:1}" == "-" ]] && die "${FUNCNAME}: Unknown argument \"${1}\"!"
+				files+=( "${1}" )
+				shift 1;;
+		esac
+	done
+
+	if $recursive; then
+		doins_opts+=( "-r" )
+	fi
+	for file in "${files[@]}"; do
+		[[ -e "${file}" ]] || die "$FUNCNAME: Argument \"${file}\" is not an existing file"
+		[[ $recursive && -d "${file}" ]] && die "$FUNCNAME: Argument \"${file}\" is a directory ( needs -r parameter )"
+	done
+
+	target="$(perl_get_vendorlib)"
+
+	# Extend target if target_prefix is set
+	[[ -z "${target_prefix}" ]] || target="${target%/}/${target_prefix#/}"
+
+	insinto "/${target#/}"
+	doins "${doins_opts[@]}" "${files[@]}"
+}
-- 
2.11.0