From Gentoo Wiki
Jump to: navigation, search

python-utils-r1 provides all the common utility functions that are used within all of -r1 suite eclasses. This eclass is seldom (if ever) inherited directly. Instead, its API is exposed via other eclasses.

Python build environment

Introductory information

Python build environment describes the environment setup that is necessary to properly build packages against specific version of Python, or run Python scripts using it. Python build environment consists of a number of environment variables and often a helper directories.

The most minimal Python build environment is established through EPYTHON variable.

Establishing the build environment

Implicit build environment

The Python build environment is initialized implicitly by many other eclasses. The functions which establish it and list of enabled variables are listed in the following table.

Eclass Function Variables
distutils-r1 (sub-phases) EPYTHON, PYTHON, BUILD_DIR, MULTIBUILD_*, PYTHONPATH, executable & pkg-config wrappers
python-r1 python_foreach_impl EPYTHON, PYTHON, BUILD_DIR, MULTIBUILD_*, executable & pkg-config wrappers
python_export_best user-specified variables (default: EPYTHON, PYTHON)
(called directly) python_setup EPYTHON, PYTHON, executable & pkg-config wrappers
python-any-r1 python-any-r1_pkg_setup
python-single-r1 python-single-r1_pkg_setup


Usage: python_export [<impl>] <variable>...

Exports the specified build environment variables. If the first argument specifies a valid Python implementation (either in PYTHON_COMPAT or EPYTHON form), the variables are exported for specified implementation. Otherwise, they are exported for the implementation listed in current value of EPYTHON environment variable.

This command can be used both to initialize a new build environment and to export additional variables for the current build environment. Most of the variables also have getters which can be used instead of python_export.

CODE Example of using python_export
src_configure() {
    python_export PYTHON_SITEDIR
    econf --with-python-sitedir="${PYTHON_SITEDIR}"


Usage: python_wrapper_setup [<path> [<impl>]]

Prepare Python executable and pkg-config file wrappers, and add them to PATH and PKG_CONFIG_PATH (remember to localize the variables before calling!). The wrapper tree will be created in specified directory if any, or otherwise in ${T}/${EPYTHON}. The wrappers will match the implementation passed as second argument or specified in EPYTHON environment variable.

The following wrappers are created:

  • python and python2 or python3 executables,
  • python-config and python2-config or python3-config executables if available,
  • 2to3 executable if available,
  • python.pc and python2.pc or python3.pc pkg-config files if available.


Attempts to export a usable UTF-8 locale in the LC_CTYPE variable. Does nothing if LC_ALL is defined, or if the current locale uses a UTF-8 charmap. This may be used to work around the quirky open() behavior of python3.

Return value: 0 on success, 1 on failure.

Build environment variables


The basename of Python interpreter. Used as main identifier of the active implementation in Gentoo. Affects python-exec and many eclass functions. The preferred way of invoking Python within ebuilds, as it relies on PATH lookup, which among other things is more portable on Gentoo Prefix setups, for instance.

Example values: python2.7, python3.3, pypy-c2.0, jython2.7


The full path to the Python interpreter. Sometimes required by autotools and cmake-based build systems.

Example values: /usr/bin/python2.7, /usr/bin/pypy-c2.0


Getter: python_get_sitedir [<impl>]

The Python interpreter's site-packages directory, the directory where third-party Python modules shall be installed. Includes EPREFIX.

Example value: /usr/lib64/python2.7/site-packages


Getter: python_get_includedir [<impl>]

The Python interpreter's header files directory. This is the directory where implementation-specific headers can be found. Includes EPREFIX.

Example value: /usr/include/python2.7


Getter: python_get_library_path [<impl>]

Full path to the Python interpreter's dynamic library (for linking against Python). Includes EPREFIX. Available for CPython only.

Example value: /usr/lib64/


Getter: python_get_CFLAGS [<impl>]

Getter: python_get_LIBS [<impl>]

Respectively the C compiler build and linking flags for linking against the Python interpreter. Available for CPython only. Requires the implementation to be installed.

In modern CPython versions, uses pkg-config. In Python 2.6, uses python-config.


Getter: python_get_PYTHON_CONFIG [<impl>]

Full path to the python-config utility, with appropriate ABI suffix. Available for CPython only.

Example value: /usr/bin/python3.4m-config

Install functions


Usage: python_doexe <file>...

Usage: python_newexe <file> <new-name>

Usage: python_scriptinto <path>

Install the specified implementation-specific executables. The executables will be wrapped for current Python implementation.

python_newexe can be used to install an executable under new name. python_scriptinto changes the executable install path (defaults to /usr/bin). All paths are implicitly prefixed with EPREFIX.

This function is intended for files other than Python scripts (executables, bash scripts). For Python scripts, python_doscript should be used instead.

CODE Example use of python_doexe
src_install() {
    python_foreach_impl python_doexe


Usage: python_doscript <file>...

Usage: python_newscript <file> <new-name>

Usage: python_scriptinto <path>

Install the specified scripts. The scripts will be wrapped and the shebang on its underlying copy will be adjusted for the current implementation.

python_newscript can be used to install a script under new name. python_scriptinto changes the script install path (defaults to /usr/bin). All paths are implicitly prefixed with EPREFIX.

CODE Example use of python_doscript
src_install() {
    python_foreach_impl python_doscript


Usage: python_domodule <file-or-directory>...

Usage: python_moduleinto <path>

Install the specified Python modules or packages (directories). All Python modules will be byte-compiled. Directories (packages) will be installed recursively, including all files (not only modules).

python_moduleinto changes the module install path. It can either take an absolute path (starting with a slash), or a path relative to site-packages directory. The relative path can either use a slash (/) or a dot (.) as the path separator. The default is to install into site-packages.

CODE Example use of python_domodule
src_install() {
    python_moduleinto foo.barmatic
    python_foreach_impl python_domodule lib/*.py


Usage: python_doheader <file>...

Install the specified header files into implementation-specific header directory. The directory is added to the compiler search path when Python extensions or programs linking against Python are being built.

CODE Example use of python_doheader
python_install() {
    python_doheader libImaging/{Imaging.h,ImPlatform.h}


Usage: python_optimize [<directory>...]

Byte-compile Python modules. If any directories are provided, modules in those directories will be byte-compiled. Otherwise, all directories in Python search path (sys.path) inside D will be used.

All directories need to be specified using absolute paths (including ${D} if appropriate). Python modules inside installation image will be compiled with target filesystem paths embedded (with ${D} stripped).

Other functions


Usage: python_fix_shebang [-f|--force] [-q|--quiet] <path>...

Fixes shebangs in Python scripts to match the current interpreter.

Both files and directories can be specified as paths. If directories are provided, they are processed recursively. Only files with Python shebangs are modified.

If --force is passed, the function will replace shebangs matching incompatible Python implementations. For example, it will replace python2 with python3.4. Otherwise, such an attempt will result in a fatal error.

If --quiet is passed, the function will not output the modified files. Otherwise, it will verbosely report each modified file.

CODE Example use of python_fix_shebang
src_install() {
    python_fix_shebang "${ED}"usr/bin


Usage: python_is_python3 [<impl>]

Determines whether the passed implementation (or ${EPYTHON} if none passed) uses a dialect of Python 3. Returns 0 if it is, 1 otherwise (Python 2 dialect).


Usage: python_is_installed [<impl>]

Determines whether the passed Python implementation (or ${EPYTHON} if none passed) is installed in the system, with USE flags matching PYTHON_REQ_USE. Returns 0 if it is installed, 1 otherwise.