Creating Python-related Ebuilds
Contents |
Quick Start
Progress overlay is now integrated into funtoo-experimental.
Progress Overlay currently contains 400+ packages that implement next-generation Python support for ebuilds. After switching active version of Python, users should change value of PYTHON_ABIS in make.conf, run emerge with -N / --newuse option to reinstall packages with PYTHON_ABIS USE flags and next run python-updater to reinstall old-style packages.
TODO: add cmdline examples
Building Python Modules with Portage
Conceptual Overview
Portage supports the ability to build python modules and extensions for all installed versions of python. This functionality has been implemented by python.eclass.
To use python.eclass, you first want to investigate how python module building is integrated into any included Makefile or build script. Since we want python.eclass to build these modules for us, typically the first step is to tweak the Makefile or configure script to explicitly *not* build python modules. We will be handling that process using python.eclass.
Progress Improvements
The old way: python-updater
With the current python.eclass in Gentoo and Funtoo Linux, python modules are built for all installed versions of python. However, no usable accounting information is stored by Portage so that it can "know" what versions of python the module was built for. This creates a problem when new versions of python are installed, as the new module will not be available for the new python, and Portage will not be aware of what needs to be done to fix this, if anything. This has resulted in the creation of a tool called python-updater to rebuild all necessary python-related ebuilds so that they reflect the currently-installed versions of python.
TODO: add python-updater example
The new way: new python eclass
The new python.eclass from Arfrever has a new API that can be used to write python ebuilds. When this API is used, Portage can track and resolve missing builds of python modules internally, so python-updater is not needed to be used for these ebuilds. However, until all ebuilds are converted to the new API, python-updater will need to be used to update these old-style ebuilds.
python-updater-0.10 doesn't reinstall any packages which set PYTHON_MULTIPLE_ABIS and EAPI="4-python", as manual rebuilding is not necessary.
TODO: document mechanisms, USE, etc. that are used to accomplish this and how it works
Help us document this page so we can help others convert to the new python API from progress overlay :)
Setting up progress overlay
Experimental branch users do not need to perform those steps!
Progress overlay now merged into experimental branch of funtoo-overlay. For master tree overlay can be easily added via layman. Progress overlay is a subversion repository, make sure dev-vcs/subversion is installed
# emerge subversion # layman -a progress
The following changes required for proper overlay work, edit /etc/make.conf
PYTHON_ABIS="2.7 3.2"for python-2.7.x and python-3.2x, respectively.
Notice, that progress overlay including an updated packages that also available in main portage tree!
# python-updaterthis still required to rebuild old-fashion python-related ebuilds
Updating the packages from progress overlay
Package updates are done the same way than before:
emerge -avuDN @world
Several python-related packages should be updated to progress versions, with the new PYTHON_ABIS flags.
Developer Docs
Ebuild Converstion to new Python eclass
Conversion from previous EAPIs and eclasses to the new progress python eclass is fairly straightforward. This section tries to explain the steps.
4-python EAPI
First, set EAPI to 4-python:
EAPI=4-python
Next, you will need to use new-style variables recognized by the new python eclass:
PYTHON_MULTIPLE_ABIS=1
Note the new variable names. PYTHON_MULTIPLE_ABIS turns on the functionality to build multiple versions of python modules for each installed version of python.
When PYTHON_MULTIPLE_ABIS is set and EAPI is set to 4-python, then new USE flags will be automatically added to the IUSE with the python_abis_ prefix. If you want to see what ABIs are supported, see the _PYTHON_GLOBALLY_SUPPORTED_ABIS variable defined in python.eclass.
PYTHON_RESTRICTED_ABIS
PYTHON_RESTRICTED_ABIS variable set in ebuild specifies a space-separated list of patterns of Python ABIs not supported by current package. The settings in PYTHON_RESTRICTED_ABIS will remove certain ABIS from the auto-IUSE expansion that happens when EAPI is set to 4-python and PYTHON_MULTIPLE_ABIS is set to 1 (This behavior is described above.) It will also limit the behavior of the python_abi_depend() function, described below. And of course, it will tell the python eclass to not build any python modules for these python versions, even if they happen to be installed on the system.
Use it like this, before the eclasses are inherited:
</pre> PYTHON_RESTRICTED_ABIS="3.*" </pre>
Note that PYTHON_RESTRICTED_ABIS is a glob-style pattern. If you want to have it build with everything except 3.2 and above and jython, use this pattern:
PYTHON_RESTRICTED_ABIS="3.[2-9] *-jython"
