eclass/perl-functions.eclass

   1 # Copyright 1999-2019 Gentoo Authors
   2 # Distributed under the terms of the GNU General Public License v2
   3
   4 # @ECLASS: perl-functions.eclass
   5 # @MAINTAINER:
   6 # perl@gentoo.org
   7 # @AUTHOR:
   8 # Seemant Kulleen <seemant@gentoo.org>
   9 # Andreas K. Huettel <dilfridge@gentoo.org>
  10 # Kent Fredric <kentnl@gentoo.org>
  11 # @SUPPORTED_EAPIS: 5 6 7
  12 # @BLURB: helper functions eclass for perl modules
  13 # @DESCRIPTION:
  14 # The perl-functions eclass is designed to allow easier installation of perl
  15 # modules, and their incorporation into the Gentoo Linux system.
  16 # It provides helper functions, no phases or variable manipulation in
  17 # global scope.
  18
  19 [[ ${CATEGORY} == "perl-core" ]] && inherit alternatives
  20
  21 case "${EAPI:-0}" in
  22         5|6|7)
  23                 ;;
  24         *)
  25                 die "EAPI=${EAPI} is not supported by perl-functions.eclass"
  26                 ;;
  27 esac
  28
  29 perlinfo_done=false
  30
  31 # @FUNCTION: perl_set_version
  32 # @DESCRIPTION:
  33 # Extract version information and installation paths from the current Perl
  34 # interpreter.
  35 #
  36 # This sets the following variables: PERL_VERSION, SITE_ARCH, SITE_LIB,
  37 # ARCH_LIB, VENDOR_LIB, VENDOR_ARCH
  38 #
  39 # This function used to be called perlinfo as well.
  40 #
  41 # Example:
  42 # @CODE
  43 # perl_set_version
  44 # echo $PERL_VERSION
  45 # @CODE
  46 perl_set_version() {
  47         debug-print-function $FUNCNAME "$@"
  48         debug-print "$FUNCNAME: perlinfo_done=${perlinfo_done}"
  49         ${perlinfo_done} && return 0
  50         perlinfo_done=true
  51
  52         local f version install{{site,vendor}{arch,lib},archlib}
  53         eval "$(perl -V:{version,install{{site,vendor}{arch,lib},archlib}} )"
  54         PERL_VERSION=${version}
  55         SITE_ARCH=${installsitearch}
  56         SITE_LIB=${installsitelib}
  57         ARCH_LIB=${installarchlib}
  58         VENDOR_LIB=${installvendorlib}
  59         VENDOR_ARCH=${installvendorarch}
  60 }
  61
  62 # @FUNCTION: perl_delete_localpod
  63 # @DESCRIPTION:
  64 # Remove stray perllocal.pod files in the temporary install directory D.
  65 #
  66 # This function used to be called fixlocalpod as well.
  67 perl_delete_localpod() {
  68         debug-print-function $FUNCNAME "$@"
  69
  70         find "${D}" -type f -name perllocal.pod -delete
  71         find "${D}" -depth -mindepth 1 -type d -empty -delete
  72 }
  73
  74 # @FUNCTION: perl_fix_osx_extra
  75 # @DESCRIPTION:
  76 # Look through ${S} for AppleDouble encoded files and get rid of them.
  77 perl_fix_osx_extra() {
  78         debug-print-function $FUNCNAME "$@"
  79
  80         local f
  81         find "${S}" -type f -name "._*" -print0 | while read -rd '' f ; do
  82                 einfo "Removing AppleDouble encoded Macintosh file: ${f#${S}/}"
  83                 rm -f "${f}"
  84                 f=${f#${S}/}
  85                 grep -q "${f}" "${S}"/MANIFEST && \
  86                         elog "AppleDouble encoded Macintosh file in MANIFEST: ${f#${S}/}"
  87         done
  88 }
  89
  90 # @FUNCTION: perl_delete_module_manpages
  91 # @DESCRIPTION:
  92 # Bump off manpages installed by the current module such as *.3pm files as well
  93 # as empty directories.
  94 perl_delete_module_manpages() {
  95         debug-print-function $FUNCNAME "$@"
  96
  97         if [[ -d "${ED}"/usr/share/man ]] ; then
  98                 find "${ED}"/usr/share/man -type f -name "*.3pm" -delete
  99                 find "${ED}"/usr/share/man -depth -type d -empty -delete
 100         fi
 101 }
 102
 103 # @FUNCTION: perl_delete_packlist
 104 # @DESCRIPTION:
 105 # Look through ${D} for .packlist files, empty .bs files and empty directories,
 106 # and get rid of items found.
 107 perl_delete_packlist() {
 108         debug-print-function $FUNCNAME "$@"
 109         perl_set_version
 110         if [[ -d ${D}/${VENDOR_ARCH} ]] ; then
 111                 find "${D}/${VENDOR_ARCH}" -type f -a -name .packlist -delete
 112                 perl_delete_emptybsdir
 113         fi
 114 }
 115
 116 # @FUNCTION: perl_delete_emptybsdir
 117 # @DESCRIPTION:
 118 # Look through ${D} for empty .bs files and empty directories,
 119 # and get rid of items found.
 120 perl_delete_emptybsdir() {
 121         debug-print-function $FUNCNAME "$@"
 122         perl_set_version
 123         if [[ -d ${D}/${VENDOR_ARCH} ]] ; then
 124                 find "${D}/${VENDOR_ARCH}" -type f \
 125                         -a -name '*.bs' -a -empty -delete
 126                 find "${D}" -depth -mindepth 1 -type d -empty -delete
 127         fi
 128 }
 129
 130 # @FUNCTION: perl_fix_packlist
 131 # @DESCRIPTION:
 132 # Look through ${D} for .packlist text files containing the temporary installation
 133 # folder (i.e. ${D}). If the pattern is found, silently replace it with `/'.
 134 # Remove duplicate entries; then validate all entries in the packlist against ${D}
 135 # and prune entries that do not correspond to installed files.
 136 perl_fix_packlist() {
 137         debug-print-function $FUNCNAME "$@"
 138
 139         local packlist_temp="${T}/.gentoo_packlist_temp"
 140         find "${D}" -type f -name '.packlist' -print0 | while read -rd '' f ; do
 141                 if file "${f}" | grep -q -i " text" ; then
 142                         einfo "Fixing packlist file /${f#${D}}"
 143
 144                         # remove the temporary build dir path
 145                         sed -i -e "s:${D%/}/:/:g" "${f}"
 146
 147                         # remove duplicate entries
 148                         sort -u "${f}" > "${packlist_temp}"
 149                         mv "${packlist_temp}" "${f}"
 150
 151                         # remove files that dont exist
 152                         cat "${f}" | while read -r entry; do
 153                                 if [ ! -e "${D}/${entry}" ]; then
 154                                         einfo "Pruning surplus packlist entry ${entry}"
 155                                         grep -v -x -F "${entry}" "${f}" > "${packlist_temp}"
 156                                         mv "${packlist_temp}" "${f}"
 157                                 fi
 158                         done
 159                 fi
 160         done
 161 }
 162
 163 # @FUNCTION: perl_remove_temppath
 164 # @DESCRIPTION:
 165 # Look through ${D} for text files containing the temporary installation
 166 # folder (i.e. ${D}). If the pattern is found, replace it with `/' and warn.
 167 perl_remove_temppath() {
 168         debug-print-function $FUNCNAME "$@"
 169
 170         find "${D}" -type f -not -name '*.so' -print0 | while read -rd '' f ; do
 171                 if file "${f}" | grep -q -i " text" ; then
 172                         grep -q "${D}" "${f}" && ewarn "QA: File contains a temporary path ${f}"
 173                         sed -i -e "s:${D%/}/:/:g" "${f}"
 174                 fi
 175         done
 176 }
 177
 178 # @FUNCTION: perl_rm_files
 179 # @USAGE: <list of files>
 180 # @DESCRIPTION:
 181 # Remove certain files from a Perl release and remove them from the MANIFEST
 182 # while we're there.
 183 #
 184 # Most useful in src_prepare for nuking bad tests, and is highly recommended
 185 # for any tests like 'pod.t', 'pod-coverage.t' or 'kwalitee.t', as what they
 186 # test is completely irrelevant to end users, and frequently fail simply
 187 # because the authors of Test::Pod... changed their recommendations, and thus
 188 # failures are only useful feedback to Authors, not users.
 189 #
 190 # Removing from MANIFEST also avoids needless log messages warning
 191 # users about files "missing from their kit".
 192 #
 193 # Example:
 194 # @CODE
 195 # src_test() {
 196 #   perl_rm_files t/pod{,-coverage}.t
 197 #   perl-module_src_test
 198 # }
 199 # @CODE
 200 perl_rm_files() {
 201         debug-print-function $FUNCNAME "$@"
 202         local skipfile="${T}/.gentoo_makefile_skip"
 203         local manifile="${S}/MANIFEST"
 204         local manitemp="${T}/.gentoo_manifest_temp"
 205         oldifs="$IFS"
 206         IFS="\n"
 207         for filename in "$@"; do
 208                 einfo "Removing un-needed ${filename}";
 209                 # Remove the file
 210                 rm -f "${S}/${filename}"
 211                 [[ -e "${manifile}" ]] && echo "${filename}" >> "${skipfile}"
 212         done
 213         if [[ -e "${manifile}" && -e "${skipfile}" ]]; then
 214                 einfo "Fixing Manifest"
 215                 grep -v -F -f "${skipfile}" "${manifile}" > "${manitemp}"
 216                 mv -f -- "${manitemp}" "${manifile}"
 217                 rm -- "${skipfile}";
 218         fi
 219         IFS="$oldifs"
 220 }
 221
 222 # @FUNCTION: perl_link_duallife_scripts
 223 # @DESCRIPTION:
 224 # Moves files and generates symlinks so dual-life packages installing scripts do not
 225 # lead to file collisions. Mainly for use in pkg_postinst and pkg_postrm, and makes
 226 # only sense for perl-core packages.
 227 perl_link_duallife_scripts() {
 228         debug-print-function $FUNCNAME "$@"
 229         if [[ ${CATEGORY} != perl-core ]] || ! has_version ">=dev-lang/perl-5.8.8-r8" ; then
 230                 return 0
 231         fi
 232
 233         local i ff
 234         if has "${EBUILD_PHASE:-none}" "postinst" "postrm" ; then
 235                 for i in "${DUALLIFESCRIPTS[@]}" ; do
 236                         alternatives_auto_makesym "/${i}" "/${i}-[0-9]*"
 237                 done
 238                 for i in "${DUALLIFEMAN[@]}" ; do
 239                         ff=`echo "${EROOT}"/${i%.1}-${PV}-${P}.1*`
 240                         ff=${ff##*.1}
 241                         alternatives_auto_makesym "/${i}${ff}" "/${i%.1}-[0-9]*"
 242                 done
 243         else
 244                 pushd "${ED}" > /dev/null
 245                 for i in $(find usr/bin -maxdepth 1 -type f 2>/dev/null) ; do
 246                         mv ${i}{,-${PV}-${P}} || die
 247                         #DUALLIFESCRIPTS[${#DUALLIFESCRIPTS[*]}]=${i##*/}
 248                         DUALLIFESCRIPTS[${#DUALLIFESCRIPTS[*]}]=${i}
 249                 done
 250                 for i in $(find usr/share/man/man1 -maxdepth 1 -type f 2>/dev/null) ; do
 251                         mv ${i} ${i%.1}-${PV}-${P}.1 || die
 252                         DUALLIFEMAN[${#DUALLIFEMAN[*]}]=${i}
 253                 done
 254                 popd > /dev/null
 255         fi
 256 }
 257
 258 # @FUNCTION: perl_check_env
 259 # @DESCRIPTION:
 260 # Checks a blacklist of known-suspect ENV values that can be accidentally set by users
 261 # doing personal perl work, which may accidentally leak into portage and break the
 262 # system perl installaton.
 263 # Dies if any of the suspect fields are found, and tell the user what needs to be unset.
 264 # There's a workaround, but you'll have to read the code for it.
 265 perl_check_env() {
 266         local errored value;
 267
 268         for i in PERL_MM_OPT PERL5LIB PERL5OPT PERL_MB_OPT PERL_CORE PERLPREFIX; do
 269                 # Next unless match
 270                 [ -v $i ] || continue;
 271
 272                 # Warn only once, and warn only when one of the bad values are set.
 273                 # record failure here.
 274                 if [ ${errored:-0} == 0 ]; then
 275                         if [ -n "${I_KNOW_WHAT_I_AM_DOING}" ]; then
 276                                 elog "perl-module.eclass: Suspicious environment values found.";
 277                         else
 278                                 eerror "perl-module.eclass: Suspicious environment values found.";
 279                         fi
 280                 fi
 281                 errored=1
 282
 283                 # Read ENV Value
 284                 value=${!i};
 285
 286                 # Print ENV name/value pair
 287                 if [ -n "${I_KNOW_WHAT_I_AM_DOING}" ]; then
 288                         elog "    $i=\"$value\"";
 289                 else
 290                         eerror "    $i=\"$value\"";
 291                 fi
 292         done
 293
 294         # Return if there were no failures
 295         [ ${errored:-0} == 0 ] && return;
 296
 297         # Return if user knows what they're doing
 298         if [ -n "${I_KNOW_WHAT_I_AM_DOING}" ]; then
 299                 elog "Continuing anyway, seems you know what you're doing."
 300                 return
 301         fi
 302
 303         eerror "Your environment settings may lead to undefined behavior and/or build failures."
 304         die "Please fix your environment ( ~/.bashrc, package.env, ... ), see above for details."
 305 }
 306
 307 # @FUNCTION: perl_doexamples
 308 # @USAGE: <list of files or globs>
 309 # @DESCRIPTION:
 310 # Install example files ready-to-run.
 311 # Is called under certain circumstances in perl-module.eclass src_install
 312 # (see the documentation there).
 313 #
 314 # Example:
 315 # @CODE
 316 # src_install() {
 317 #   perl-module_src_install
 318 #   use examples && perl_doexamples "eg/*"
 319 # }
 320 # @CODE
 321 perl_doexamples() {
 322         debug-print-function $FUNCNAME "$@"
 323
 324         einfo "Installing examples into /usr/share/doc/${PF}/examples"
 325
 326         # no compression since we want ready-to-run scripts
 327         docompress -x /usr/share/doc/${PF}/examples
 328
 329         docinto examples/
 330         # Lack of quoting here is important in order to support glob expansion
 331         # in DIST_EXAMPLES=( ), which is defined before source extraction occurs
 332         dodoc -r $@
 333
 334         # is there a way to undo "docinto" ?
 335 }
 336
 337 # @FUNCTION: perl_has_module
 338 # @USAGE: <module name>
 339 # @RETURN: 0 if available, non-zero otherwise
 340 # @DESCRIPTION:
 341 # Query the installed system Perl to see if a given module is installed.
 342 # This does **not** load the module in question, only anticipates if it *might* load.
 343 #
 344 # This is primarily for the purposes of dependency weakening so that conditional
 345 # behaviour can be triggered without adding dependencies to portage which would confuse
 346 # a dependency resolver.
 347 #
 348 # returns 'true' if the module is available, returns error if the module is not available
 349 #
 350 # Example:
 351 # @CODE
 352 # perl_has_module "Test::Tester" && echo "Test::Tester installed"
 353 # @CODE
 354
 355 perl_has_module() {
 356         debug-print-function $FUNCNAME "$@"
 357
 358         [[ $# -gt 0 ]] || die "${FUNCNAME}: No module name provided"
 359         [[ $# -lt 2 ]] || die "${FUNCNAME}: Too many parameters ($#)"
 360
 361         perl -we 'my $mn = $ARGV[0];
 362                 $mn =~ s{(::|\x{27})}{/}g;
 363                 for(@INC){
 364                         next if ref $_;
 365                         exit 0 if -r $_ . q[/] . $mn . q[.pm]
 366                 }
 367                 exit 1' "$@";
 368 }
 369
 370 # @FUNCTION: perl_has_module_version
 371 # @USAGE: <module name> <minimum upstream version>
 372 # @RETURN: 0 if satisfied, non-zero otherwise
 373 # @DESCRIPTION:
 374 # Query the installed system Perl to see if a given module is installed
 375 # and is at least a given version.
 376 #
 377 # This requires more caution to use than perl_has_module as it requires
 378 # loading the module in question to determine version compatibility,
 379 # which can be SLOW, and can have side effects (ie: compilation fails in
 380 # require due to some dependency, resulting in a "Fail")
 381 #
 382 # Also take care to note the module version is a *minimum*, *must* be
 383 # written in upstream versions format and should be a a legal upstream version
 384 #
 385 # returns a true exit code if the module is both available and is at least
 386 # the specified version
 387 #
 388 # Example:
 389 # @CODE
 390 # perl_has_module_version "Test::Tester" "0.017" \
 391 #       && echo "Test::Tester 0.017 or greater installed"
 392 # @CODE
 393 perl_has_module_version() {
 394         debug-print-function $FUNCNAME "$@"
 395
 396         [[ $# -gt 0 ]] || die "${FUNCNAME}: No module name provided"
 397         [[ $# -gt 1 ]] || die "${FUNCNAME}: No module version provided"
 398         [[ $# -lt 3 ]] || die "${FUNCNAME}: Too many parameters ($#)"
 399
 400         perl -we 'my $mn = $ARGV[0];
 401                 $mn =~ s{(::|\x{27})}{/}g;
 402                 exit ( eval {
 403                         require qq[${mn}.pm];
 404                         $ARGV[0]->VERSION($ARGV[1]);
 405                         1
 406                 } ? 0 : 1 )' "$@"
 407 }
 408
 409 # @FUNCTION: perl_get_module_version
 410 # @USAGE: <module name>
 411 # @RETURN: 0 if module available, non-zero if error
 412 # @DESCRIPTION:
 413 # Query the installed system perl to report the version of the installed
 414 # module.
 415 #
 416 # Note this should be strictly for diagnostic purposes to the end user,
 417 # and may be of selective use in pkg_info to enhance
 418 # emerge --info reports.
 419 #
 420 # Anything that does version comparisons **must not** use the return value
 421 # from this function
 422 #
 423 # Also note that this **must** at least attempt load the module in
 424 # question as part of its operation, and is subsequently prone to SLOWness.
 425 #
 426 # Return codes return error in both compilation-failure and not-installed cases.
 427 #
 428 # Example:
 429 # @CODE
 430 # MODVER=$(perl_get_module_version "Test::Simple") \
 431 #       || die "Test::Simple not installed: $MODVER"
 432 # @CODE
 433
 434 perl_get_module_version() {
 435         debug-print-function $FUNCNAME "$@"
 436
 437         [[ $# -gt 0 ]] || die "${FUNCNAME}: No module name provided"
 438         [[ $# -lt 2 ]] || die "${FUNCNAME}: Too many parameters ($#)"
 439
 440         if ! perl_has_module "$@" ; then
 441                 echo "(Not Installed)";
 442                 return 1;
 443         fi
 444
 445         # Todo: What do we do if require fails? spew to stderr
 446         # or stay silent?
 447
 448         perl -we 'my $mn = $ARGV[0];
 449                 $mn =~ s{(::|\x{27})}{/}g;
 450                 local $@;
 451                 eval { require qq[${mn}.pm]; 1 } or do {
 452                         print q[(Compilation failed in require)];
 453                         exit 1;
 454                 };
 455                 my $stash = \%{ $ARGV[0] . q[::] };
 456                 if ( not exists $stash->{VERSION} ) {
 457                         print q[(No VERSION property)];
 458                         exit 0;
 459                 }
 460                 if ( not defined ${$stash->{VERSION}} ) {
 461                         print q[(undef)];
 462                         exit 0;
 463                 }
 464                 print ${$stash->{VERSION}};
 465                 exit 0; ' "$@"
 466 }
 467
 468 # @FUNCTION: perl_get_raw_vendorlib
 469 # @DESCRIPTION:
 470 # Convenience function to optimise for a common case without double-handling
 471 # variables everywhere.
 472 #
 473 # Note: Will include EPREFIX where relevant
 474 #
 475 # Example:
 476 # @CODE
 477 # my_raw_vendorlib="$(perl_get_raw_vendorlib)"
 478 # @CODE
 479
 480 perl_get_raw_vendorlib() {
 481         debug-print-function $FUNCNAME "$@"
 482
 483         [[ $# -lt 1 ]] || die "${FUNCNAME}: Too many parameters ($#)"
 484
 485         perl -MConfig \
 486                 -e'exists $Config{$ARGV[0]} || die qq{No such Config key "$ARGV[0]"};
 487                    print $Config{$ARGV[0]};
 488                    exit 0' -- "installvendorlib" || die "Can't extract installvendorlib from Perl Configuration"
 489 }
 490
 491 # @FUNCTION: perl_get_vendorlib
 492 # @DESCRIPTION:
 493 # Convenience helper for returning Perls' vendor install root
 494 # without EPREFIXing.
 495 #
 496 # Example:
 497 # @CODE
 498 # my_vendorlib="$(perl_get_vendorlib)"
 499 # @CODE
 500
 501 perl_get_vendorlib() {
 502         debug-print-function $FUNCNAME "$@"
 503
 504         [[ $# -lt 1 ]] || die "${FUNCNAME}: Too many parameters ($#)"
 505
 506         # Requires perl 5.14 for /r attribute of s///
 507         # Just in case somebody out there is stuck in a time warp: upgrade perl first
 508         perl -M5.014 -MConfig \
 509                 -e'exists $Config{$ARGV[0]} || die qq{No such Config key "$ARGV[0]"};
 510                    print $Config{$ARGV[0]} =~ s{\A\Q$ARGV[1]\E}{}r;
 511                    exit 0' -- "installvendorlib" "$EPREFIX" || die "Can't extract installvendorlib from Perl Configuration"
 512 }
 513
 514 # @FUNCTION: perl_domodule
 515 # @USAGE: [-C <target>] [-r] <files>
 516 # @DESCRIPTION:
 517 # Installs files in paths where they can be found in the default
 518 # Perl runtime.
 519 #
 520 # Note: Should only be used in src_install or pkg_preinst
 521 # anywhere else will do the wrong thing or die.
 522 #
 523 # The contents of the <files> list are copied into Perls Vendor library path
 524 # as follows:
 525 # @CODE
 526 #   # install perl/File.pm as Samba::File
 527 #   pushd perl/
 528 #   perl_domodule -C Samba File.pm
 529 #
 530 #   # install perl/ recursively under VENDORLIB/Samba/
 531 #   pushd perl/
 532 #   perl_domodule -C Samba -r .
 533 # @CODE
 534 #
 535 # @CODE
 536 #   options:
 537 #       -C Target/Name
 538 #          The subdirectory relative to the Perl VENDOR_LIB
 539 #          to install into.
 540 #
 541 #          defaults to ""
 542 #       -r
 543 #          Install directories recursively ( see doins )
 544 #          files:
 545 #          list of .pm files to install to VENDORLIB
 546 # @CODE
 547
 548 perl_domodule() {
 549         local target_prefix=""
 550         local files=()
 551         local doins_opts=()
 552
 553         local recursive="false"
 554         local target
 555         local file
 556
 557         while [[ $# -gt 0 ]] ; do
 558                 case $1 in
 559                         -C|--target-prefix)
 560                                 [[ -z "${2}" || "${2:0:1}" == "-" ]] && die "${FUNCNAME}: -C|--target-prefix expects an argument, got \"$2\"!"
 561                                 target_prefix="${2}";
 562                                 shift 2;;
 563                         -r)
 564                                 recursive="true"
 565                                 shift;;
 566                         *)
 567                                 [[ -z "${1}" || "${1:0:1}" == "-" ]] && die "${FUNCNAME}: Unknown argument \"${1}\"!"
 568                                 files+=( "${1}" )
 569                                 shift 1;;
 570                 esac
 571         done
 572
 573         if [[ "true" == $recursive ]]; then
 574                 doins_opts+=( "-r" )
 575         fi
 576         for file in "${files[@]}"; do
 577                 [[ -e "${file}" ]] || die "$FUNCNAME: Argument \"${file}\" is not an existing file"
 578                 [[ "false" == ${recursive} && -d "${file}" ]] && die "$FUNCNAME: Argument \"${file}\" is a directory ( needs -r parameter )"
 579         done
 580
 581         target="$(perl_get_vendorlib)"
 582
 583         # Extend target if target_prefix is set
 584         [[ -z "${target_prefix}" ]] || target="${target%/}/${target_prefix#/}"
 585
 586         insinto "/${target#/}"
 587         doins "${doins_opts[@]}" "${files[@]}"
 588 }