eclass/python-r1.eclass

   1 # Copyright 1999-2018 Gentoo Foundation
   2 # Distributed under the terms of the GNU General Public License v2
   3
   4 # @ECLASS: python-r1.eclass
   5 # @MAINTAINER:
   6 # Python team <python@gentoo.org>
   7 # @AUTHOR:
   8 # Author: Michał Górny <mgorny@gentoo.org>
   9 # Based on work of: Krzysztof Pawlik <nelchael@gentoo.org>
  10 # @BLURB: A common, simple eclass for Python packages.
  11 # @DESCRIPTION:
  12 # A common eclass providing helper functions to build and install
  13 # packages supporting being installed for multiple Python
  14 # implementations.
  15 #
  16 # This eclass sets correct IUSE. Modification of REQUIRED_USE has to
  17 # be done by the author of the ebuild (but PYTHON_REQUIRED_USE is
  18 # provided for convenience, see below). python-r1 exports PYTHON_DEPS
  19 # and PYTHON_USEDEP so you can create correct dependencies for your
  20 # package easily. It also provides methods to easily run a command for
  21 # each enabled Python implementation and duplicate the sources for them.
  22 #
  23 # Please note that python-r1 will always inherit python-utils-r1 as
  24 # well. Thus, all the functions defined there can be used
  25 # in the packages using python-r1, and there is no need ever to inherit
  26 # both.
  27 #
  28 # For more information, please see the wiki:
  29 # https://wiki.gentoo.org/wiki/Project:Python/python-r1
  30
  31 case "${EAPI:-0}" in
  32         0|1|2|3|4)
  33                 die "Unsupported EAPI=${EAPI:-0} (too old) for ${ECLASS}"
  34                 ;;
  35         5|6|7)
  36                 # EAPI=5 is required for sane USE_EXPAND dependencies
  37                 ;;
  38         *)
  39                 die "Unsupported EAPI=${EAPI} (unknown) for ${ECLASS}"
  40                 ;;
  41 esac
  42
  43 if [[ ! ${_PYTHON_R1} ]]; then
  44
  45 if [[ ${_PYTHON_SINGLE_R1} ]]; then
  46         die 'python-r1.eclass can not be used with python-single-r1.eclass.'
  47 elif [[ ${_PYTHON_ANY_R1} ]]; then
  48         die 'python-r1.eclass can not be used with python-any-r1.eclass.'
  49 fi
  50
  51 [[ ${EAPI} == [45] ]] && inherit eutils
  52 inherit multibuild python-utils-r1
  53
  54 fi
  55
  56 # @ECLASS-VARIABLE: PYTHON_COMPAT
  57 # @REQUIRED
  58 # @DESCRIPTION:
  59 # This variable contains a list of Python implementations the package
  60 # supports. It must be set before the `inherit' call. It has to be
  61 # an array.
  62 #
  63 # Example:
  64 # @CODE
  65 # PYTHON_COMPAT=( python2_7 python3_3 python3_4 )
  66 # @CODE
  67 #
  68 # Please note that you can also use bash brace expansion if you like:
  69 # @CODE
  70 # PYTHON_COMPAT=( python2_7 python3_{3,4} )
  71 # @CODE
  72
  73 # @ECLASS-VARIABLE: PYTHON_COMPAT_OVERRIDE
  74 # @INTERNAL
  75 # @DESCRIPTION:
  76 # This variable can be used when working with ebuilds to override
  77 # the in-ebuild PYTHON_COMPAT. It is a string listing all
  78 # the implementations which package will be built for. It need be
  79 # specified in the calling environment, and not in ebuilds.
  80 #
  81 # It should be noted that in order to preserve metadata immutability,
  82 # PYTHON_COMPAT_OVERRIDE does not affect IUSE nor dependencies.
  83 # The state of PYTHON_TARGETS is ignored, and all the implementations
  84 # in PYTHON_COMPAT_OVERRIDE are built. Dependencies need to be satisfied
  85 # manually.
  86 #
  87 # Example:
  88 # @CODE
  89 # PYTHON_COMPAT_OVERRIDE='pypy python3_3' emerge -1v dev-python/foo
  90 # @CODE
  91
  92 # @ECLASS-VARIABLE: PYTHON_REQ_USE
  93 # @DEFAULT_UNSET
  94 # @DESCRIPTION:
  95 # The list of USEflags required to be enabled on the chosen Python
  96 # implementations, formed as a USE-dependency string. It should be valid
  97 # for all implementations in PYTHON_COMPAT, so it may be necessary to
  98 # use USE defaults.
  99 #
 100 # This should be set before calling `inherit'.
 101 #
 102 # Example:
 103 # @CODE
 104 # PYTHON_REQ_USE="gdbm,ncurses(-)?"
 105 # @CODE
 106 #
 107 # It will cause the Python dependencies to look like:
 108 # @CODE
 109 # python_targets_pythonX_Y? ( dev-lang/python:X.Y[gdbm,ncurses(-)?] )
 110 # @CODE
 111
 112 # @ECLASS-VARIABLE: PYTHON_DEPS
 113 # @DESCRIPTION:
 114 # This is an eclass-generated Python dependency string for all
 115 # implementations listed in PYTHON_COMPAT.
 116 #
 117 # Example use:
 118 # @CODE
 119 # RDEPEND="${PYTHON_DEPS}
 120 #       dev-foo/mydep"
 121 # DEPEND="${RDEPEND}"
 122 # @CODE
 123 #
 124 # Example value:
 125 # @CODE
 126 # dev-lang/python-exec:=
 127 # python_targets_python2_7? ( dev-lang/python:2.7[gdbm] )
 128 # python_targets_pypy? ( virtual/pypy[gdbm] )
 129 # @CODE
 130
 131 # @ECLASS-VARIABLE: PYTHON_USEDEP
 132 # @DESCRIPTION:
 133 # This is an eclass-generated USE-dependency string which can be used to
 134 # depend on another Python package being built for the same Python
 135 # implementations.
 136 #
 137 # The generate USE-flag list is compatible with packages using python-r1
 138 # and python-distutils-ng eclasses. It must not be used on packages
 139 # using python.eclass.
 140 #
 141 # Example use:
 142 # @CODE
 143 # RDEPEND="dev-python/foo[${PYTHON_USEDEP}]"
 144 # @CODE
 145 #
 146 # Example value:
 147 # @CODE
 148 # python_targets_python2_7(-)?,python_targets_python3_4(-)?
 149 # @CODE
 150
 151 # @ECLASS-VARIABLE: PYTHON_REQUIRED_USE
 152 # @DESCRIPTION:
 153 # This is an eclass-generated required-use expression which ensures at
 154 # least one Python implementation has been enabled.
 155 #
 156 # This expression should be utilized in an ebuild by including it in
 157 # REQUIRED_USE, optionally behind a use flag.
 158 #
 159 # Example use:
 160 # @CODE
 161 # REQUIRED_USE="python? ( ${PYTHON_REQUIRED_USE} )"
 162 # @CODE
 163 #
 164 # Example value:
 165 # @CODE
 166 # || ( python_targets_python2_7 python_targets_python3_4 )
 167 # @CODE
 168
 169 _python_set_globals() {
 170         local deps i PYTHON_PKG_DEP
 171
 172         _python_set_impls
 173
 174         for i in "${_PYTHON_SUPPORTED_IMPLS[@]}"; do
 175                 python_export "${i}" PYTHON_PKG_DEP
 176                 deps+="python_targets_${i}? ( ${PYTHON_PKG_DEP} ) "
 177         done
 178
 179         local flags=( "${_PYTHON_SUPPORTED_IMPLS[@]/#/python_targets_}" )
 180         local optflags=${flags[@]/%/(-)?}
 181
 182         # A nice QA trick here. Since a python-single-r1 package has to have
 183         # at least one PYTHON_SINGLE_TARGET enabled (REQUIRED_USE),
 184         # the following check will always fail on those packages. Therefore,
 185         # it should prevent developers from mistakenly depending on packages
 186         # not supporting multiple Python implementations.
 187
 188         local flags_st=( "${_PYTHON_SUPPORTED_IMPLS[@]/#/-python_single_target_}" )
 189         optflags+=,${flags_st[@]/%/(-)}
 190         local requse="|| ( ${flags[*]} )"
 191         local usedep=${optflags// /,}
 192
 193         # 1) well, python-exec would suffice as an RDEP
 194         # but no point in making this overcomplex, BDEP doesn't hurt anyone
 195         # 2) python-exec should be built with all targets forced anyway
 196         # but if new targets were added, we may need to force a rebuild
 197         if [[ ${_PYTHON_WANT_PYTHON_EXEC2} == 0 ]]; then
 198                 die "python-exec:0 is no longer supported, please fix your ebuild to work with python-exec:2"
 199         else
 200                 deps+=">=dev-lang/python-exec-2:=[${usedep}]"
 201         fi
 202
 203         if [[ ${PYTHON_DEPS+1} ]]; then
 204                 # IUSE is magical, so we can't really check it
 205                 # (but we verify PYTHON_COMPAT already)
 206
 207                 if [[ ${PYTHON_DEPS} != "${deps}" ]]; then
 208                         eerror "PYTHON_DEPS have changed between inherits (PYTHON_REQ_USE?)!"
 209                         eerror "Before: ${PYTHON_DEPS}"
 210                         eerror "Now   : ${deps}"
 211                         die "PYTHON_DEPS integrity check failed"
 212                 fi
 213
 214                 # these two are formality -- they depend on PYTHON_COMPAT only
 215                 if [[ ${PYTHON_REQUIRED_USE} != ${requse} ]]; then
 216                         eerror "PYTHON_REQUIRED_USE have changed between inherits!"
 217                         eerror "Before: ${PYTHON_REQUIRED_USE}"
 218                         eerror "Now   : ${requse}"
 219                         die "PYTHON_REQUIRED_USE integrity check failed"
 220                 fi
 221
 222                 if [[ ${PYTHON_USEDEP} != "${usedep}" ]]; then
 223                         eerror "PYTHON_USEDEP have changed between inherits!"
 224                         eerror "Before: ${PYTHON_USEDEP}"
 225                         eerror "Now   : ${usedep}"
 226                         die "PYTHON_USEDEP integrity check failed"
 227                 fi
 228         else
 229                 IUSE=${flags[*]}
 230
 231                 PYTHON_DEPS=${deps}
 232                 PYTHON_REQUIRED_USE=${requse}
 233                 PYTHON_USEDEP=${usedep}
 234                 readonly PYTHON_DEPS PYTHON_REQUIRED_USE
 235         fi
 236 }
 237 _python_set_globals
 238 unset -f _python_set_globals
 239
 240 if [[ ! ${_PYTHON_R1} ]]; then
 241
 242 # @FUNCTION: _python_validate_useflags
 243 # @INTERNAL
 244 # @DESCRIPTION:
 245 # Enforce the proper setting of PYTHON_TARGETS, if PYTHON_COMPAT_OVERRIDE
 246 # is not in effect. If it is, just warn that the flags will be ignored.
 247 _python_validate_useflags() {
 248         debug-print-function ${FUNCNAME} "${@}"
 249
 250         if [[ ${PYTHON_COMPAT_OVERRIDE} ]]; then
 251                 if [[ ! ${_PYTHON_COMPAT_OVERRIDE_WARNED} ]]; then
 252                         ewarn "WARNING: PYTHON_COMPAT_OVERRIDE in effect. The following Python"
 253                         ewarn "implementations will be enabled:"
 254                         ewarn
 255                         ewarn " ${PYTHON_COMPAT_OVERRIDE}"
 256                         ewarn
 257                         ewarn "Dependencies won't be satisfied, and PYTHON_TARGETS will be ignored."
 258                         _PYTHON_COMPAT_OVERRIDE_WARNED=1
 259                 fi
 260                 # we do not use flags with PCO
 261                 return
 262         fi
 263
 264         local i
 265
 266         for i in "${_PYTHON_SUPPORTED_IMPLS[@]}"; do
 267                 use "python_targets_${i}" && return 0
 268         done
 269
 270         eerror "No Python implementation selected for the build. Please add one"
 271         eerror "of the following values to your PYTHON_TARGETS (in make.conf):"
 272         eerror
 273         eerror "${PYTHON_COMPAT[@]}"
 274         echo
 275         die "No supported Python implementation in PYTHON_TARGETS."
 276 }
 277
 278 # @FUNCTION: python_gen_usedep
 279 # @USAGE: <pattern> [...]
 280 # @DESCRIPTION:
 281 # Output a USE dependency string for Python implementations which
 282 # are both in PYTHON_COMPAT and match any of the patterns passed
 283 # as parameters to the function.
 284 #
 285 # The patterns can be either fnmatch-style patterns (matched via bash
 286 # == operator against PYTHON_COMPAT values) or '-2' / '-3' to indicate
 287 # appropriately all enabled Python 2/3 implementations (alike
 288 # python_is_python3). Remember to escape or quote the fnmatch patterns
 289 # to prevent accidental shell filename expansion.
 290 #
 291 # When all implementations are requested, please use ${PYTHON_USEDEP}
 292 # instead. Please also remember to set an appropriate REQUIRED_USE
 293 # to avoid ineffective USE flags.
 294 #
 295 # Example:
 296 # @CODE
 297 # PYTHON_COMPAT=( python{2_7,3_4} )
 298 # DEPEND="doc? ( dev-python/epydoc[$(python_gen_usedep 'python2*')] )"
 299 # @CODE
 300 #
 301 # It will cause the dependency to look like:
 302 # @CODE
 303 # DEPEND="doc? ( dev-python/epydoc[python_targets_python2_7?] )"
 304 # @CODE
 305 python_gen_usedep() {
 306         debug-print-function ${FUNCNAME} "${@}"
 307
 308         local impl matches=()
 309
 310         for impl in "${_PYTHON_SUPPORTED_IMPLS[@]}"; do
 311                 if _python_impl_matches "${impl}" "${@}"; then
 312                         matches+=(
 313                                 "python_targets_${impl}(-)?"
 314                                 "-python_single_target_${impl}(-)"
 315                         )
 316                 fi
 317         done
 318
 319         [[ ${matches[@]} ]] || die "No supported implementations match python_gen_usedep patterns: ${@}"
 320
 321         local out=${matches[@]}
 322         echo "${out// /,}"
 323 }
 324
 325 # @FUNCTION: python_gen_useflags
 326 # @USAGE: <pattern> [...]
 327 # @DESCRIPTION:
 328 # Output a list of USE flags for Python implementations which
 329 # are both in PYTHON_COMPAT and match any of the patterns passed
 330 # as parameters to the function.
 331 #
 332 # The patterns can be either fnmatch-style patterns (matched via bash
 333 # == operator against PYTHON_COMPAT values) or '-2' / '-3' to indicate
 334 # appropriately all enabled Python 2/3 implementations (alike
 335 # python_is_python3). Remember to escape or quote the fnmatch patterns
 336 # to prevent accidental shell filename expansion.
 337 #
 338 # Example:
 339 # @CODE
 340 # PYTHON_COMPAT=( python{2_7,3_4} )
 341 # REQUIRED_USE="doc? ( || ( $(python_gen_useflags python2*) ) )"
 342 # @CODE
 343 #
 344 # It will cause the variable to look like:
 345 # @CODE
 346 # REQUIRED_USE="doc? ( || ( python_targets_python2_7 ) )"
 347 # @CODE
 348 python_gen_useflags() {
 349         debug-print-function ${FUNCNAME} "${@}"
 350
 351         local impl matches=()
 352
 353         for impl in "${_PYTHON_SUPPORTED_IMPLS[@]}"; do
 354                 if _python_impl_matches "${impl}" "${@}"; then
 355                         matches+=( "python_targets_${impl}" )
 356                 fi
 357         done
 358
 359         echo "${matches[@]}"
 360 }
 361
 362 # @FUNCTION: python_gen_cond_dep
 363 # @USAGE: <dependency> <pattern> [...]
 364 # @DESCRIPTION:
 365 # Output a list of <dependency>-ies made conditional to USE flags
 366 # of Python implementations which are both in PYTHON_COMPAT and match
 367 # any of the patterns passed as the remaining parameters.
 368 #
 369 # The patterns can be either fnmatch-style patterns (matched via bash
 370 # == operator against PYTHON_COMPAT values) or '-2' / '-3' to indicate
 371 # appropriately all enabled Python 2/3 implementations (alike
 372 # python_is_python3). Remember to escape or quote the fnmatch patterns
 373 # to prevent accidental shell filename expansion.
 374 #
 375 # In order to enforce USE constraints on the packages, verbatim
 376 # '${PYTHON_USEDEP}' (quoted!) may be placed in the dependency
 377 # specification. It will get expanded within the function into a proper
 378 # USE dependency string.
 379 #
 380 # Example:
 381 # @CODE
 382 # PYTHON_COMPAT=( python{2_7,3_{3,4}} pypy )
 383 # RDEPEND="$(python_gen_cond_dep \
 384 #   'dev-python/unittest2[${PYTHON_USEDEP}]' python2_7 pypy )"
 385 # @CODE
 386 #
 387 # It will cause the variable to look like:
 388 # @CODE
 389 # RDEPEND="python_targets_python2_7? (
 390 #     dev-python/unittest2[python_targets_python2_7?] )
 391 #       python_targets_pypy? (
 392 #     dev-python/unittest2[python_targets_pypy?] )"
 393 # @CODE
 394 python_gen_cond_dep() {
 395         debug-print-function ${FUNCNAME} "${@}"
 396
 397         local impl matches=()
 398         local dep=${1}
 399         shift
 400
 401         for impl in "${_PYTHON_SUPPORTED_IMPLS[@]}"; do
 402                 if _python_impl_matches "${impl}" "${@}"; then
 403                         # substitute ${PYTHON_USEDEP} if used
 404                         # (since python_gen_usedep() will not return ${PYTHON_USEDEP}
 405                         #  the code is run at most once)
 406                         if [[ ${dep} == *'${PYTHON_USEDEP}'* ]]; then
 407                                 local usedep=$(python_gen_usedep "${@}")
 408                                 dep=${dep//\$\{PYTHON_USEDEP\}/${usedep}}
 409                         fi
 410
 411                         matches+=( "python_targets_${impl}? ( ${dep} )" )
 412                 fi
 413         done
 414
 415         echo "${matches[@]}"
 416 }
 417
 418 # @FUNCTION: python_gen_impl_dep
 419 # @USAGE: [<requested-use-flags> [<impl-pattern>...]]
 420 # @DESCRIPTION:
 421 # Output a dependency on Python implementations with the specified USE
 422 # dependency string appended, or no USE dependency string if called
 423 # without the argument (or with empty argument). If any implementation
 424 # patterns are passed, the output dependencies will be generated only
 425 # for the implementations matching them.
 426 #
 427 # The patterns can be either fnmatch-style patterns (matched via bash
 428 # == operator against PYTHON_COMPAT values) or '-2' / '-3' to indicate
 429 # appropriately all enabled Python 2/3 implementations (alike
 430 # python_is_python3). Remember to escape or quote the fnmatch patterns
 431 # to prevent accidental shell filename expansion.
 432 #
 433 # Use this function when you need to request different USE flags
 434 # on the Python interpreter depending on package's USE flags. If you
 435 # only need a single set of interpreter USE flags, just set
 436 # PYTHON_REQ_USE and use ${PYTHON_DEPS} globally.
 437 #
 438 # Example:
 439 # @CODE
 440 # PYTHON_COMPAT=( python{2_7,3_{3,4}} pypy )
 441 # RDEPEND="foo? ( $(python_gen_impl_dep 'xml(+)') )"
 442 # @CODE
 443 #
 444 # It will cause the variable to look like:
 445 # @CODE
 446 # RDEPEND="foo? (
 447 #   python_targets_python2_7? (
 448 #     dev-lang/python:2.7[xml(+)] )
 449 #       python_targets_pypy? (
 450 #     dev-python/pypy[xml(+)] ) )"
 451 # @CODE
 452 python_gen_impl_dep() {
 453         debug-print-function ${FUNCNAME} "${@}"
 454
 455         local impl matches=()
 456         local PYTHON_REQ_USE=${1}
 457         shift
 458
 459         local patterns=( "${@-*}" )
 460         for impl in "${_PYTHON_SUPPORTED_IMPLS[@]}"; do
 461                 if _python_impl_matches "${impl}" "${patterns[@]}"; then
 462                         local PYTHON_PKG_DEP
 463                         python_export "${impl}" PYTHON_PKG_DEP
 464                         matches+=( "python_targets_${impl}? ( ${PYTHON_PKG_DEP} )" )
 465                 fi
 466         done
 467
 468         echo "${matches[@]}"
 469 }
 470
 471 # @FUNCTION: python_gen_any_dep
 472 # @USAGE: <dependency-block> [<impl-pattern>...]
 473 # @DESCRIPTION:
 474 # Generate an any-of dependency that enforces a version match between
 475 # the Python interpreter and Python packages. <dependency-block> needs
 476 # to list one or more dependencies with verbatim '${PYTHON_USEDEP}'
 477 # references (quoted!) that will get expanded inside the function.
 478 # Optionally, patterns may be specified to restrict the dependency
 479 # to a subset of Python implementations supported by the ebuild.
 480 #
 481 # The patterns can be either fnmatch-style patterns (matched via bash
 482 # == operator against PYTHON_COMPAT values) or '-2' / '-3' to indicate
 483 # appropriately all enabled Python 2/3 implementations (alike
 484 # python_is_python3). Remember to escape or quote the fnmatch patterns
 485 # to prevent accidental shell filename expansion.
 486 #
 487 # This should be used along with an appropriate python_check_deps()
 488 # that checks which of the any-of blocks were matched, and python_setup
 489 # call that enables use of the matched implementation.
 490 #
 491 # Example use:
 492 # @CODE
 493 # DEPEND="$(python_gen_any_dep '
 494 #       dev-python/foo[${PYTHON_USEDEP}]
 495 #       || ( dev-python/bar[${PYTHON_USEDEP}]
 496 #               dev-python/baz[${PYTHON_USEDEP}] )' -2)"
 497 #
 498 # python_check_deps() {
 499 #       has_version "dev-python/foo[${PYTHON_USEDEP}]" \
 500 #               && { has_version "dev-python/bar[${PYTHON_USEDEP}]" \
 501 #                       || has_version "dev-python/baz[${PYTHON_USEDEP}]"; }
 502 # }
 503 #
 504 # src_compile() {
 505 #       python_foreach_impl usual_code
 506 #
 507 #       # some common post-build task that requires Python 2
 508 #       python_setup -2
 509 #       emake frobnicate
 510 # }
 511 # @CODE
 512 #
 513 # Example value:
 514 # @CODE
 515 # || (
 516 #       (
 517 #               dev-lang/python:2.7
 518 #               dev-python/foo[python_targets_python2_7(-)?,python_single_target_python2_7(+)?]
 519 #               || ( dev-python/bar[python_targets_python2_7(-)?,python_single_target_python2_7(+)?]
 520 #                       dev-python/baz[python_targets_python2_7(-)?,python_single_target_python2_7(+)?] )
 521 #       )
 522 #       (
 523 #               dev-lang/python:3.3
 524 #               dev-python/foo[python_targets_python3_3(-)?,python_single_target_python3_3(+)?]
 525 #               || ( dev-python/bar[python_targets_python3_3(-)?,python_single_target_python3_3(+)?]
 526 #                       dev-python/baz[python_targets_python3_3(-)?,python_single_target_python3_3(+)?] )
 527 #       )
 528 # )
 529 # @CODE
 530 python_gen_any_dep() {
 531         debug-print-function ${FUNCNAME} "${@}"
 532
 533         local depstr=${1}
 534         [[ ${depstr} ]] || die "No dependency string provided"
 535         shift
 536
 537         local i PYTHON_PKG_DEP out=
 538         for i in "${_PYTHON_SUPPORTED_IMPLS[@]}"; do
 539                 if _python_impl_matches "${i}" "${@-*}"; then
 540                         local PYTHON_USEDEP="python_targets_${i}(-),python_single_target_${i}(+)"
 541                         python_export "${i}" PYTHON_PKG_DEP
 542
 543                         local i_depstr=${depstr//\$\{PYTHON_USEDEP\}/${PYTHON_USEDEP}}
 544                         # note: need to strip '=' slot operator for || deps
 545                         out="( ${PYTHON_PKG_DEP%=} ${i_depstr} ) ${out}"
 546                 fi
 547         done
 548         echo "|| ( ${out})"
 549 }
 550
 551 # @ECLASS-VARIABLE: BUILD_DIR
 552 # @DESCRIPTION:
 553 # The current build directory. In global scope, it is supposed to
 554 # contain an initial build directory; if unset, it defaults to ${S}.
 555 #
 556 # In functions run by python_foreach_impl(), the BUILD_DIR is locally
 557 # set to an implementation-specific build directory. That path is
 558 # created through appending a hyphen and the implementation name
 559 # to the final component of the initial BUILD_DIR.
 560 #
 561 # Example value:
 562 # @CODE
 563 # ${WORKDIR}/foo-1.3-python2_7
 564 # @CODE
 565
 566 # @FUNCTION: python_copy_sources
 567 # @DESCRIPTION:
 568 # Create a single copy of the package sources for each enabled Python
 569 # implementation.
 570 #
 571 # The sources are always copied from initial BUILD_DIR (or S if unset)
 572 # to implementation-specific build directory matching BUILD_DIR used by
 573 # python_foreach_abi().
 574 python_copy_sources() {
 575         debug-print-function ${FUNCNAME} "${@}"
 576
 577         local MULTIBUILD_VARIANTS
 578         _python_obtain_impls
 579
 580         multibuild_copy_sources
 581 }
 582
 583 # @FUNCTION: _python_obtain_impls
 584 # @INTERNAL
 585 # @DESCRIPTION:
 586 # Set up the enabled implementation list.
 587 _python_obtain_impls() {
 588         _python_validate_useflags
 589
 590         if [[ ${PYTHON_COMPAT_OVERRIDE} ]]; then
 591                 MULTIBUILD_VARIANTS=( ${PYTHON_COMPAT_OVERRIDE} )
 592                 return
 593         fi
 594
 595         MULTIBUILD_VARIANTS=()
 596
 597         local impl
 598         for impl in "${_PYTHON_SUPPORTED_IMPLS[@]}"; do
 599                 has "${impl}" "${PYTHON_COMPAT[@]}" && \
 600                 use "python_targets_${impl}" && MULTIBUILD_VARIANTS+=( "${impl}" )
 601         done
 602 }
 603
 604 # @FUNCTION: _python_multibuild_wrapper
 605 # @USAGE: <command> [<args>...]
 606 # @INTERNAL
 607 # @DESCRIPTION:
 608 # Initialize the environment for Python implementation selected
 609 # for multibuild.
 610 _python_multibuild_wrapper() {
 611         debug-print-function ${FUNCNAME} "${@}"
 612
 613         local -x EPYTHON PYTHON
 614         local -x PATH=${PATH} PKG_CONFIG_PATH=${PKG_CONFIG_PATH}
 615         python_export "${MULTIBUILD_VARIANT}" EPYTHON PYTHON
 616         python_wrapper_setup
 617
 618         "${@}"
 619 }
 620
 621 # @FUNCTION: python_foreach_impl
 622 # @USAGE: <command> [<args>...]
 623 # @DESCRIPTION:
 624 # Run the given command for each of the enabled Python implementations.
 625 # If additional parameters are passed, they will be passed through
 626 # to the command.
 627 #
 628 # The function will return 0 status if all invocations succeed.
 629 # Otherwise, the return code from first failing invocation will
 630 # be returned.
 631 #
 632 # For each command being run, EPYTHON, PYTHON and BUILD_DIR are set
 633 # locally, and the former two are exported to the command environment.
 634 python_foreach_impl() {
 635         debug-print-function ${FUNCNAME} "${@}"
 636
 637         local MULTIBUILD_VARIANTS
 638         _python_obtain_impls
 639
 640         multibuild_foreach_variant _python_multibuild_wrapper "${@}"
 641 }
 642
 643 # @FUNCTION: python_setup
 644 # @USAGE: [<impl-pattern>...]
 645 # @DESCRIPTION:
 646 # Find the best (most preferred) Python implementation that is suitable
 647 # for running common Python code. Set the Python build environment up
 648 # for that implementation. This function has two modes of operation:
 649 # pure and any-of dep.
 650 #
 651 # The pure mode is used if python_check_deps() function is not declared.
 652 # In this case, an implementation is considered suitable if it is
 653 # supported (in PYTHON_COMPAT), enabled (via USE flags) and matches
 654 # at least one of the patterns passed (or '*' if no patterns passed).
 655 #
 656 # Implementation restrictions in the pure mode need to be accompanied
 657 # by appropriate REQUIRED_USE constraints. Otherwise, the eclass may
 658 # fail at build time due to unsatisfied dependencies.
 659 #
 660 # The any-of dep mode is used if python_check_deps() is declared.
 661 # In this mode, an implementation is considered suitable if it is
 662 # supported, matches at least one of the patterns and python_check_deps()
 663 # has successful return code. USE flags are not considered.
 664 #
 665 # The python_check_deps() function in the any-of mode needs to be
 666 # accompanied by appropriate any-of dependencies.
 667 #
 668 # The patterns can be either fnmatch-style patterns (matched via bash
 669 # == operator against PYTHON_COMPAT values) or '-2' / '-3' to indicate
 670 # appropriately all enabled Python 2/3 implementations (alike
 671 # python_is_python3). Remember to escape or quote the fnmatch patterns
 672 # to prevent accidental shell filename expansion.
 673 #
 674 # This function needs to be used when Python is being called outside
 675 # of python_foreach_impl calls (e.g. for shared processes like doc
 676 # building). python_foreach_impl sets up the build environment itself.
 677 #
 678 # Pure mode example:
 679 # @CODE
 680 # DEPEND="doc? ( dev-python/epydoc[$(python_gen_usedep 'python2*')] )"
 681 # REQUIRED_USE="doc? ( $(python_gen_useflags 'python2*') )"
 682 #
 683 # src_compile() {
 684 #   #...
 685 #   if use doc; then
 686 #     python_setup 'python2*'
 687 #     make doc
 688 #   fi
 689 # }
 690 # @CODE
 691 #
 692 # Any-of mode example:
 693 # @CODE
 694 # DEPEND="doc? (
 695 #       $(python_gen_any_dep 'dev-python/epydoc[${PYTHON_USEDEP}]' 'python2*') )"
 696 #
 697 # python_check_deps() {
 698 #       has_version "dev-python/epydoc[${PYTHON_USEDEP}]"
 699 # }
 700 #
 701 # src_compile() {
 702 #   #...
 703 #   if use doc; then
 704 #     python_setup 'python2*'
 705 #     make doc
 706 #   fi
 707 # }
 708 # @CODE
 709 python_setup() {
 710         debug-print-function ${FUNCNAME} "${@}"
 711
 712         _python_validate_useflags
 713         local pycompat=( "${PYTHON_COMPAT[@]}" )
 714         if [[ ${PYTHON_COMPAT_OVERRIDE} ]]; then
 715                 pycompat=( ${PYTHON_COMPAT_OVERRIDE} )
 716         fi
 717
 718         local has_check_deps
 719         declare -f python_check_deps >/dev/null && has_check_deps=1
 720
 721         # (reverse iteration -- newest impl first)
 722         local found
 723         for (( i = ${#_PYTHON_SUPPORTED_IMPLS[@]} - 1; i >= 0; i-- )); do
 724                 local impl=${_PYTHON_SUPPORTED_IMPLS[i]}
 725
 726                 # check PYTHON_COMPAT[_OVERRIDE]
 727                 has "${impl}" "${pycompat[@]}" || continue
 728
 729                 # match USE flags only if override is not in effect
 730                 # and python_check_deps() is not defined
 731                 if [[ ! ${PYTHON_COMPAT_OVERRIDE} && ! ${has_check_deps} ]]; then
 732                         use "python_targets_${impl}" || continue
 733                 fi
 734
 735                 # check patterns
 736                 _python_impl_matches "${impl}" "${@-*}" || continue
 737
 738                 python_export "${impl}" EPYTHON PYTHON
 739
 740                 # if python_check_deps() is declared, switch into any-of mode
 741                 if [[ ${has_check_deps} ]]; then
 742                         # first check if the interpreter is installed
 743                         python_is_installed "${impl}" || continue
 744                         # then run python_check_deps
 745                         local PYTHON_USEDEP="python_targets_${impl}(-),python_single_target_${impl}(+)"
 746                         python_check_deps || continue
 747                 fi
 748
 749                 found=1
 750                 break
 751         done
 752
 753         if [[ ! ${found} ]]; then
 754                 eerror "${FUNCNAME}: none of the enabled implementation matched the patterns."
 755                 eerror "  patterns: ${@-'(*)'}"
 756                 eerror "Likely a REQUIRED_USE constraint (possibly USE-conditional) is missing."
 757                 eerror "  suggested: || ( \$(python_gen_useflags ${@}) )"
 758                 eerror "(remember to quote all the patterns with '')"
 759                 die "${FUNCNAME}: no enabled implementation satisfy requirements"
 760         fi
 761
 762         python_wrapper_setup
 763 }
 764
 765 # @FUNCTION: python_export_best
 766 # @USAGE: [<variable>...]
 767 # @DESCRIPTION:
 768 # Find the best (most preferred) Python implementation enabled
 769 # and export given variables for it. If no variables are provided,
 770 # EPYTHON & PYTHON will be exported.
 771 python_export_best() {
 772         debug-print-function ${FUNCNAME} "${@}"
 773
 774         [[ ${EAPI} == [45] ]] || die "${FUNCNAME} is banned in EAPI ${EAPI}"
 775
 776         eqawarn "python_export_best() is deprecated. Please use python_setup instead,"
 777         eqawarn "combined with python_export if necessary."
 778
 779         [[ ${#} -gt 0 ]] || set -- EPYTHON PYTHON
 780
 781         local best MULTIBUILD_VARIANTS
 782         _python_obtain_impls
 783
 784         _python_set_best() {
 785                 best=${MULTIBUILD_VARIANT}
 786         }
 787         multibuild_for_best_variant _python_set_best
 788         unset -f _python_set_best
 789
 790         debug-print "${FUNCNAME}: Best implementation is: ${best}"
 791         python_export "${best}" "${@}"
 792         python_wrapper_setup
 793 }
 794
 795 # @FUNCTION: python_replicate_script
 796 # @USAGE: <path>...
 797 # @DESCRIPTION:
 798 # Copy the given script to variants for all enabled Python
 799 # implementations, then replace it with a symlink to the wrapper.
 800 #
 801 # All specified files must start with a 'python' shebang. A file not
 802 # having a matching shebang will be refused.
 803 python_replicate_script() {
 804         debug-print-function ${FUNCNAME} "${@}"
 805
 806         _python_replicate_script() {
 807                 local _PYTHON_FIX_SHEBANG_QUIET=1
 808
 809                 local PYTHON_SCRIPTDIR
 810                 python_export PYTHON_SCRIPTDIR
 811
 812                 (
 813                         exeopts -m 0755
 814                         exeinto "${PYTHON_SCRIPTDIR#${EPREFIX}}"
 815                         doexe "${files[@]}"
 816                 )
 817
 818                 python_fix_shebang -q \
 819                         "${files[@]/*\//${D%/}/${PYTHON_SCRIPTDIR}/}"
 820         }
 821
 822         local files=( "${@}" )
 823         python_foreach_impl _python_replicate_script
 824         unset -f _python_replicate_script
 825
 826         # install the wrappers
 827         local f
 828         for f; do
 829                 _python_ln_rel "${ED%/}/usr/lib/python-exec/python-exec2" "${f}" || die
 830         done
 831 }
 832
 833 _PYTHON_R1=1
 834 fi