Qt4-based ebuild howto

1. Introduction

The goal of this document is to introduce the qt4-r2 eclass and provide basic instructions on writing ebuilds for applications that use the Qt4 qmake build system. If you're writing an ebuild for a Qt-based application that uses cmake as a build system, you should take a look at the cmake-utils eclass instead.

2. Required variables, inheriting eclass and EAPI version

Valid EAPI version

The first step for your shiny Qt4-based ebuild is to specify the right EAPI. The current eclass is compatible with EAPI 2, 3 or 4, so you have to use one of these when inheriting qt4-r2 eclass.

Code Listing 2.1: Specify correct EAPI version

EAPI="4"

Inherit qt4-r2 eclass

All Qt4 qmake-based ebuilds should use qt4-r2 eclass, which provides useful tools and features (listed below) for building Qt4 applications.

Code Listing 2.2: Inheriting qt4-r2 eclass

inherit qt4-r2

Warning: There is an old qt4 eclass in the tree. It has been deprecated since 15 December 2009. Please use the qt4-r2 eclass instead, since we plan to drop the old eclass. If you already maintain a Qt4 ebuild which uses the qt4 eclass, please consider migrating to the new eclass as soon as possible.

Language variables

In case your ebuild provides translations, you should populate the IUSE variable with appropriate linguas_* USE flags. When writing ebuilds it is common to group language codes that are part of translation filenames in a variable that is later used to iterate over translations when configuring and/or installing the package.

Our qt4-r2 eclass provides two special variables for this purpose. LANGS and LANGSLONG are meant to ease up linguas_* USE flags population. All you have to do is set LANGS to a list of translation languages for your package (using language codes as specified in ${PORTDIR}/profiles/desc/linguas.desc).

Some applications provide translation files with languages specified together with a country code (e.g. myapp_de_DE.ts). That is not always the proper solution from a Gentoo point of view, since e.g. "de_DE" is an invalid LINGUAS member. If your package's translation files contain language codes incompatible with those used by Gentoo, the LANGSLONG variable might help you a bit. It will cut off the country code from the language when populating linguas_* IUSE. This way you can use an incompatible language code to refer to the translation file, but still you're sure that linguas_* use flag is specified correctly.

Code Listing 2.3: Example of defining languages

LANGS="de es fr_CA hu pt_BR zh_CN"
LANGSLONG="cs_CZ fr_FR pl_PL"

This example results in the following expanded IUSE set:

Code Listing 2.4: Resulting IUSE

IUSE="linguas_cs linguas_de linguas_es linguas_fr linguas_fr_CA linguas_hu
linguas_pl linguas_pt_BR linguas_zh_CN"

Important: In order for automatic linguas_* IUSE generation to work, LANGS and LANGSLONG must be set before inheriting qt4-r2 eclass.

3. Dependencies and USE flags

Depend on Qt4 split packages

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

x11-libs/qt-assistant
x11-libs/qt-core
x11-libs/qt-dbus
x11-libs/qt-declarative
x11-libs/qt-demo
x11-libs/qt-gui
x11-libs/qt-multimedia
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 in the DEPEND variable:

Code Listing 3.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 x11-libs/qt-meta metapackage, you must NOT use it as a dependency. We have masked it to prevent that.

Debug and Release scope

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

Release: Leads to smaller binaries, useful for the normal usage.
Debug: Leads to bigger binaries, useful for debugging during the development process.

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

Code Listing 3.2: Add 'debug' use flag

IUSE="debug"

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

Package documentation

There is a special variable to use in case your package provides documentation files. The DOCS variable can be used by the default src_install function to install those documents. Normally the documents are located in the ${S} directory. If not, set the DOCSDIR variable to match the documents path. If you don't need to use DOCSDIR variable, then ${S} will be used by default.

Code Listing 3.3: Simple example of DOCS variable usage

DOCSDIR="${S}/docs/"
DOCS="Authors ChangeLog Readme"

4. Preparing the package

src_prepare function

EAPI2 introduced the src_prepare function which is executed right after src_unpack. The default implementation does nothing.

Applying patches

The qt4-r2 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 the PATCHES array:

Code Listing 4.1: Simple example for using the PATCHES array

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

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

5. Configure the sources

The 'magic' eqmake4 tool

We provide a special function for configuring Qt4 project files. That is eqmake4, which is provided by the qt4-r2 eclass. It is based on qmake, plus it uses default Qt variables for proper package configuration. Packages should be configured during the src_configure phase. The default src_configure phase finds and configures project files (.pro files) located in the ${S} directory. If there are more than one project files in there, it will try to find the one named ${PN}.pro or $(basename ${PWD}).pro. In case your package uses some weird file hierarchy and you need to configure a project file in a subdirectory, then you can specify the path as a parameter to eqmake4:

Code Listing 5.1: Simple example for src_configure function

src_configure() {
    eqmake4 "${S}"/tool/foo.pro
}

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

There are some rare occasions where eqmake4 fails, but qmake works. Please file a bug about this, in order for us to possibly fix this.

6. Installation

src_install function

The default src_install in qt4-r2 eclass is the following:

Code Listing 6.1: default src_install function

qt4-r2_src_install() {
    debug-print-function $FUNCNAME "$@"

    emake INSTALL_ROOT="${D}" DESTDIR="${D}" install || die "emake install failed"
    # install documentation

    local dir=${DOCSDIR:-${S}}
    for doc in ${DOCS}; do
        dodoc "${dir}/${doc}" || die "dodoc failed"
    done
}

This is the most popular method to install Qt4 packages and their documentation. Rarely you will need to override this function. Usually, you write an extended version of this one, to support translations installation, like the following case:

Code Listing 6.2: extended src_install function

src_install() {
    # do normal installation
    qt4-r2_src_install
    # Install translations
    for X in ${LINGUAS}; do
        for Z in ${LANGS}; do
            ...
            ...

The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.

Page updated February 9, 2012

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-r2 eclass and split Qt4 dependencies.

Markos Chandras
Author

Dominik Kapusta
Author

Ben de Groot
Editor

Donate to support our development efforts.