1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/desktop/qt/qt4-based-ebuild-howto.xml,v 1.5 2010/08/15 22:28:22 hwoarang Exp $ -->
<guide link="/proj/en/desktop/qt/qt4-ebuild-howto.xml" lang="en">
<title>Qt4-based ebuild howto</title>
<author title="Author">
<mail link="hwoarang" />
</author>
<author title="Author">
<mail link="ayoy" />
</author>
<author title="Editor">
<mail link="yngwin"/>
</author>
<abstract>
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.
</abstract>
<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>
<version>0.6.1</version>
<date>2010-07-14</date>
<chapter>
<title>Introduction</title>
<section>
<title>Purpose of this howto</title>
<body>
<p>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.</p>
</body>
</section>
</chapter>
<chapter>
<title>Required variables, inheriting eclass and EAPI version</title>
<section>
<title>Valid EAPI version</title>
<body>
<p>The first step for your shiny Qt4-based ebuild is to specify the
right EAPI. The current eclass is compatible with EAPI 2 and 3
<b>only</b>, so you have to use one of these when inheriting qt4-r2
eclass.</p>
<pre caption="Specify correct EAPI version">
EAPI="3"</pre>
</body>
</section>
<section>
<title>Inherit qt4-r2 eclass</title>
<body>
<p>All Qt4 qmake-based ebuilds should use qt4-r2 eclass, which provides
usefull tools and features (listed below) for building Qt4 applications.
</p>
<pre caption="Inheriting qt4-r2 eclass">
inherit qt4-r2</pre>
<warn>
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.
</warn>
</body>
</section>
<section>
<title>Language variables</title>
<body>
<p>
In case your ebuild provides translations, you should populate the IUSE
variable with appropriate <c>linguas_*</c> 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.</p>
<p>Our qt4-r2 eclass provides two special variables for this purpose.
<c>LANGS</c> and <c>LANGSLONG</c> are meant to ease up <c>linguas_*</c>
USE flags population. All you have to do is set <c>LANGS</c> to a list
of translation languages for your package (using language codes as
specified in <path>${PORTDIR}/profiles/desc/linguas.desc</path>).</p>
<p>Some applications provide translation files with languages specified
together with a country code (e.g. <path>myapp_de_DE.ts</path>). That
is not always the proper solution from a Gentoo point of view, since
e.g. "de_DE" is an invalid <c>LINGUAS</c> member. If your package's
translation files contain language codes incompatible with those used
by Gentoo, the <c>LANGSLONG</c> variable might help you a bit. It will
cut off the country code from the language when populating
<c>linguas_*</c> IUSE. This way you can use an incompatible language
code to refer to the translation file, but still you're sure that
<c>linguas_*</c> use flag is specified correctly.</p>
<pre caption="Example of defining languages">
LANGS="de es fr_CA hu pt_BR zh_CN"
LANGSLONG="cs_CZ fr_FR pl_PL"</pre>
<p>This example results in the following expanded IUSE set:</p>
<pre caption="Resulting IUSE">
IUSE="linguas_cs linguas_de linguas_es linguas_fr linguas_fr_CA linguas_hu
linguas_pl linguas_pt_BR linguas_zh_CN"</pre>
<impo>
In order for automatic <c>linguas_*</c> IUSE generation to work,
<c>LANGS</c> and <c>LANGSLONG</c> <b>must</b> be set before inheriting
qt4-r2 eclass.
</impo>
</body>
</section>
</chapter>
<chapter>
<title>Dependencies and USE flags</title>
<section>
<title>Depend on Qt4 split packages</title>
<body>
<p>Since Qt-4.4.0 the Gentoo Qt team splits the monolithic Qt4 package
into smaller packages. Those are</p>
<ul>
<li> x11-libs/qt-assistant</li>
<li> x11-libs/qt-core</li>
<li> x11-libs/qt-dbus</li>
<li> x11-libs/qt-declarative</li>
<li> x11-libs/qt-demo</li>
<li> x11-libs/qt-gui</li>
<li> x11-libs/qt-multimedia</li>
<li> x11-libs/qt-opengl</li>
<li> x11-libs/qt-phonon</li>
<li> x11-libs/qt-qt3support</li>
<li> x11-libs/qt-script</li>
<li> x11-libs/qt-sql</li>
<li> x11-libs/qt-svg</li>
<li> x11-libs/qt-test</li>
<li> x11-libs/qt-webkit</li>
<li> x11-libs/qt-xmlpatterns</li>
</ul>
<p>Now all you need to do, is to specify the correct modules in the DEPEND
variable:</p>
<pre caption="Simple example to demonstrate proper qt4 split dependencies usage">
DEPEND="x11-libs/qt-gui:4
x11-libs/qt-sql:4"</pre>
<warn>
Even though there is a <c>x11-libs/qt</c> metapackage, you <b>must NOT</b>
use it as a dependency. We have masked it to prevent that.
</warn>
</body>
</section>
<section>
<title>Debug and Release scope</title>
<body>
<p>Qt offers you the ability to build your applications using two different
modes:</p>
<ul>
<li>Release: Leads to smaller binaries, useful for the normal usage.</li>
<li>Debug: Leads to bigger binaries, useful for debugging during the
development process.</li>
</ul>
<p>Thus, qt4-r2 eclass can use the 'debug' use flag in order to build your
application with debug symbols.</p>
<pre caption="Add 'debug' use flag">
IUSE="debug"</pre>
<impo>
'debug' use flag usage implies that you have already followed the
<uri link="/proj/en/qa/backtraces.xml">"How to get meaningful backtraces in
Gentoo"</uri> tutorial.
</impo>
</body>
</section>
<section>
<title> Package documentation</title>
<body>
<p>There is a special variable to use in case your package provides
documentation files. The <b>DOCS</b> variable can be used by the
<uri link="#doc_chap5_pre1">default src_install function</uri> to install
those documents. Normally the documents are located in the ${S} directory.
If not, set the <b>DOCSDIR</b> variable to match the documents path. If you
don't need to use DOCSDIR variable, then ${S} will be used by default.</p>
<pre caption="Simple example of DOCS variable usage">
DOCSDIR="${S}/docs/"
DOCS="Authors ChangeLog Readme"</pre>
</body>
</section>
</chapter>
<chapter>
<title>Preparing the package</title>
<section>
<title>src_prepare function</title>
<body>
<p>EAPI2 introduced the src_prepare function which is executed right
after src_unpack. The default implementation does nothing.</p>
</body>
</section>
<section>
<title>Applying patches</title>
<body>
<p>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:</p>
<pre caption="Simple example for using the PATCHES array">
PATCHES=(
"${FILESDIR}/fixconfig.patch"
"${FILESDIR}/fixgui.patch"
)</pre>
<impo>
Please note that PATCHES is an array, so you will always need to
includes patches between parentheses.
</impo>
</body>
</section>
</chapter>
<chapter>
<title>Configure the sources</title>
<section>
<title>The 'magic' eqmake4 tool</title>
<body>
<p>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 <b>default src_configure phase</b> 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:</p>
<pre caption="Simple example for src_configure function">
src_configure() {
eqmake4 "${S}"/tool/foo.pro
}</pre>
<impo>
eqmake4 does not need a 'die' statement.
</impo>
<p>There are some rare occasions where eqmake4 fails, but qmake works.
Please file a <uri link="http://bugs.gentoo.org">bug</uri> about this,
in order for us to possibly fix this.</p>
</body>
</section>
</chapter>
<chapter>
<title>Installation</title>
<section>
<title>src_install function</title>
<body>
<p>
The <b>default src_install</b> in qt4-r2 eclass is the following:</p>
<pre caption="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
if [[ -n "${DOCS}" ]]; then
local dir=${DOCSDIR:-${S}}
for doc in ${DOCS}; do
dodoc "${dir}/${doc}" || die "dodoc failed"
done
fi
}</pre>
<p>
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:</p>
<pre caption="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
...
...</pre>
</body>
</section>
</chapter>
</guide>
|
GitWeb