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
|
/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the QtQuick3D documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the Technology Preview License Agreement accompanying
** this package.
**
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qt3d-building.html
\title Building QtQuick3D
\keyword Building QtQuick3D
\section1 QtQuick3D Binary Packages
Do you have to build QtQuick3D? 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 QtQuick3D sources
If you want to work with the latest bleeding edge QtQuick3D features, or if
you would like to modify or contribute to QtQuick3D you can build it from
our source repository.
The source for QtQuick3D is hosted on Gitorious as the git repository
\l{http://qt.gitorious.org/qt-labs/quick3d}{\c{qt-labs/quick3d.git}}.
It can be cloned as follows:
\code
$ mkdir -p $HOME/depot/qt
$ cd $HOME/depot/qt
$ git clone git://gitorious.org/qt-labs/quick3d.git
\endcode
More stable versions of the QtQuick3D source code is available as source
packages from \l{http://qt.nokia.com/downloads}{Qt downloads page}.
\section1 Building QtQuick3D
QtQuick3D requires Qt 4.7. The QtSDK currently ships with Qt 4.7 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 in
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.7 && cd $HOME/build/qt/4.7
/path/to/qt/configure -developer-build -no-qt3support -no-webkit -no-xmlpatterns \
-no-phonon -opengl -declarative -nomake demos -nomake examples
make
\endcode
...this line turns off many features that aren't needed for QtQuick3D, 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.
\section1 Building QtQuick3D Using QtCreator / QtSDK
Here is a step-by-step guide to building QtQuick3D using the
\l{http://qt.nokia.com/products/appdev/developer-tools/developer-tools}{QtCreator IDE}.
QtCreator is the development environment for the QtSDK. Here we're using
version 2.0 on Mac OSX, but other operating systems and versions should
look similar. Always use the latest release of QtCreator if possible.
\image build-qt3d-qtcreator-1.png
\bold{Step 1} - Open the QtQuick3D project.
Choose \c{Open} from the \c{File} menu and navigate to the quick3d.pro project
file \c {$HOME/depot/qt/quick3d/quick3d.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
After a short time QtCreator will have loaded up the Qt3D project, read all its
project files and display the source tree as shown just above.
\bold{Step 2a} - Useful Options
Use \c{QtCreator} -> \c{Preferences...} to bring up QtCreators options and settings.
On Windows its \c{Tools} -> \c{Options...}.
Make sure you have QtCreator set to display the compile process, so you can check
what any errors may be. The other options are set how I like them, and may suit
your use too. Give them a try, as shown in this screenshot just below.
\image build-qt3d-qtcreator-7.png
\bold{Step 3} - Set up for Building.
\image build-qt3d-qtcreator-5.png
Click the projects tab at the left to display the QtQuick3D 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 just above I use the Finder (Mac's equivalent to the Windows File
Manager) to create the shadow build directory as a "new folder".
\image build-qt3d-qtcreator-6.png
In this screenshot, I have renamed the "new folder" to match the shadow build directory
name that I gave QtCreator. Now I'm ready to click the "Build" button - circled in
red in the bottom left hand corner of Qt Creators main screen.
\image build-qt3d-qtcreator-8.png
Before you do that here's a 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}. 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.
\image build-qt3d-qtcreator-set-to-release.png
\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").
By default the Qt build system used by QtCreator will build Qt3D in debug mode.
Ok, \b{now} hit the build button.
\bold{Step 4} - Build QtQuick3D and run a test App.
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.
\image build-qt3d-qtcreator-9.png
Now you can use QtCreator to run one of the examples. Click the button for the
project switcher (circled in red) and then choose one of the apps. Here we
have chosen the QML "Moon" app from the menu (indicated by the red arrow).
Click the green arrow bottom left to actually launch the "Moon" app.
Congratulations on building Qt3D!
\section1 Building from the Command Line
On Linux assuming that you have built Qt 4.7 in
\c{$HOME/build/qt/4.7}, you would configure and build QtQuick3D as follows:
\code
$ mkdir -p $HOME/build/qt/quick3d
$ cd $HOME/build/qt/quick3d
$ $HOME/build/qt/4.7/bin/qmake $HOME/depot/qt/quick3d/quick3d.pro
$ make -j 4
$ bin/moon
\endcode
Note that the \c{$} above means the shell prompt (don't type the \{$}).
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\quick3d
cd \build\qt\quick3d
qmake \depot\qt\quick3d\quick3d.pro
nmake
bin\moon
\endcode
These commands for Windows assume that your Qt build for Qt 4.7 is in
the current PATH - so that the qmake invoked above is actually going to
be the Qt 4.7 qmake.
On Symbian (with RVCT) those commands look like this:
\code
mkdir C:\depot\qt\quick3d
cd C:\depot\qt\quick3d
qmake CONFIG+=old_importer
sbs -c armv5_urel
cd devices\symbian
createpackage QtQuick3D_template.pkg release-armv5
runonphone --sis QtQuick3D.sis
\endcode
Once you have built QtQuick3D, you can run the "teapot" example:
\code
$ cd $HOME/build/qt/quick3d
$ bin/teapot
\endcode
If all goes well, you should see something like the following
on the screen:
\image teapot-screenshot.png
QtQuick3D 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 QtQuick3D page} or
\l{qt3d-examples.html}{Continue to the Tutorials and Examples}.
*/
|
