DISTUTILS-R1

Section: portage (5)
Updated: May 2013
Index Return to Main Contents

---

 

NAME

distutils-r1 - A simple eclass to build Python packages using distutils.  

DESCRIPTION

A simple eclass providing functions to build Python packages using the distutils build system. It exports phase functions for all the src_* phases. Each of the phases runs two pseudo-phases: python_..._all() (e.g. python_prepare_all()) once in ${S}, then python_...() (e.g. python_prepare()) for each implementation (see: python_foreach_impl() in python-r1).

In distutils-r1_src_prepare(), the 'all' function is run before per-implementation ones (because it creates the implementations), per-implementation functions are run in a random order.

In remaining phase functions, the per-implementation functions are run before the 'all' one, and they are ordered from the least to the most preferred implementation (so that 'better' files overwrite 'worse' ones).

If the ebuild doesn't specify a particular pseudo-phase function, the default one will be used (distutils-r1_...). Defaults are provided for all per-implementation pseudo-phases, python_prepare_all() and python_install_all(); whenever writing your own pseudo-phase functions, you should consider calling the defaults (and especially distutils-r1_python_prepare_all).

Please note that distutils-r1 sets RDEPEND and DEPEND unconditionally for you.

Also, please note that distutils-r1 will always inherit python-r1 as well. Thus, all the variables defined and documented there are relevant to the packages using distutils-r1.

For more information, please see the python-r1 Developer's Guide: http://www.gentoo.org/proj/en/Python/python-r1/dev-guide.xml  

FUNCTIONS

esetup.py [<args>...]

Run setup.py using currently selected Python interpreter (if ${PYTHON} is set; fallback 'python' otherwise).

setup.py will be passed the following, in order: 1. ${mydistutilsargs[@]} 2. The 'build' command and standard build options including ${BUILD_DIR} 3. Any additional arguments passed to the esetup.py function.

This command dies on failure.

distutils_install_for_testing [<args>...]

Install the package into a temporary location for running tests. Update PYTHONPATH appropriately and set TEST_DIR to the test installation root. The Python packages will be installed in 'lib' subdir, and scripts in 'scripts' subdir (like in BUILD_DIR).

Please note that this function should be only used if package uses namespaces (and therefore proper install needs to be done to enforce PYTHONPATH) or tests rely on the results of install command. For most of the packages, tests built in BUILD_DIR are good enough.

distutils-r1_python_prepare_all

The default python_prepare_all(). It applies the patches from PATCHES array, then user patches and finally calls python_copy_sources to create copies of resulting sources for each Python implementation.

At some point in the future, it may also apply eclass-specific distutils patches and/or quirks.

distutils-r1_python_prepare

The default python_prepare(). A no-op.

distutils-r1_python_configure

The default python_configure(). A no-op.

distutils-r1_python_compile [additional-args...]

The default python_compile(). Runs 'esetup.py build'. Any parameters passed to this function will be appended to setup.py invocation, i.e. passed as options to the 'build' command.

distutils-r1_python_test

The default python_test(). A no-op.

distutils-r1_python_install [additional-args...]

The default python_install(). Runs 'esetup.py install', appending the optimization flags. Then renames the installed scripts. Any parameters passed to this function will be appended to the setup.py invocation (i.e. as options to the 'install' command).

distutils-r1_python_install_all

The default python_install_all(). It installs the documentation.

 

ECLASS VARIABLES

DISTUTILS_OPTIONAL

If set to a non-null value, distutils part in the ebuild will be considered optional. No dependencies will be added and no phase functions will be exported.

If you enable DISTUTILS_OPTIONAL, you have to set proper dependencies for your package (using ${PYTHON_DEPS}) and to either call distutils-r1 default phase functions or call the build system manually.

DISTUTILS_SINGLE_IMPL

If set to a non-null value, the ebuild will support setting a single Python implementation only. It will effectively replace the python-r1 eclass inherit with python-single-r1.

Note that inheriting python-single-r1 will cause pkg_setup() to be exported. It must be run in order for the eclass functions to function properly.

PATCHES

An array containing patches to be applied to the sources before copying them.

If unset, no custom patches will be applied.

Please note, however, that at some point the eclass may apply additional distutils patches/quirks independently of this variable.

Example:

PATCHES=( "${FILESDIR}"/${P}-make-gentoo-happy.patch )

DOCS

An array containing documents installed using dodoc. The files listed there must exist in the directory from which distutils-r1_python_install_all() is run (${S} by default).

If unset, the function will instead look up files matching default filename pattern list (from the Package Manager Specification), and install those found.

Example:

DOCS=( NEWS README )

HTML_DOCS

An array containing documents installed using dohtml. The files and directories listed there must exist in the directory from which distutils-r1_python_install_all() is run (${S} by default).

If unset, no HTML docs will be installed.

Example:

HTML_DOCS=( doc/html/. )

EXAMPLES

An array containing examples installed into 'examples' doc subdirectory. The files and directories listed there must exist in the directory from which distutils-r1_python_install_all() is run (${S} by default).

The 'examples' subdirectory will be marked not to be compressed automatically.

If unset, no examples will be installed.

Example:

EXAMPLES=( examples/. demos/. )

DISTUTILS_IN_SOURCE_BUILD

If set to a non-null value, in-source builds will be enabled. If unset, the default is to use in-source builds when python_prepare() is declared, and out-of-source builds otherwise.

If in-source builds are used, the eclass will create a copy of package sources for each Python implementation in python_prepare_all(), and work on that copy afterwards.

If out-of-source builds are used, the eclass will instead work on the sources directly, prepending setup.py arguments with files in the specific root.

DISTUTILS_NO_PARALLEL_BUILD

If set to a non-null value, the parallel build feature will be disabled.

When parallel builds are used, the implementation-specific sub-phases for selected Python implementation will be run in parallel. This will increase build efficiency with distutils which does not do parallel builds.

This variable can be used to disable the afore-mentioned feature in case it causes issues with the package.

mydistutilsargs

An array containing options to be passed to setup.py.

Example:

python_configure_all() {
        mydistutilsargs=( --enable-my-hidden-option )
}

 

AUTHORS

Author: Michał Górny <mgorny@gentoo.org>
Based on the work of: Krzysztof Pawlik <nelchael@gentoo.org>

 

MAINTAINERS

Python team <python@gentoo.org>

 

REPORTING BUGS

Please report bugs via http://bugs.gentoo.org/  

FILES

/usr/portage/eclass/distutils-r1  

SEE ALSO

ebuild(5)

http://sources.gentoo.org/eclass/distutils-r1?view=log

---

 

Index

NAME

DESCRIPTION

FUNCTIONS

ECLASS VARIABLES

AUTHORS

MAINTAINERS

REPORTING BUGS

FILES

SEE ALSO

---

This document was created by man2html, using the manual pages.
Time: 03:25:01 GMT, May 20, 2013