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
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
|
/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the Qt3D documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qt3d-building.html
\title Building Qt3D for Qt 4
\keyword Building Qt3D
\section1 This is Qt3D for Qt 4.
If you're looking for Qt 3D on Qt 5, please check for a recent Qt 5
release or source package, as Qt 3D is now a Qt 5 Essential and ships as
part of Qt 5 and the \l{http://qt.nokia.com/downloads}{Qt SDK}. Obtaining
Qt 5 source is explained on \l{http://qt-project.org/wiki/Building_Qt_5_from_Git}{the Qt project pages}.
\section1 Qt3D Binary Packages
Do you have to build Qt3D for Qt 4? Check if binary packages are available
for your platform on the \l{http://qt.nokia.com/downloads}{Qt downloads page}.
This page gives guidelines on how to build Qt3D either from a source package
or from a repository snapshot.
\section1 Obtaining Qt3D sources
If you want to work with the latest bleeding edge Qt3D features, or if
you would like to modify or contribute to Qt3D you can build it from
our source repository.
The source for Qt3D is hosted on Gitorious as the git repository
\l{http://qt.gitorious.org/qt/qt3d}{\c{qt/qt3d.git}}. Note that you'll
need the \c{qt4} branch.
It can be cloned as follows:
\code
$ mkdir $HOME/source/qt && cd $HOME/source/qt
$ git clone git://gitorious.org/qt/qt3d.git qt3d
$ cd qt3d
$ git checkout --track -b qt4 origin/qt4
\endcode
Note that the \c{$} above means the shell prompt (don't type the \c{$}).
More stable versions of the Qt3D source code is available as source
packages from \l{ftp://ftp.qt.nokia.com/qt3d/noarch}{Qt3D downloads page}.
Just unzip or untar it into your \c{source} directory.
\section1 Building Qt3D for Qt 4
This version of Qt3D requires Qt 4.8. The QtSDK currently ships with
Qt 4.8 so if you're using the SDK you should be fine. Alternatively you can build
against a Qt that you have compiled from source. Just make sure that
when you build Qt, that you use the -developer-build option, and do not
do a \c{make install} as root. The reason for this is when Qt3D builds
it will place the libraries, headers and plugins into the correct position
in the hosted Qt library, so that will need to be writable.
Here's an example configure line you can use:
\code
$ mkdir -p $HOME/build/qt/4.8 && cd $HOME/build/qt/4.8
$ $HOME/source/qt/4.8/configure -developer-build -no-qt3support -no-webkit \
-no-phonon -opengl -declarative -nomake demos -nomake examples
$ make
\endcode
...this line turns off many features that aren't needed for Qt3D, and
it also explicitly asks for declarative and opengl (even though those are
on by default) so that an error will be generated if OpenGL is not available.
If you're on windows omit the -opengl as it can cause errors.
Once you have your Qt 4 set up, you can go ahead and build Qt 3D. The recommended
way is to use QtCreator, which you'll have if you downloaded the SDK.
\section1 Building Qt3D Using QtCreator / QtSDK
Here is a step-by-step guide to building Qt3D using the
\l{http://qt.nokia.com/products/appdev/developer-tools/developer-tools}{QtCreator IDE}.
QtCreator is the development environment for the QtSDK. As you can see in the screenshot
below, we're using the beta version 2.5 on Linux, but other operating systems and
versions should look similar. Always use the latest release of QtCreator if possible.
\bold{Special note: Harmattan SDK.} When using the Harmattan support in the Qt SDK:
\list
\o in Step 2 below ensure you choose the appropriate Qt Build eg \c{Meego 1.2 Harmattan API}; and
\o in Step 3 under \c{Build Steps > QMake > Additional arguments} add in \c{CONFIG+=qtc_harmattan}
\o Do \bold{not} accept the Harmattan Wizard's offer to create deployment files for the project.
\endlist
\image build-qt3d-qtcreator-1.png
\bold{Step 1} - Open the Qt3D project.
Choose \c{Open} from the \c{File} menu and navigate to the qt3d.pro project
file \c {$HOME/source/qt/qt3d/qt3d.pro}. Click \c{Open}.
\image build-qt3d-qtcreator-2.png
\bold{Step 2} - Select the Qt and load Qt3D.
\image build-qt3d-qtcreator-4.png
Set the Qt build to use, making sure it has OpenGL and QtDeclarative. In this
situation where I have a large number of Qt versions to choose from it is
easiest to use the "Uncheck All" button, then check the one I want - which is the
Qt that ships with the QtSDK.
If you can't tell from the screen above which is the right Qt to use, just
choose a safe looking one, perhaps the default, as you can change it easily
below.
\image build-qt3d-qtcreator-3.png
Set the Qt build that you created above. In the screenshot below there is a
situation where we have a number of Qt versions to choose from, so it is
easiest to uncheck all of the ones we don't need, then check the one we want - which
is the Qt version created above. You may need to add it using the "Manage" button first.
After a short time QtCreator will have loaded up the Qt3D project, read all its
project files and display the source tree as shown below.
\image build-qt3d-qtcreator-4.png
\bold{Step 3} - Set up for Building.
Click the projects tab at the left to display the Qt3D target's \c{Build Settings}
pane, marked in the screenshot below.
\image build-qt3d-qtcreator-5.png
Click the projects tab at the left to display the Qt3D target's \c{Build Settings}
pane. Here you can specify a Shadow Build directory. It is always a good idea to
build in a shadow directory, instead of inside the source tree.
In the screenshot below we use file management windows invoked by the the browse button to create
the shadow build directory as a "new folder", which we'll call "qt3d" to match the project name.
\image build-qt3d-qtcreator-6.png
Here's another handy trick - set QtCreator to use multiple cores when it builds, if its supported
on your platform. On Mac and other platforms that use GCC I can set the \c{-j 4} argument to \c{make}.
Do this by expanding the details of the make step in the projects page, then enter the extra arguments,
as shown below.
\image build-qt3d-qtcreator-7.png
For Windows check for the \c{jom} tool which you will already be using automatically, to see how many
parallel jobs your build will use.
\bold{Special note for Windows} - make sure that the type of build matches the
Qt that you are building against. In the case of binary packages, and the Qt
that ships with the SDK these are binary release builds - so in those cases set
your Qt3D to a release build also. One way to tell that this has gone wrong is
that your Qt3D library will be called \c{Qt3Dd.dll} (note the lower case "d"
for debug) when your QtGui library is called \c{QtGui4.dll} (no lower case "d").
\image build-qt3d-qtcreator-set-to-release.png
\bold{Step 4} - Build Qt3D and run a test App.
By default the Qt build system used by QtCreator will build Qt3D in debug mode.
Now hit the build button (marked with a red arrow in the screenshot below)
\image build-qt3d-qtcreator-8.png
Qt3D will go ahead and compile all its libraries, plugins and QML imports.
The build is set up so that these will be placed into the directories as specified
by the host qmake - inside the Qt build tree. To find what these directories are run
\c{qmake -query}. If you like after the build you can check those directories to be sure
that Qt3D's files got placed there correctly.
As explained above for this reason you will need to have the privileges on your
computer to write to the directories given by \c{qmake -query}. On Windows this is
generally not a problem. On Mac and Linux it should work fine when building with the
SDK which is by default installed in your home directory. It will also be fine
with builds from a source package.
Qt3D will also place its \c{qt3d.prf} and \c{qt3dquick.prf} files into the
host Qt's QMAKE_MKSPECS/features directory. Again see \c{qmake -query} for what
that directory is on your system. This means that you can write Qt3D applications
in C++ that use the libraries by simply adding \c{CONFIG += qt3d} to your
.pro file.
If you get early errors about not being able to copy the .prf files then check
that you have set up QtCreator to use a Qt that you can write to.
The build will then continue on and compile all of Qt3D's examples and demos,
using the libraries as installed. When finished a message like "The process /usr/bin/make
exited normally" should be displayed.
There is no need to run a make install step.
Now you can use QtCreator to run one of the examples. You can do this by right clicking on
the example you want to run in the build tree (in this case, the "basket" app), then clicking
the green arrow bottom to actually launch the app.
\image build-qt3d-qtcreator-9.png
Congratulations on building Qt3D!
\bold{If you built for Harmattan - N9}. Now you'll want to go ahead and create some
packages for your device. Ensure you have your device correctly set up for use within
QtCreator, by activating the device wizard under the Tools > Options or Preferences menu.
Now right choose \c{Deploy Project Qt3D} from the \c{Build} menu. This step will
cause the SDK to copy the harmattan support files from the qtc_harmattan directory of
the Qt3D sources into \c{$BUILD/debian} and then proceed to create the 3 debian packages
which are specified there, by the *.install files and the rules file. When its
complete 3 package files will have been created:
\list
\o libqt4-3d_1.0-rc_armel.deb
\o libqt4-3d-examples_1.0-rc_armel.deb
\o libqt4-3d-dev_1.0-rc_armel.deb
\endlist
The first of these \c{libqt4-3d_1.0-rc_armel.deb} which provides all the Qt 3D
functionality including QML support has been deployed to the phone. The other two are
in the directory \bold{below} your build directory. If you want to deploy the examples
to your N9, you can do this with ssh from the command line.
\section1 Building from the Command Line
On Linux assuming that you have built Qt 4.8 in
\c{$HOME/build/qt/4.8}, you would configure and build Qt3D as follows:
\code
$ mkdir -p $HOME/build/qt/qt3d && cd $HOME/build/qt/qt3d
$ $HOME/build/qt/4.8/bin/qmake $HOME/source/qt/qt3d/qt3d.pro
$ make -j 4
\endcode
Note that the \c{$} above means the shell prompt (don't type the \c{$}).
The last line runs the example QML application \c{moon} to check that
the build went OK.
On Windows (with Visual Studio) those commands look like this:
\code
mkdir \build\qt\qt3d && cd \build\qt\qt3d
qmake \source\qt\qt3d\qt3d.pro
nmake
\endcode
These commands for Windows assume that your Qt build for Qt 4.8 is in
the current PATH - so that the qmake invoked above is actually going to
be the Qt 4.8 qmake.
On Symbian (with RVCT) those commands look like this:
\code
mkdir C:\source\qt\qt3d
cd C:\source\qt\qt3d
qmake CONFIG+=old_importer
sbs -c armv5_urel
cd devices\symbian
createpackage Qt3D_template.pkg release-armv5
runonphone --sis Qt3D.sis
\endcode
Once you have built Qt 3D, you can run the "teapot" example:
\code
$ cd $HOME/build/qt/qt3d
$ bin/teapot
\endcode
If all goes well, you should see something like the following
on the screen:
\image teapot-screenshot.png
Qt3D has been tested with Qt/X11 and Qt/Embedded under Linux, on MacOSX
and Windows XP. It also runs on Symbian^3 and MeeGo/Maemo.
Patches for other platforms are welcome.
\l{index.html}{Return to the main Qt3D page} or
\l{qt3d-examples.html}{Continue to the Tutorials and Examples}.
*/
|