Qt4-based Ebuild HowTo

1. Choosing eclass and EAPI version

The first step for your shiny Qt4-based ebuild, is to specify the right EAPI. Current eclass is EAPI 2 compatible, so all you need to do is

Code Listing 1.1: Specify correct EAPI version

EAPI="2"

That was the most important step for your ebuild.

Inherit qt4 eclass

All qt4 based ebuilds, can use qt4 eclass which provides usefull tools and operation (listed below) for building qt4 applications.

Code Listing 1.2: Inherit qt4 eclass

inherit qt4

2. Dependencies and Use flags

Depend on qt4 split packages

Since Qt-4.4.0, Gentoo Qt team, splits monolithic Qt4 package into smaller packages. Those are

x11-libs/qt-assistant
x11-libs/qt-core
x11-libs/qt-dbus
x11-libs/qt-demo
x11-libs/qt-gui
x11-libs/qt-opengl
x11-libs/qt-phonon
x11-libs/qt-qt3support
x11-libs/qt-script
x11-libs/qt-sql
x11-libs/qt-svg
x11-libs/qt-test
x11-libs/qt-webkit
x11-libs/qt-xmlpatterns

Now all you need to do, is to specify the correct modules on DEPEND variable

Code Listing 2.1: Simple example to demonstrate proper qt4 split dependencies usage

DEPEND="x11-libs/qt-gui:4
	x11-libs/qt-sql:4"

Warning: Even though there is a qt4 metapackage, you must NOT use it as a dependency.

Debug and Release scope

Qt offers you the ability to build your applications using two different modes:

Release: Leads to smaller binaries, usefull for the production state.
Debug: Leads to bigger binaries, usefull for debugging during development process.

Thus, qt4 eclass can use the 'debug' use flag in order to build your application with debug symbols.

Code Listing 2.2: Add 'debug' use flag

	IUSE="debug"

In case 'debug' use flag is present on IUSE, you must adjust the qt dependencies accordingly

Code Listing 2.3: Adjusted qt4 dependencies

	DEPEND="x11-libs/qt-gui:4[debug?]
		x11-libs/qt-sql:4[debug?]"

Important: 'debug' use flag usage implies that you have already followed the "How to get meaningful backtraces in Gentoo" tutorial.

3. Preparing the package

src_prepare function

EAPI2 introduced the src_prepare function which is executed right after src_unpack. The default implementation does nothing. Most of the time, you wont need to use this function at all. Patches are applied automatically via autopatcher

Applying patches

Qt4 eclass uses the base eclass autopatcher in order to apply patches. All you have to do is to specify which patches you want to apply using PATCHES variable

Code Listing 3.1: Simple example for using PATCHES variable

PATCHES=(
	"${FILESDIR}/fixconfig.patch"
	"${FILESDIR}/fixgui.patch"
)

Important: Please note that PATCHES is an array, so you will always need to includes patches between parenthesis.

4. Configure the sources

The 'magic' eqmake4 tool

We provide a special function for configuring Qt4 project files. That is eqmake4 which is provided by qt4 eclass. It is based on qmake, plus it uses default Qt variables for proper package configuration. Packages should be configured under src_configure function.

Code Listing 4.1: Simple example for src_configure function

src_configure() {
	eqmake4
}

Important: eqmake4 does not need a 'die' statement.

There are some rare occasions where eqmake4 fails, but qmake works. Please fill a bug about this in order to take care of it

5. Installation

src_install function

Most Qt4 packages use INSTALL_ROOT variable instead of DESTDIR on their Makefiles. Make sure not to use DESTDIR on src_install, otherwise you will end up with Access violation errors. Below there is an example src_install for most Qt4 packages

Code Listing 5.1: Simple example for src_install function

src_install() {
	emake INSTALL_ROOT="${D}" install || die "emake install failed"
	dodoc README AUTHORS || die "dodoc failed"
}

The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.

Updated June 26, 2009

Summary: This guide is intented to give an overview of how to create a Qt4-based ebuild. It will assist users to write proper ebuilds for Qt4 based packages. using Gentoos' qt4 eclass and splitted Qt4 dependencies

Markos Chandras
Author

Donate to support our development efforts.