/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the Qt3D documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** 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.  Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page qt3d-building.html
    \title Building Qt 3D
    \keyword Building Qt 3D

    \section1 Qt 3D Binary Packages

    Do you have to build \l{Qt 3D}?  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 Qt 3D either from a source package
    or from a repository snapshot.

    \section1 Obtaining Qt 3D sources

    If you want to work with the latest bleeding edge Qt 3D features, or if
    you would like to modify or contribute to Qt 3D you can build it from
    our source repository.

    The source for Qt 3D is hosted on Gitorious as the git repository
    \l{http://qt.gitorious.org/qt/qt3d}{\c{qt/qt3d.git}}.
    It can be cloned as follows:

    \code
    $ mkdir -p $HOME/depot/qt
    $ cd $HOME/depot/qt
    $ git clone git://gitorious.org/qt/qt3d.git
    \endcode

    More stable versions of the Qt 3D source code is available as source
    packages from \l{ftp://ftp.qt.nokia.com/qt3d/noarch}{Qt 3D downloads page}.
    Just unzip or untar it into your \c{depot} directory.

    \section1 Building Qt 3D

    The latest version of Qt 3D requires Qt 5.0.  The QtSDK currently ships with Qt 4.8 so
    you will need to \l{http://developer.qt.nokia.com/wiki/Building_Qt_5_from_Git}{build from Git}.

    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 Qt 3D 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.

    If you're working with Qt4.8.x, and want to use Qt 3D, you will need to check-out the
    qt4 branch for Qt 3D.  After the git clone command earlier, checkout the qt4 code branch
    by running:

    \code
    $ git checkout --track -b qt4 origin/qt4
    \endcode

    Instructions for building against Qt4 are fundamentally the same as for Qt5 (except that
    wherever we select Qt5 in these instructions, you should use Qt4.8), however
    you should make and review the docs provided in the qt4 branch for accuracy.

    \section1 Building Qt 3D Using QtCreator / QtSDK

    Here is a step-by-step guide to building Qt 3D 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.

    \image build-qt3d-qtcreator-1.png

    \b{Step 1} - Open the Qt 3D project.

    Choose \c{Open} from the \c{File} menu and navigate to the qt3d.pro project
    file \c {$HOME/depot/qt/qt3d/qt3d.pro}.  Click \c{Open}.

    \image build-qt3d-qtcreator-2.png

    \b{Step 2} - Select the Qt and load Qt 3D.

    \image build-qt3d-qtcreator-3.png

    Set the Qt5 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 Qt5 version created above.  You may need to add it using the "Manage" button first.

    After a short time QtCreator will have loaded up the Qt 3D project, read all its
    project files and display the source tree as shown below.

    \image build-qt3d-qtcreator-4.png

    \b{Step 3} - Set up for Building.

    Click the projects tab at the left to display the Qt 3D target's \c{Build Settings}
    pane, marked in the screenshot below.

    \image build-qt3d-qtcreator-5.png

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

    \b{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 Qt 3D to a release build also.  One way to tell that this has gone wrong is
    that your Qt 3D 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

    \b{Step 4} - Build Qt 3D and run a test App.

    By default the Qt build system used by QtCreator will build Qt 3D in debug mode.

    Now hit the build button (marked with a red arrow in the screenshot below)

    \image build-qt3d-qtcreator-8.png

    Qt 3D 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 Qt 3D'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.

    Qt 3D 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 Qt 3D 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 Qt 3D'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 Qt 3D!

    \section1 Building from the Command Line

    On Linux assuming that you have built Qt 5 in
    \c{$HOME/build/qt5}, you would configure and build Qt 3D as follows:

    \code
    $ cd $HOME/build/qt5
    $ make module-qt3d
    $ make -j 4
    $ bin/basket
    \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
    cd \build\qt5
    nmake module-qt3d
    bin\basket
    \endcode

    These commands for Windows assume that your Qt build for Qt5 is in
    the current PATH - so that the qmake invoked above is actually going to
    be the Qt5 qmake.

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

    \code
    $ cd $HOME/build/qt5/qt3d
    $ bin/teapot
    \endcode

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

    \image teapot-screenshot.png

    Qt 3D 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{Qt 3D}{Return to the main Qt 3D page} or
    \l{Qt 3D Tutorials and Examples}{Continue to the Tutorials and Examples}.
*/
