Building QtQuick3D
QtQuick3D Binary Packages
Do you have to build QtQuick3D? Check if binary packages are available for your platform on the Qt downloads page.
This page gives guidelines on how to build Qt3D either from a source package or from a repository snapshot.
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 qt-quick3d/qt-quick3d.git. It can be cloned as follows:
$ mkdir -p $HOME/depot/qt $ cd $HOME/depot/qt $ git clone git://gitorious.org/qt-quick3d/qt-quick3d.git
More stable versions of the QtQuick3D source code is available as source packages from Qt3D downloads page. Just unzip or untar it into your depot directory.
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 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:
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
...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.
Building QtQuick3D Using QtCreator / QtSDK
Here is a step-by-step guide to building QtQuick3D using the 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.
Special note: Harmattan SDK. When using the Harmattan support in the Qt SDK:
- in Step 2 below ensure you choose the appropriate Qt Build eg Meego 1.2 Harmattan API; and
- in Step 3 under Build Steps > QMake > Additional arguments add in CONFIG+=qtc_harmattan
Step 1 - Open the QtQuick3D project.
Choose Open from the File menu and navigate to the quick3d.pro project file $HOME/depot/qt/quick3d/quick3d.pro. Click Open.
Step 2 - Select the Qt and load Qt3D.
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.
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.
Step 2a - Useful Options
Use QtCreator -> Preferences... to bring up QtCreators options and settings. On Windows its Tools -> 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.
Step 3 - Set up for Building.
Click the projects tab at the left to display the QtQuick3D target's 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".
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.
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 -j 4 argument to make. For Windows check for the jom tool which you will already be using automatically, to see how many parallel jobs your build will use.
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 Qt3Dd.dll (note the lower case "d" for debug) when your QtGui library is called QtGui4.dll (no lower case "d").
By default the Qt build system used by QtCreator will build Qt3D in debug mode.
Ok, now hit the build button.
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 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 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 qt3d.prf and qt3dquick.prf files into the host Qt's QMAKE_MKSPECS/features directory. Again see 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 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. 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!
Building from the Command Line
On Linux assuming that you have built Qt 4.7 in $HOME/build/qt/4.7, you would configure and build QtQuick3D as follows:
$ 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
Note that the $ above means the shell prompt (don't type the {$}).
The last line runs the example QML application moon to check that the build went OK.
On Windows (with Visual Studio) those commands look like this:
mkdir \build\qt\quick3d
cd \build\qt\quick3d
qmake \depot\qt\quick3d\quick3d.pro
nmake
bin\moon
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:
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
Once you have built QtQuick3D, you can run the "teapot" example:
$ cd $HOME/build/qt/quick3d $ bin/teapot
If all goes well, you should see something like the following on the screen:
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.
Return to the main QtQuick3D page or Continue to the Tutorials and Examples.