Project:Python/waf-utils integration

The waf build system bundled by a few packages is written in Python and uses build scripts that are written in Python as well. To ensure the best user experience, the waf-utils eclass intended to support waf needs to be combined with a proper python-r1 suite eclass.

Requirements for using waf-utils

Any ebuild using waf-utils needs to:

1. Set a proper value of PYTHON_COMPAT being the intersection of Python implementations supported by build system scripts and the package (if applicable),
2. Set a proper value of PYTHON_REQ_USE being the union of threads(+) (required by waf) and the USE flags required by the package (if applicable),
3. Inherit a proper Python eclass (python-any-r1, python-single-r1 or python-r1).

Which eclass to use?

The usual rules for choosing the eclass apply. That is:

1. If the package installs Python modules that need to be installed for multiple Python implementations, use python-r1 and remember to call python_setup if you want to use waf outside of python_foreach_impl,
2. If the package installs Python modules or scripts, use python-single-r1,
3. Otherwise, use python-any-r1 to express purely build-time dependency on Python.

Examples

Purely build-time dependency

Assumes that only waf (and possibly some other build/test scripts) require Python.

CODE Example ebuild with waf & build-time dep on Python

PYTHON_COMPAT=( python2_7 python3_4 )
PYTHON_REQ_USE='threads(+)' # required by waf

inherit python-any-r1 waf-utils

DEPEND=${PYTHON_DEPS}

pkg_setup() { python-any-r1_pkg_setup; } # if necessary

Simple run-time dependency + waf

A package that installs some Python scripts/modules and uses waf.

CODE Example ebuild with waf & simple run-time dep on Python

PYTHON_COMPAT=( python2_7 )
PYTHON_REQ_USE='threads(+),ssl(+)' # threads for waf, ssl for package

inherit python-single-r1 waf-utils

RDEPEND=${PYTHON_DEPS}
DEPEND=${RDEPEND}
REQUIRED_USE=${PYTHON_REQUIRED_USE}

pkg_setup() { python-single-r1_pkg_setup; } # if necessary

Conditional run-time dependency + waf

A package that installs some Python scripts/modules conditionally and uses waf (unconditionally).

CODE Example ebuild with waf & conditional run-time dep on Python

PYTHON_COMPAT=( python2_7 )
PYTHON_REQ_USE='threads(+),ssl(+)'

inherit python-single-r1 waf-utils

IUSE="python"

RDEPEND="python? ( ${PYTHON_DEPS} )"
DEPEND=${PYTHON_DEPS}
REQUIRED_USE=${PYTHON_REQUIRED_USE}

# has MERGE_TYPE check inside, so applies to source build only
pkg_setup() { python-single-r1_pkg_setup; }

# if you needed Python during pkg_pre/post* as well...
# pkg_setup() {
#     if [[ ${MERGE_TYPE} != binary ]] || use python; then
#         python_setup
#     fi
# }