Qt3D Reference Documentation

Building Qt3D for Qt 4

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 Qt SDK. Obtaining Qt 5 source is explained on the Qt project pages.

Qt3D Binary Packages

Do you have to build Qt3D for Qt 4? 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 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 qt/qt3d.git. Note that you'll need the qt4 branch.

It can be cloned as follows:

 $ 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

Note that the $ above means the shell prompt (don't type the $).

More stable versions of the Qt3D source code is available as source packages from Qt3D downloads page. Just unzip or untar it into your source directory.

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 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.

Note: Don't build Qt3D against binary package. As just explained, when building against a binary package Qt3D will try to install itself during compile time into the Qt against which it is being compiled. It cannot do this if your current user account does not have permissions to write there, which is generally the case with binary packages, that install as root into the standard system locations.

In the case of Windows many do development in an account that has Administrator privileges. This is not an endorsement of that practice, but it does mean that Windows users developing this way do not run into this problem. However in the case of Mac or Linux (or more security conscious Windows developers) this won't work. For advanced users you can try buiding with the package option turned on by adding CONFIG+=package to the qmake line, and then run make install as root. It is not recommended to run the whole build as root. In summary, build against a source package or against the SDK and it will just work.

Here's an example configure line you can use:

 $ 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

...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.

Building Qt3D Using QtCreator / QtSDK

Here is a step-by-step guide to building Qt3D using the 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.

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
  • Do not accept the Harmattan Wizard's offer to create deployment files for the project.

Step 1 - Open the Qt3D project.

Choose Open from the File menu and navigate to the qt3d.pro project file $HOME/source/qt/qt3d/qt3d.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.

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.

Step 3 - Set up for Building.

Click the projects tab at the left to display the Qt3D target's Build Settings pane, marked in the screenshot below.

Click the projects tab at the left to display the Qt3D 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 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.

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 -j 4 argument to make.

Do this by expanding the details of the make step in the projects page, then enter the extra arguments, as shown below.

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").

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)

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. 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.

Congratulations on building Qt3D!

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 Deploy Project Qt3D from the Build menu. This step will cause the SDK to copy the harmattan support files from the qtc_harmattan directory of the Qt3D sources into $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:

  • libqt4-3d_1.0-rc_armel.deb
  • libqt4-3d-examples_1.0-rc_armel.deb
  • libqt4-3d-dev_1.0-rc_armel.deb

The first of these 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 below your build directory. If you want to deploy the examples to your N9, you can do this with ssh from the command line.

Building from the Command Line

On Linux assuming that you have built Qt 4.8 in $HOME/build/qt/4.8, you would configure and build Qt3D as follows:

 $ 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

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\qt3d && cd \build\qt\qt3d
 qmake \source\qt\qt3d\qt3d.pro

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:

 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

Once you have built Qt 3D, you can run the "teapot" example:

 $ cd $HOME/build/qt/qt3d
 $ bin/teapot

If all goes well, you should see something like the following on the screen:

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.

Return to the main Qt3D page or Continue to the Tutorials and Examples.