eclass/distutils-r1.eclass

   1 # Copyright 1999-2019 Gentoo Authors
   2 # Distributed under the terms of the GNU General Public License v2
   3
   4 # @ECLASS: distutils-r1.eclass
   5 # @MAINTAINER:
   6 # Python team <python@gentoo.org>
   7 # @AUTHOR:
   8 # Author: Michał Górny <mgorny@gentoo.org>
   9 # Based on the work of: Krzysztof Pawlik <nelchael@gentoo.org>
  10 # @SUPPORTED_EAPIS: 5 6 7
  11 # @BLURB: A simple eclass to build Python packages using distutils.
  12 # @DESCRIPTION:
  13 # A simple eclass providing functions to build Python packages using
  14 # the distutils build system. It exports phase functions for all
  15 # the src_* phases. Each of the phases runs two pseudo-phases:
  16 # python_..._all() (e.g. python_prepare_all()) once in ${S}, then
  17 # python_...() (e.g. python_prepare()) for each implementation
  18 # (see: python_foreach_impl() in python-r1).
  19 #
  20 # In distutils-r1_src_prepare(), the 'all' function is run before
  21 # per-implementation ones (because it creates the implementations),
  22 # per-implementation functions are run in a random order.
  23 #
  24 # In remaining phase functions, the per-implementation functions are run
  25 # before the 'all' one, and they are ordered from the least to the most
  26 # preferred implementation (so that 'better' files overwrite 'worse'
  27 # ones).
  28 #
  29 # If the ebuild doesn't specify a particular pseudo-phase function,
  30 # the default one will be used (distutils-r1_...). Defaults are provided
  31 # for all per-implementation pseudo-phases, python_prepare_all()
  32 # and python_install_all(); whenever writing your own pseudo-phase
  33 # functions, you should consider calling the defaults (and especially
  34 # distutils-r1_python_prepare_all).
  35 #
  36 # Please note that distutils-r1 sets RDEPEND and DEPEND unconditionally
  37 # for you.
  38 #
  39 # Also, please note that distutils-r1 will always inherit python-r1
  40 # as well. Thus, all the variables defined and documented there are
  41 # relevant to the packages using distutils-r1.
  42 #
  43 # For more information, please see the wiki:
  44 # https://wiki.gentoo.org/wiki/Project:Python/distutils-r1
  45
  46 case "${EAPI:-0}" in
  47         0|1|2|3|4)
  48                 die "Unsupported EAPI=${EAPI:-0} (too old) for ${ECLASS}"
  49                 ;;
  50         5|6|7)
  51                 ;;
  52         *)
  53                 die "Unsupported EAPI=${EAPI} (unknown) for ${ECLASS}"
  54                 ;;
  55 esac
  56
  57 # @ECLASS-VARIABLE: DISTUTILS_OPTIONAL
  58 # @DEFAULT_UNSET
  59 # @DESCRIPTION:
  60 # If set to a non-null value, distutils part in the ebuild will
  61 # be considered optional. No dependencies will be added and no phase
  62 # functions will be exported.
  63 #
  64 # If you enable DISTUTILS_OPTIONAL, you have to set proper dependencies
  65 # for your package (using ${PYTHON_DEPS}) and to either call
  66 # distutils-r1 default phase functions or call the build system
  67 # manually.
  68
  69 # @ECLASS-VARIABLE: DISTUTILS_SINGLE_IMPL
  70 # @DEFAULT_UNSET
  71 # @DESCRIPTION:
  72 # If set to a non-null value, the ebuild will support setting a single
  73 # Python implementation only. It will effectively replace the python-r1
  74 # eclass inherit with python-single-r1.
  75 #
  76 # Note that inheriting python-single-r1 will cause pkg_setup()
  77 # to be exported. It must be run in order for the eclass functions
  78 # to function properly.
  79
  80 # @ECLASS-VARIABLE: DISTUTILS_USE_SETUPTOOLS
  81 # @PRE_INHERIT
  82 # @DESCRIPTION:
  83 # Controls adding dev-python/setuptools dependency.  The allowed values
  84 # are:
  85 #
  86 # - no -- do not add the dependency (pure distutils package)
  87 # - bdepend -- add it to BDEPEND (the default)
  88 # - rdepend -- add it to BDEPEND+RDEPEND (when using entry_points)
  89 # - manual -- do not add the depedency and suppress the checks
  90 #             (assumes you will take care of doing it correctly)
  91 #
  92 # This variable is effective only if DISTUTILS_OPTIONAL is disabled.
  93 # It needs to be set before the inherit line.
  94 : ${DISTUTILS_USE_SETUPTOOLS:=bdepend}
  95
  96 if [[ ! ${_DISTUTILS_R1} ]]; then
  97
  98 [[ ${EAPI} == [456] ]] && inherit eutils
  99 [[ ${EAPI} == [56] ]] && inherit xdg-utils
 100 inherit multiprocessing toolchain-funcs
 101
 102 if [[ ! ${DISTUTILS_SINGLE_IMPL} ]]; then
 103         inherit python-r1
 104 else
 105         inherit python-single-r1
 106 fi
 107
 108 fi
 109
 110 if [[ ! ${DISTUTILS_OPTIONAL} ]]; then
 111         EXPORT_FUNCTIONS src_prepare src_configure src_compile src_test src_install
 112 fi
 113
 114 if [[ ! ${_DISTUTILS_R1} ]]; then
 115
 116 _distutils_set_globals() {
 117         local rdep=${PYTHON_DEPS}
 118         local bdep=${rdep}
 119
 120         case ${DISTUTILS_USE_SETUPTOOLS} in
 121                 no|manual)
 122                         ;;
 123                 bdepend)
 124                         bdep+=" dev-python/setuptools[${PYTHON_USEDEP}]"
 125                         ;;
 126                 rdepend)
 127                         bdep+=" dev-python/setuptools[${PYTHON_USEDEP}]"
 128                         rdep+=" dev-python/setuptools[${PYTHON_USEDEP}]"
 129                         ;;
 130                 *)
 131                         die "Invalid DISTUTILS_USE_SETUPTOOLS=${DISTUTILS_USE_SETUPTOOLS}"
 132                         ;;
 133         esac
 134
 135         RDEPEND=${rdep}
 136         if [[ ${EAPI} != [56] ]]; then
 137                 BDEPEND=${bdep}
 138         else
 139                 DEPEND=${bdep}
 140         fi
 141         REQUIRED_USE=${PYTHON_REQUIRED_USE}
 142 }
 143 [[ ! ${DISTUTILS_OPTIONAL} ]] && _distutils_set_globals
 144 unset -f _distutils_set_globals
 145
 146 # @ECLASS-VARIABLE: PATCHES
 147 # @DEFAULT_UNSET
 148 # @DESCRIPTION:
 149 # An array containing patches to be applied to the sources before
 150 # copying them.
 151 #
 152 # If unset, no custom patches will be applied.
 153 #
 154 # Please note, however, that at some point the eclass may apply
 155 # additional distutils patches/quirks independently of this variable.
 156 #
 157 # Example:
 158 # @CODE
 159 # PATCHES=( "${FILESDIR}"/${P}-make-gentoo-happy.patch )
 160 # @CODE
 161
 162 # @ECLASS-VARIABLE: DOCS
 163 # @DEFAULT_UNSET
 164 # @DESCRIPTION:
 165 # An array containing documents installed using dodoc. The files listed
 166 # there must exist in the directory from which
 167 # distutils-r1_python_install_all() is run (${S} by default).
 168 #
 169 # If unset, the function will instead look up files matching default
 170 # filename pattern list (from the Package Manager Specification),
 171 # and install those found.
 172 #
 173 # Example:
 174 # @CODE
 175 # DOCS=( NEWS README )
 176 # @CODE
 177
 178 # @ECLASS-VARIABLE: HTML_DOCS
 179 # @DEFAULT_UNSET
 180 # @DESCRIPTION:
 181 # An array containing documents installed using dohtml. The files
 182 # and directories listed there must exist in the directory from which
 183 # distutils-r1_python_install_all() is run (${S} by default).
 184 #
 185 # If unset, no HTML docs will be installed.
 186 #
 187 # Example:
 188 # @CODE
 189 # HTML_DOCS=( doc/html/. )
 190 # @CODE
 191
 192 # @ECLASS-VARIABLE: EXAMPLES
 193 # @DEFAULT_UNSET
 194 # @DESCRIPTION:
 195 # OBSOLETE: this variable is deprecated and banned in EAPI 6
 196 #
 197 # An array containing examples installed into 'examples' doc
 198 # subdirectory. The files and directories listed there must exist
 199 # in the directory from which distutils-r1_python_install_all() is run
 200 # (${S} by default).
 201 #
 202 # The 'examples' subdirectory will be marked not to be compressed
 203 # automatically.
 204 #
 205 # If unset, no examples will be installed.
 206 #
 207 # Example:
 208 # @CODE
 209 # EXAMPLES=( examples/. demos/. )
 210 # @CODE
 211
 212 # @ECLASS-VARIABLE: DISTUTILS_IN_SOURCE_BUILD
 213 # @DEFAULT_UNSET
 214 # @DESCRIPTION:
 215 # If set to a non-null value, in-source builds will be enabled.
 216 # If unset, the default is to use in-source builds when python_prepare()
 217 # is declared, and out-of-source builds otherwise.
 218 #
 219 # If in-source builds are used, the eclass will create a copy of package
 220 # sources for each Python implementation in python_prepare_all(),
 221 # and work on that copy afterwards.
 222 #
 223 # If out-of-source builds are used, the eclass will instead work
 224 # on the sources directly, prepending setup.py arguments with
 225 # 'build --build-base ${BUILD_DIR}' to enforce keeping & using built
 226 # files in the specific root.
 227
 228 # @ECLASS-VARIABLE: DISTUTILS_ALL_SUBPHASE_IMPLS
 229 # @DEFAULT_UNSET
 230 # @DESCRIPTION:
 231 # An array of patterns specifying which implementations can be used
 232 # for *_all() sub-phase functions. If undefined, defaults to '*'
 233 # (allowing any implementation). If multiple values are specified,
 234 # implementations matching any of the patterns will be accepted.
 235 #
 236 # The patterns can be either fnmatch-style patterns (matched via bash
 237 # == operator against PYTHON_COMPAT values) or '-2' / '-3' to indicate
 238 # appropriately all enabled Python 2/3 implementations (alike
 239 # python_is_python3). Remember to escape or quote the fnmatch patterns
 240 # to prevent accidental shell filename expansion.
 241 #
 242 # If the restriction needs to apply conditionally to a USE flag,
 243 # the variable should be set conditionally as well (e.g. in an early
 244 # phase function or other convenient location).
 245 #
 246 # Please remember to add a matching || block to REQUIRED_USE,
 247 # to ensure that at least one implementation matching the patterns will
 248 # be enabled.
 249 #
 250 # Example:
 251 # @CODE
 252 # REQUIRED_USE="doc? ( || ( $(python_gen_useflags 'python2*') ) )"
 253 #
 254 # pkg_setup() {
 255 #     use doc && DISTUTILS_ALL_SUBPHASE_IMPLS=( 'python2*' )
 256 # }
 257 # @CODE
 258
 259 # @ECLASS-VARIABLE: mydistutilsargs
 260 # @DEFAULT_UNSET
 261 # @DESCRIPTION:
 262 # An array containing options to be passed to setup.py.
 263 #
 264 # Example:
 265 # @CODE
 266 # python_configure_all() {
 267 #       mydistutilsargs=( --enable-my-hidden-option )
 268 # }
 269 # @CODE
 270
 271 # @FUNCTION: distutils_enable_sphinx
 272 # @USAGE: <subdir> [--no-autodoc | <plugin-pkgs>...]
 273 # @DESCRIPTION:
 274 # Set up IUSE, BDEPEND, python_check_deps() and python_compile_all() for
 275 # building HTML docs via dev-python/sphinx.  python_compile_all() will
 276 # append to HTML_DOCS if docs are enabled.
 277 #
 278 # This helper is meant for the most common case, that is a single Sphinx
 279 # subdirectory with standard layout, building and installing HTML docs
 280 # behind USE=doc.  It assumes it's the only consumer of the three
 281 # aforementioned functions.  If you need to use a custom implemention,
 282 # you can't use it.
 283 #
 284 # If your package uses additional Sphinx plugins, they should be passed
 285 # (without PYTHON_USEDEP) as <plugin-pkgs>.  The function will take care
 286 # of setting appropriate any-of dep and python_check_deps().
 287 #
 288 # If no plugin packages are specified, the eclass will still utilize
 289 # any-r1 API to support autodoc (documenting source code).
 290 # If the package uses neither autodoc nor additional plugins, you should
 291 # pass --no-autodoc to disable this API and simplify the resulting code.
 292 #
 293 # This function must be called in global scope.  Take care not to
 294 # overwrite the variables set by it.  If you need to extend
 295 # python_compile_all(), you can call the original implementation
 296 # as sphinx_compile_all.
 297 distutils_enable_sphinx() {
 298         debug-print-function ${FUNCNAME} "${@}"
 299         [[ ${#} -ge 1 ]] || die "${FUNCNAME} takes at least one arg: <subdir>"
 300
 301         _DISTUTILS_SPHINX_SUBDIR=${1}
 302         shift
 303         _DISTUTILS_SPHINX_PLUGINS=( "${@}" )
 304
 305         local deps autodoc=1 d
 306         for d; do
 307                 if [[ ${d} == --no-autodoc ]]; then
 308                         autodoc=
 309                 else
 310                         deps+="
 311                                 ${d}[\${PYTHON_USEDEP}]"
 312                 fi
 313         done
 314
 315         if [[ ! ${autodoc} && -n ${deps} ]]; then
 316                 die "${FUNCNAME}: do not pass --no-autodoc if external plugins are used"
 317         fi
 318         if [[ ${autodoc} ]]; then
 319                 deps="$(python_gen_any_dep "
 320                         dev-python/sphinx[\${PYTHON_USEDEP}]
 321                         ${deps}")"
 322
 323                 python_check_deps() {
 324                         use doc || return 0
 325                         local p
 326                         for p in dev-python/sphinx "${_DISTUTILS_SPHINX_PLUGINS[@]}"; do
 327                                 has_version "${p}[${PYTHON_USEDEP}]" || return 1
 328                         done
 329                 }
 330         else
 331                 deps="dev-python/sphinx"
 332         fi
 333
 334         sphinx_compile_all() {
 335                 use doc || return
 336
 337                 local confpy=${_DISTUTILS_SPHINX_SUBDIR}/conf.py
 338                 [[ -f ${confpy} ]] ||
 339                         die "${confpy} not found, distutils_enable_sphinx call wrong"
 340
 341                 if [[ ${_DISTUTILS_SPHINX_PLUGINS[0]} == --no-autodoc ]]; then
 342                         if grep -F -q 'sphinx.ext.autodoc' "${confpy}"; then
 343                                 die "distutils_enable_sphinx: --no-autodoc passed but sphinx.ext.autodoc found in ${confpy}"
 344                         fi
 345                 else
 346                         if ! grep -F -q 'sphinx.ext.autodoc' "${confpy}"; then
 347                                 die "distutils_enable_sphinx: sphinx.ext.autodoc not found in ${confpy}, pass --no-autodoc"
 348                         fi
 349                 fi
 350
 351                 build_sphinx "${_DISTUTILS_SPHINX_SUBDIR}"
 352         }
 353         python_compile_all() { sphinx_compile_all; }
 354
 355         IUSE+=" doc"
 356         if [[ ${EAPI} == [56] ]]; then
 357                 DEPEND+=" doc? ( ${deps} )"
 358         else
 359                 BDEPEND+=" doc? ( ${deps} )"
 360         fi
 361
 362         # we need to ensure successful return in case we're called last,
 363         # otherwise Portage may wrongly assume sourcing failed
 364         return 0
 365 }
 366
 367 # @FUNCTION: distutils_enable_tests
 368 # @USAGE: <test-runner>
 369 # @DESCRIPTION:
 370 # Set up IUSE, RESTRICT, BDEPEND and python_test() for running tests
 371 # with the specified test runner.  Also copies the current value
 372 # of RDEPEND to test?-BDEPEND.  The test-runner argument must be one of:
 373 #
 374 # - nose: nosetests (dev-python/nose)
 375 # - pytest: dev-python/pytest
 376 # - setup.py: setup.py test (no deps included)
 377 # - unittest: for built-in Python unittest module
 378 #
 379 # This function is meant as a helper for common use cases, and it only
 380 # takes care of basic setup.  You still need to list additional test
 381 # dependencies manually.  If you have uncommon use case, you should
 382 # not use it and instead enable tests manually.
 383 #
 384 # This function must be called in global scope, after RDEPEND has been
 385 # declared.  Take care not to overwrite the variables set by it.
 386 distutils_enable_tests() {
 387         debug-print-function ${FUNCNAME} "${@}"
 388         [[ ${#} -eq 1 ]] || die "${FUNCNAME} takes exactly one argument: test-runner"
 389
 390         local test_deps
 391         case ${1} in
 392                 nose)
 393                         test_deps="dev-python/nose[${PYTHON_USEDEP}]"
 394                         python_test() {
 395                                 nosetests -v || die "Tests fail with ${EPYTHON}"
 396                         }
 397                         ;;
 398                 pytest)
 399                         test_deps="dev-python/pytest[${PYTHON_USEDEP}]"
 400                         python_test() {
 401                                 pytest -vv || die "Tests fail with ${EPYTHON}"
 402                         }
 403                         ;;
 404                 setup.py)
 405                         python_test() {
 406                                 esetup.py test --verbose
 407                         }
 408                         ;;
 409                 unittest)
 410                         python_test() {
 411                                 "${EPYTHON}" -m unittest discover -v ||
 412                                         die "Tests fail with ${EPYTHON}"
 413                         }
 414                         ;;
 415                 *)
 416                         die "${FUNCNAME}: unsupported argument: ${1}"
 417         esac
 418
 419         if [[ -n ${test_deps} || -n ${RDEPEND} ]]; then
 420                 IUSE+=" test"
 421                 RESTRICT+=" !test? ( test )"
 422                 if [[ ${EAPI} == [56] ]]; then
 423                         DEPEND+=" test? ( ${test_deps} ${RDEPEND} )"
 424                 else
 425                         BDEPEND+=" test? ( ${test_deps} ${RDEPEND} )"
 426                 fi
 427         fi
 428
 429         # we need to ensure successful return in case we're called last,
 430         # otherwise Portage may wrongly assume sourcing failed
 431         return 0
 432 }
 433
 434 # @FUNCTION: _distutils-r1_verify_use_setuptools
 435 # @INTERNAL
 436 # @DESCRIPTION:
 437 # Check setup.py for signs that DISTUTILS_USE_SETUPTOOLS have been set
 438 # incorrectly.
 439 _distutils_verify_use_setuptools() {
 440         [[ ${DISTUTILS_OPTIONAL} ]] && return
 441         [[ ${DISTUTILS_USE_SETUPTOOLS} == manual ]] && return
 442
 443         # ok, those are cheap greps.  we can try toimprove them if we hit
 444         # false positives.
 445         local expected=no
 446         if [[ ${CATEGORY}/${PN} == dev-python/setuptools ]]; then
 447                 # as a special case, setuptools provides itself ;-)
 448                 :
 449         elif grep -E -q -s '(from|import)\s+setuptools' setup.py; then
 450                 if grep -E -q -s 'entry_points\s*=' setup.py; then
 451                         expected=rdepend
 452                 elif grep -F -q -s '[options.entry_points]' setup.cfg; then
 453                         expected=rdepend
 454                 else
 455                         expected=bdepend
 456                 fi
 457         fi
 458
 459         if [[ ${DISTUTILS_USE_SETUPTOOLS} != ${expected} ]]; then
 460                 if [[ ! ${_DISTUTILS_SETUPTOOLS_WARNED} ]]; then
 461                         _DISTUTILS_SETUPTOOLS_WARNED=1
 462                         local def=
 463                         [[ ${DISTUTILS_USE_SETUPTOOLS} == bdepend ]] && def=' (default?)'
 464
 465                         eqawarn "DISTUTILS_USE_SETUPTOOLS value is probably incorrect"
 466                         eqawarn "  value:    DISTUTILS_USE_SETUPTOOLS=${DISTUTILS_USE_SETUPTOOLS}${def}"
 467                         eqawarn "  expected: DISTUTILS_USE_SETUPTOOLS=${expected}"
 468                 fi
 469         fi
 470 }
 471
 472 # @FUNCTION: esetup.py
 473 # @USAGE: [<args>...]
 474 # @DESCRIPTION:
 475 # Run setup.py using currently selected Python interpreter
 476 # (if ${EPYTHON} is set; fallback 'python' otherwise).
 477 #
 478 # setup.py will be passed the following, in order:
 479 # 1. ${mydistutilsargs[@]}
 480 # 2. additional arguments passed to the esetup.py function.
 481 #
 482 # Please note that setup.py will respect defaults (unless overridden
 483 # via command-line options) from setup.cfg that is created
 484 # in distutils-r1_python_compile and in distutils-r1_python_install.
 485 #
 486 # This command dies on failure.
 487 esetup.py() {
 488         debug-print-function ${FUNCNAME} "${@}"
 489
 490         local die_args=()
 491         [[ ${EAPI} != [45] ]] && die_args+=( -n )
 492
 493         [[ ${BUILD_DIR} ]] && _distutils-r1_create_setup_cfg
 494         _distutils_verify_use_setuptools
 495
 496         set -- "${EPYTHON:-python}" setup.py "${mydistutilsargs[@]}" "${@}"
 497
 498         echo "${@}" >&2
 499         "${@}" || die "${die_args[@]}"
 500         local ret=${?}
 501
 502         if [[ ${BUILD_DIR} ]]; then
 503                 rm "${HOME}"/.pydistutils.cfg || die "${die_args[@]}"
 504         fi
 505
 506         return ${ret}
 507 }
 508
 509 # @FUNCTION: distutils_install_for_testing
 510 # @USAGE: [<args>...]
 511 # @DESCRIPTION:
 512 # Install the package into a temporary location for running tests.
 513 # Update PYTHONPATH appropriately and set TEST_DIR to the test
 514 # installation root. The Python packages will be installed in 'lib'
 515 # subdir, and scripts in 'scripts' subdir (like in BUILD_DIR).
 516 #
 517 # Please note that this function should be only used if package uses
 518 # namespaces (and therefore proper install needs to be done to enforce
 519 # PYTHONPATH) or tests rely on the results of install command.
 520 # For most of the packages, tests built in BUILD_DIR are good enough.
 521 distutils_install_for_testing() {
 522         debug-print-function ${FUNCNAME} "${@}"
 523
 524         # A few notes:
 525         # 1) because of namespaces, we can't use 'install --root',
 526         # 2) 'install --home' is terribly broken on pypy, so we need
 527         #    to override --install-lib and --install-scripts,
 528         # 3) non-root 'install' complains about PYTHONPATH and missing dirs,
 529         #    so we need to set it properly and mkdir them,
 530         # 4) it runs a bunch of commands which write random files to cwd,
 531         #    in order to avoid that, we add the necessary path overrides
 532         #    in _distutils-r1_create_setup_cfg.
 533
 534         TEST_DIR=${BUILD_DIR}/test
 535         local bindir=${TEST_DIR}/scripts
 536         local libdir=${TEST_DIR}/lib
 537         PYTHONPATH=${libdir}:${PYTHONPATH}
 538
 539         local add_args=(
 540                 install
 541                         --home="${TEST_DIR}"
 542                         --install-lib="${libdir}"
 543                         --install-scripts="${bindir}"
 544         )
 545
 546         mkdir -p "${libdir}" || die
 547         esetup.py "${add_args[@]}" "${@}"
 548 }
 549
 550 # @FUNCTION: _distutils-r1_disable_ez_setup
 551 # @INTERNAL
 552 # @DESCRIPTION:
 553 # Stub out ez_setup.py and distribute_setup.py to prevent packages
 554 # from trying to download a local copy of setuptools.
 555 _distutils-r1_disable_ez_setup() {
 556         local stub="def use_setuptools(*args, **kwargs): pass"
 557         if [[ -f ez_setup.py ]]; then
 558                 echo "${stub}" > ez_setup.py || die
 559         fi
 560         if [[ -f distribute_setup.py ]]; then
 561                 echo "${stub}" > distribute_setup.py || die
 562         fi
 563 }
 564
 565 # @FUNCTION: distutils-r1_python_prepare_all
 566 # @DESCRIPTION:
 567 # The default python_prepare_all(). It applies the patches from PATCHES
 568 # array, then user patches and finally calls python_copy_sources to
 569 # create copies of resulting sources for each Python implementation.
 570 #
 571 # At some point in the future, it may also apply eclass-specific
 572 # distutils patches and/or quirks.
 573 distutils-r1_python_prepare_all() {
 574         debug-print-function ${FUNCNAME} "${@}"
 575
 576         if [[ ! ${DISTUTILS_OPTIONAL} ]]; then
 577                 if [[ ${EAPI} != [45] ]]; then
 578                         default
 579                 else
 580                         [[ ${PATCHES} ]] && epatch "${PATCHES[@]}"
 581                         epatch_user
 582                 fi
 583         fi
 584
 585         # by default, use in-source build if python_prepare() is used
 586         if [[ ! ${DISTUTILS_IN_SOURCE_BUILD+1} ]]; then
 587                 if declare -f python_prepare >/dev/null; then
 588                         DISTUTILS_IN_SOURCE_BUILD=1
 589                 fi
 590         fi
 591
 592         _distutils-r1_disable_ez_setup
 593
 594         if [[ ${DISTUTILS_IN_SOURCE_BUILD} && ! ${DISTUTILS_SINGLE_IMPL} ]]
 595         then
 596                 # create source copies for each implementation
 597                 python_copy_sources
 598         fi
 599
 600         _DISTUTILS_DEFAULT_CALLED=1
 601 }
 602
 603 # @FUNCTION: distutils-r1_python_prepare
 604 # @DESCRIPTION:
 605 # The default python_prepare(). A no-op.
 606 distutils-r1_python_prepare() {
 607         debug-print-function ${FUNCNAME} "${@}"
 608
 609         [[ ${EAPI} == [45] ]] || die "${FUNCNAME} is banned in EAPI 6 (it was a no-op)"
 610 }
 611
 612 # @FUNCTION: distutils-r1_python_configure
 613 # @DESCRIPTION:
 614 # The default python_configure(). A no-op.
 615 distutils-r1_python_configure() {
 616         debug-print-function ${FUNCNAME} "${@}"
 617
 618         [[ ${EAPI} == [45] ]] || die "${FUNCNAME} is banned in EAPI 6 (it was a no-op)"
 619 }
 620
 621 # @FUNCTION: _distutils-r1_create_setup_cfg
 622 # @INTERNAL
 623 # @DESCRIPTION:
 624 # Create implementation-specific configuration file for distutils,
 625 # setting proper build-dir (and install-dir) paths.
 626 _distutils-r1_create_setup_cfg() {
 627         cat > "${HOME}"/.pydistutils.cfg <<-_EOF_ || die
 628                 [build]
 629                 build-base = ${BUILD_DIR}
 630
 631                 # using a single directory for them helps us export
 632                 # ${PYTHONPATH} and ebuilds find the sources independently
 633                 # of whether the package installs extensions or not
 634                 #
 635                 # note: due to some packages (wxpython) relying on separate
 636                 # platlib & purelib dirs, we do not set --build-lib (which
 637                 # can not be overridden with --build-*lib)
 638                 build-platlib = %(build-base)s/lib
 639                 build-purelib = %(build-base)s/lib
 640
 641                 # make the ebuild writer lives easier
 642                 build-scripts = %(build-base)s/scripts
 643
 644                 # this is needed by distutils_install_for_testing since
 645                 # setuptools like to create .egg files for install --home.
 646                 [bdist_egg]
 647                 dist-dir = ${BUILD_DIR}/dist
 648         _EOF_
 649
 650         # we can't refer to ${D} before src_install()
 651         if [[ ${EBUILD_PHASE} == install ]]; then
 652                 cat >> "${HOME}"/.pydistutils.cfg <<-_EOF_ || die
 653
 654                         # installation paths -- allow calling extra install targets
 655                         # without the default 'install'
 656                         [install]
 657                         compile = True
 658                         optimize = 2
 659                         root = ${D%/}
 660                 _EOF_
 661
 662                 if [[ ! ${DISTUTILS_SINGLE_IMPL} ]]; then
 663                         cat >> "${HOME}"/.pydistutils.cfg <<-_EOF_ || die
 664                                 install-scripts = $(python_get_scriptdir)
 665                         _EOF_
 666                 fi
 667         fi
 668 }
 669
 670 # @FUNCTION: _distutils-r1_copy_egg_info
 671 # @INTERNAL
 672 # @DESCRIPTION:
 673 # Copy egg-info files to the ${BUILD_DIR} (that's going to become
 674 # egg-base in esetup.py). This way, we respect whatever's in upstream
 675 # egg-info.
 676 _distutils-r1_copy_egg_info() {
 677         mkdir -p "${BUILD_DIR}" || die
 678         # stupid freebsd can't do 'cp -t ${BUILD_DIR} {} +'
 679         find -name '*.egg-info' -type d -exec cp -R -p {} "${BUILD_DIR}"/ ';' || die
 680 }
 681
 682 # @FUNCTION: distutils-r1_python_compile
 683 # @USAGE: [additional-args...]
 684 # @DESCRIPTION:
 685 # The default python_compile(). Runs 'esetup.py build'. Any parameters
 686 # passed to this function will be appended to setup.py invocation,
 687 # i.e. passed as options to the 'build' command.
 688 #
 689 # This phase also sets up initial setup.cfg with build directories
 690 # and copies upstream egg-info files if supplied.
 691 distutils-r1_python_compile() {
 692         debug-print-function ${FUNCNAME} "${@}"
 693
 694         _distutils-r1_copy_egg_info
 695
 696         local build_args=()
 697         # distutils is parallel-capable since py3.5
 698         # to avoid breaking stable ebuilds, enable it only if either:
 699         # a. we're dealing with EAPI 7
 700         # b. we're dealing with Python 3.7 or PyPy3
 701         if python_is_python3 && [[ ${EPYTHON} != python3.4 ]]; then
 702                 if [[ ${EAPI} != [56] || ${EPYTHON} != python3.[56] ]]; then
 703                         local jobs=$(makeopts_jobs "${MAKEOPTS}" INF)
 704                         if [[ ${jobs} == INF ]]; then
 705                                 local nproc=$(get_nproc)
 706                                 jobs=$(( nproc + 1 ))
 707                         fi
 708                         build_args+=( -j "${jobs}" )
 709                 fi
 710         fi
 711
 712         esetup.py build "${build_args[@]}" "${@}"
 713 }
 714
 715 # @FUNCTION: _distutils-r1_wrap_scripts
 716 # @USAGE: <path> <bindir>
 717 # @INTERNAL
 718 # @DESCRIPTION:
 719 # Moves and wraps all installed scripts/executables as necessary.
 720 _distutils-r1_wrap_scripts() {
 721         debug-print-function ${FUNCNAME} "${@}"
 722
 723         [[ ${#} -eq 2 ]] || die "usage: ${FUNCNAME} <path> <bindir>"
 724         local path=${1}
 725         local bindir=${2}
 726
 727         local PYTHON_SCRIPTDIR
 728         python_export PYTHON_SCRIPTDIR
 729
 730         local f python_files=() non_python_files=()
 731
 732         if [[ -d ${path}${PYTHON_SCRIPTDIR} ]]; then
 733                 for f in "${path}${PYTHON_SCRIPTDIR}"/*; do
 734                         [[ -d ${f} ]] && die "Unexpected directory: ${f}"
 735                         debug-print "${FUNCNAME}: found executable at ${f#${path}/}"
 736
 737                         local shebang
 738                         read -r shebang < "${f}"
 739                         if [[ ${shebang} == '#!'*${EPYTHON}* ]]; then
 740                                 debug-print "${FUNCNAME}: matching shebang: ${shebang}"
 741                                 python_files+=( "${f}" )
 742                         else
 743                                 debug-print "${FUNCNAME}: non-matching shebang: ${shebang}"
 744                                 non_python_files+=( "${f}" )
 745                         fi
 746
 747                         mkdir -p "${path}${bindir}" || die
 748                 done
 749
 750                 for f in "${python_files[@]}"; do
 751                         local basename=${f##*/}
 752
 753                         debug-print "${FUNCNAME}: installing wrapper at ${bindir}/${basename}"
 754                         _python_ln_rel "${path}${EPREFIX}"/usr/lib/python-exec/python-exec2 \
 755                                 "${path}${bindir}/${basename}" || die
 756                 done
 757
 758                 for f in "${non_python_files[@]}"; do
 759                         local basename=${f##*/}
 760
 761                         debug-print "${FUNCNAME}: moving ${f#${path}/} to ${bindir}/${basename}"
 762                         mv "${f}" "${path}${bindir}/${basename}" || die
 763                 done
 764         fi
 765 }
 766
 767 # @FUNCTION: distutils-r1_python_install
 768 # @USAGE: [additional-args...]
 769 # @DESCRIPTION:
 770 # The default python_install(). Runs 'esetup.py install', doing
 771 # intermediate root install and handling script wrapping afterwards.
 772 # Any parameters passed to this function will be appended
 773 # to the setup.py invocation (i.e. as options to the 'install' command).
 774 #
 775 # This phase updates the setup.cfg file with install directories.
 776 distutils-r1_python_install() {
 777         debug-print-function ${FUNCNAME} "${@}"
 778
 779         local args=( "${@}" )
 780
 781         # enable compilation for the install phase.
 782         local -x PYTHONDONTWRITEBYTECODE=
 783
 784         # python likes to compile any module it sees, which triggers sandbox
 785         # failures if some packages haven't compiled their modules yet.
 786         addpredict "${EPREFIX}/usr/lib/${EPYTHON}"
 787         addpredict "${EPREFIX}/usr/$(get_libdir)/${EPYTHON}"
 788         addpredict /usr/lib/pypy2.7
 789         addpredict /usr/lib/pypy3.6
 790         addpredict /usr/lib/portage/pym
 791         addpredict /usr/local # bug 498232
 792
 793         if [[ ! ${DISTUTILS_SINGLE_IMPL} ]]; then
 794                 # user may override --install-scripts
 795                 # note: this is poor but distutils argv parsing is dumb
 796                 local mydistutilsargs=( "${mydistutilsargs[@]}" )
 797                 local scriptdir=${EPREFIX}/usr/bin
 798
 799                 # construct a list of mydistutilsargs[0] args[0] args[1]...
 800                 local arg arg_vars
 801                 [[ ${mydistutilsargs[@]} ]] && eval arg_vars+=(
 802                         'mydistutilsargs['{0..$(( ${#mydistutilsargs[@]} - 1 ))}']'
 803                 )
 804                 [[ ${args[@]} ]] && eval arg_vars+=(
 805                         'args['{0..$(( ${#args[@]} - 1 ))}']'
 806                 )
 807
 808                 set -- "${arg_vars[@]}"
 809                 while [[ ${@} ]]; do
 810                         local arg_var=${1}
 811                         shift
 812                         local a=${!arg_var}
 813
 814                         case "${a}" in
 815                                 --install-scripts=*)
 816                                         scriptdir=${a#--install-scripts=}
 817                                         unset "${arg_var}"
 818                                         ;;
 819                                 --install-scripts)
 820                                         scriptdir=${!1}
 821                                         unset "${arg_var}" "${1}"
 822                                         shift
 823                                         ;;
 824                         esac
 825                 done
 826         fi
 827
 828         local root=${D%/}/_${EPYTHON}
 829         [[ ${DISTUTILS_SINGLE_IMPL} ]] && root=${D%/}
 830
 831         esetup.py install --root="${root}" "${args[@]}"
 832
 833         local forbidden_package_names=( examples test tests .pytest_cache )
 834         local p
 835         for p in "${forbidden_package_names[@]}"; do
 836                 if [[ -d ${root}$(python_get_sitedir)/${p} ]]; then
 837                         die "Package installs '${p}' package which is forbidden and likely a bug in the build system."
 838                 fi
 839         done
 840
 841         local shopt_save=$(shopt -p nullglob)
 842         shopt -s nullglob
 843         local pypy_dirs=(
 844                 "${root}/usr/$(get_libdir)"/pypy*/share
 845                 "${root}/usr/lib"/pypy*/share
 846         )
 847         ${shopt_save}
 848
 849         if [[ -n ${pypy_dirs} ]]; then
 850                 local cmd=die
 851                 [[ ${EAPI} == [45] ]] && cmd=eqawarn
 852                 "${cmd}" "Package installs 'share' in PyPy prefix, see bug #465546."
 853         fi
 854
 855         if [[ ! ${DISTUTILS_SINGLE_IMPL} ]]; then
 856                 _distutils-r1_wrap_scripts "${root}" "${scriptdir}"
 857                 multibuild_merge_root "${root}" "${D%/}"
 858         fi
 859 }
 860
 861 # @FUNCTION: distutils-r1_python_install_all
 862 # @DESCRIPTION:
 863 # The default python_install_all(). It installs the documentation.
 864 distutils-r1_python_install_all() {
 865         debug-print-function ${FUNCNAME} "${@}"
 866
 867         einstalldocs
 868
 869         if declare -p EXAMPLES &>/dev/null; then
 870                 [[ ${EAPI} != [45] ]] && die "EXAMPLES are banned in EAPI ${EAPI}"
 871
 872                 (
 873                         docinto examples
 874                         dodoc -r "${EXAMPLES[@]}"
 875                 )
 876                 docompress -x "/usr/share/doc/${PF}/examples"
 877         fi
 878
 879         _DISTUTILS_DEFAULT_CALLED=1
 880 }
 881
 882 # @FUNCTION: distutils-r1_run_phase
 883 # @USAGE: [<argv>...]
 884 # @INTERNAL
 885 # @DESCRIPTION:
 886 # Run the given command.
 887 #
 888 # If out-of-source builds are used, the phase function is run in source
 889 # directory, with BUILD_DIR pointing at the build directory
 890 # and PYTHONPATH having an entry for the module build directory.
 891 #
 892 # If in-source builds are used, the command is executed in the directory
 893 # holding the per-implementation copy of sources. BUILD_DIR points
 894 # to the 'build' subdirectory.
 895 distutils-r1_run_phase() {
 896         debug-print-function ${FUNCNAME} "${@}"
 897
 898         if [[ ${DISTUTILS_IN_SOURCE_BUILD} ]]; then
 899                 # only force BUILD_DIR if implementation is explicitly enabled
 900                 # for building; any-r1 API may select one that is not
 901                 # https://bugs.gentoo.org/701506
 902                 if [[ ! ${DISTUTILS_SINGLE_IMPL} ]] &&
 903                                 has "${EPYTHON/./_}" ${PYTHON_TARGETS}; then
 904                         cd "${BUILD_DIR}" || die
 905                 fi
 906                 local BUILD_DIR=${BUILD_DIR}/build
 907         fi
 908         local -x PYTHONPATH="${BUILD_DIR}/lib:${PYTHONPATH}"
 909
 910         # Bug 559644
 911         # using PYTHONPATH when the ${BUILD_DIR}/lib is not created yet might lead to
 912         # problems in setup.py scripts that try to import modules/packages from that path
 913         # during the build process (Python at startup evaluates PYTHONPATH, if the dir is
 914         # not valid then associates a NullImporter object to ${BUILD_DIR}/lib storing it
 915         # in the sys.path_importer_cache)
 916         mkdir -p "${BUILD_DIR}/lib" || die
 917
 918         # Set up build environment, bug #513664.
 919         local -x AR=${AR} CC=${CC} CPP=${CPP} CXX=${CXX}
 920         tc-export AR CC CPP CXX
 921
 922         # How to build Python modules in different worlds...
 923         local ldopts
 924         case "${CHOST}" in
 925                 # provided by haubi, 2014-07-08
 926                 *-aix*) ldopts='-shared -Wl,-berok';; # good enough
 927                 # provided by grobian, 2014-06-22, bug #513664 c7
 928                 *-darwin*) ldopts='-bundle -undefined dynamic_lookup';;
 929                 *) ldopts='-shared';;
 930         esac
 931
 932         local -x LDSHARED="${CC} ${ldopts}" LDCXXSHARED="${CXX} ${ldopts}"
 933
 934         "${@}"
 935
 936         cd "${_DISTUTILS_INITIAL_CWD}" || die
 937 }
 938
 939 # @FUNCTION: _distutils-r1_run_common_phase
 940 # @USAGE: [<argv>...]
 941 # @INTERNAL
 942 # @DESCRIPTION:
 943 # Run the given command, restoring the state for a most preferred Python
 944 # implementation matching DISTUTILS_ALL_SUBPHASE_IMPLS.
 945 #
 946 # If in-source build is used, the command will be run in the copy
 947 # of sources made for the selected Python interpreter.
 948 _distutils-r1_run_common_phase() {
 949         local DISTUTILS_ORIG_BUILD_DIR=${BUILD_DIR}
 950
 951         if [[ ${DISTUTILS_SINGLE_IMPL} ]]; then
 952                 # reuse the dedicated code branch
 953                 _distutils-r1_run_foreach_impl "${@}"
 954         else
 955                 local -x EPYTHON PYTHON
 956                 local -x PATH=${PATH} PKG_CONFIG_PATH=${PKG_CONFIG_PATH}
 957                 python_setup "${DISTUTILS_ALL_SUBPHASE_IMPLS[@]}"
 958
 959                 local MULTIBUILD_VARIANTS=( "${EPYTHON/./_}" )
 960                 # store for restoring after distutils-r1_run_phase.
 961                 local _DISTUTILS_INITIAL_CWD=${PWD}
 962                 multibuild_foreach_variant \
 963                         distutils-r1_run_phase "${@}"
 964         fi
 965 }
 966
 967 # @FUNCTION: _distutils-r1_run_foreach_impl
 968 # @INTERNAL
 969 # @DESCRIPTION:
 970 # Run the given phase for each implementation if multiple implementations
 971 # are enabled, once otherwise.
 972 _distutils-r1_run_foreach_impl() {
 973         debug-print-function ${FUNCNAME} "${@}"
 974
 975         # store for restoring after distutils-r1_run_phase.
 976         local _DISTUTILS_INITIAL_CWD=${PWD}
 977         set -- distutils-r1_run_phase "${@}"
 978
 979         if [[ ! ${DISTUTILS_SINGLE_IMPL} ]]; then
 980                 python_foreach_impl "${@}"
 981         else
 982                 if [[ ! ${EPYTHON} ]]; then
 983                         die "EPYTHON unset, python-single-r1_pkg_setup not called?!"
 984                 fi
 985                 local BUILD_DIR=${BUILD_DIR:-${S}}
 986                 BUILD_DIR=${BUILD_DIR%%/}_${EPYTHON}
 987
 988                 "${@}"
 989         fi
 990 }
 991
 992 distutils-r1_src_prepare() {
 993         debug-print-function ${FUNCNAME} "${@}"
 994
 995         local _DISTUTILS_DEFAULT_CALLED
 996
 997         # common preparations
 998         if declare -f python_prepare_all >/dev/null; then
 999                 python_prepare_all
1000         else
1001                 distutils-r1_python_prepare_all
1002         fi
1003
1004         if [[ ! ${_DISTUTILS_DEFAULT_CALLED} ]]; then
1005                 local cmd=die
1006                 [[ ${EAPI} == [45] ]] && cmd=eqawarn
1007
1008                 "${cmd}" "QA: python_prepare_all() didn't call distutils-r1_python_prepare_all"
1009         fi
1010
1011         if declare -f python_prepare >/dev/null; then
1012                 _distutils-r1_run_foreach_impl python_prepare
1013         fi
1014 }
1015
1016 distutils-r1_src_configure() {
1017         python_export_utf8_locale
1018         [[ ${EAPI} == [56] ]] && xdg_environment_reset # Bug 577704
1019
1020         if declare -f python_configure >/dev/null; then
1021                 _distutils-r1_run_foreach_impl python_configure
1022         fi
1023
1024         if declare -f python_configure_all >/dev/null; then
1025                 _distutils-r1_run_common_phase python_configure_all
1026         fi
1027 }
1028
1029 distutils-r1_src_compile() {
1030         debug-print-function ${FUNCNAME} "${@}"
1031
1032         if declare -f python_compile >/dev/null; then
1033                 _distutils-r1_run_foreach_impl python_compile
1034         else
1035                 _distutils-r1_run_foreach_impl distutils-r1_python_compile
1036         fi
1037
1038         if declare -f python_compile_all >/dev/null; then
1039                 _distutils-r1_run_common_phase python_compile_all
1040         fi
1041 }
1042
1043 # @FUNCTION: _distutils-r1_clean_egg_info
1044 # @INTERNAL
1045 # @DESCRIPTION:
1046 # Clean up potential stray egg-info files left by setuptools test phase.
1047 # Those files ended up being unversioned, and caused issues:
1048 # https://bugs.gentoo.org/534058
1049 _distutils-r1_clean_egg_info() {
1050         rm -rf "${BUILD_DIR}"/lib/*.egg-info || die
1051 }
1052
1053 distutils-r1_src_test() {
1054         debug-print-function ${FUNCNAME} "${@}"
1055
1056         if declare -f python_test >/dev/null; then
1057                 _distutils-r1_run_foreach_impl python_test
1058                 _distutils-r1_run_foreach_impl _distutils-r1_clean_egg_info
1059         fi
1060
1061         if declare -f python_test_all >/dev/null; then
1062                 _distutils-r1_run_common_phase python_test_all
1063         fi
1064 }
1065
1066 # @FUNCTION: _distutils-r1_check_namespace_pth
1067 # @INTERNAL
1068 # @DESCRIPTION:
1069 # Check if any *-nspkg.pth files were installed (by setuptools)
1070 # and warn about the policy non-conformance if they were.
1071 _distutils-r1_check_namespace_pth() {
1072         local f pth=()
1073
1074         while IFS= read -r -d '' f; do
1075                 pth+=( "${f}" )
1076         done < <(find "${ED%/}" -name '*-nspkg.pth' -print0)
1077
1078         if [[ ${pth[@]} ]]; then
1079                 ewarn "The following *-nspkg.pth files were found installed:"
1080                 ewarn
1081                 for f in "${pth[@]}"; do
1082                         ewarn "  ${f#${ED%/}}"
1083                 done
1084                 ewarn
1085                 ewarn "The presence of those files may break namespaces in Python 3.5+. Please"
1086                 ewarn "read our documentation on reliable handling of namespaces and update"
1087                 ewarn "the ebuild accordingly:"
1088                 ewarn
1089                 ewarn "  https://wiki.gentoo.org/wiki/Project:Python/Namespace_packages"
1090         fi
1091 }
1092
1093 distutils-r1_src_install() {
1094         debug-print-function ${FUNCNAME} "${@}"
1095
1096         if declare -f python_install >/dev/null; then
1097                 _distutils-r1_run_foreach_impl python_install
1098         else
1099                 _distutils-r1_run_foreach_impl distutils-r1_python_install
1100         fi
1101
1102         local _DISTUTILS_DEFAULT_CALLED
1103
1104         if declare -f python_install_all >/dev/null; then
1105                 _distutils-r1_run_common_phase python_install_all
1106         else
1107                 _distutils-r1_run_common_phase distutils-r1_python_install_all
1108         fi
1109
1110         if [[ ! ${_DISTUTILS_DEFAULT_CALLED} ]]; then
1111                 local cmd=die
1112                 [[ ${EAPI} == [45] ]] && cmd=eqawarn
1113
1114                 "${cmd}" "QA: python_install_all() didn't call distutils-r1_python_install_all"
1115         fi
1116
1117         _distutils-r1_check_namespace_pth
1118 }
1119
1120 # -- distutils.eclass functions --
1121
1122 distutils_get_intermediate_installation_image() {
1123         die "${FUNCNAME}() is invalid for distutils-r1"
1124 }
1125
1126 distutils_src_unpack() {
1127         die "${FUNCNAME}() is invalid for distutils-r1, and you don't want it in EAPI ${EAPI} anyway"
1128 }
1129
1130 distutils_src_prepare() {
1131         die "${FUNCNAME}() is invalid for distutils-r1, you probably want: ${FUNCNAME/_/-r1_}"
1132 }
1133
1134 distutils_src_compile() {
1135         die "${FUNCNAME}() is invalid for distutils-r1, you probably want: ${FUNCNAME/_/-r1_}"
1136 }
1137
1138 distutils_src_test() {
1139         die "${FUNCNAME}() is invalid for distutils-r1, you probably want: ${FUNCNAME/_/-r1_}"
1140 }
1141
1142 distutils_src_install() {
1143         die "${FUNCNAME}() is invalid for distutils-r1, you probably want: ${FUNCNAME/_/-r1_}"
1144 }
1145
1146 distutils_pkg_postinst() {
1147         die "${FUNCNAME}() is invalid for distutils-r1, and pkg_postinst is unnecessary"
1148 }
1149
1150 distutils_pkg_postrm() {
1151         die "${FUNCNAME}() is invalid for distutils-r1, and pkg_postrm is unnecessary"
1152 }
1153
1154 _DISTUTILS_R1=1
1155 fi