path: root/doc/src/platforms/platform-notes.qdoc

/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the 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$
**
****************************************************************************/

/*!
    \group platform-specific
    \title Platform-Specific Documentation
    \brief Documents describing platform-specific features of Qt.

    These documents describe platform-specific features provided by Qt, and
    discuss issues related to particular platforms and environments.

    \generatelist{related}
*/

/*!
    \page platform-notes.html
    \ingroup platform-specific
    \title Platform and Compiler Notes
    \brief Information about the platforms on which Qt can be used.

    This page contains information about the platforms Qt is currently known
    to run on, with links to platform-specific notes, including any known bugs
    or incompatibilities.

    Information about the combinations of platforms and compilers
    supported by Qt can be found on the \l{Supported Platforms} page.

    \list
    \li \l{Platform and Compiler Notes - X11}
    \tableofcontents{1 Platform and Compiler Notes - X11}
    \li \l{Platform and Compiler Notes - Windows}
    \tableofcontents{1 Platform and Compiler Notes - Windows}
    \li \l{Platform and Compiler Notes - Mac OS X}
    \tableofcontents{1 Platform and Compiler Notes - Mac OS X}
    \li \l{Platform and Compiler Notes - QNX}
    \tableofcontents{1 Platform and Compiler Notes - QNX}
    \li \l{Platform and Compiler Notes - VxWorks}
    \tableofcontents{1 Platform and Compiler Notes - VxWorks}
    \li \l{Platform and Compiler Notes - Android}
    \tableofcontents{1 Platform and Compiler Notes - Android}
    \endlist

    \section1 General Compiler Notes

    \section2 Supported Features

    Qt can be compiled with any compiler that is compliant with the C++98 standard. C++11
    support is automatically enabled on compilers supporting it.

    Building Qt is currently being tested on the following list of compilers:

    \list
    \li gcc 4.2.1 (Mac OS X only)
    \li Apple clang 3.1 (Mac OS X / XCode 4)
    \li gcc 4.5 and newer (Linux)
    \li MSVC 2008 and newer
    \li MingW 4.6
    \li Intel CC (latest version)
    \endlist

*/

/*!
    \page platform-notes-x11.html
    \title Platform and Compiler Notes - X11
    \contentspage Platform and Compiler Notes

    This page contains information about the X11 platforms Qt is currently
    known to run on, with links to platform-specific notes. More information
    about the combinations of platforms and compilers supported by Qt can be
    found on the \l{Supported Platforms} page.

    \tableofcontents

    \section1 Linux

    There are no known problems with using Qt on production versions of
    Linux/x86, Linux/ppc, Linux/amd64 and Linux/ia64 (including Altix(R)).

    For the GCC compiler, please also see the relevant
    \l{Platform and Compiler Notes#General Compiler Notes}{General Compiler Notes}.

    \section2 Installation problems

    If you experience problems when installing new open source versions of Qt
    versions, try to use the open source Qt archives (e.g., RPM)
    provided by your Linux distribution. If you need to install the source (.tgz)
    archive, be aware that you will probably end up with two different
    versions of the Qt library installed on your system, which will probably
    lead to link errors, like this:
    \snippet doc/src/snippets/code/doc_src_platform-notes.qdoc 0
    Fix this by removing the old version of the library.

    If you have problems installing open source versions of Qt
    provided by your Linux distribution (e.g., RPM), please consult the
    maintainers of the distribution, not us.

    Some RPM versions have problems installing some of the Qt RPM archives
    where installation stops with an error message warning about a
    "Failed Dependency". Use the \c{--nodeps} option to \c rpm to workaround
    this problem.

    \section2 Intel C++ Compiler for Linux

    Qt can be compiled with the Intel C++ compile for Linux. The configuration is
    not tested on a regular basis.

    \section2 Known Issues with Intel C++ Compiler for Linux

    \list

    \li Precompiled header support does not work in version 10.0.025
       and older. For these compilers, you should configure Qt with
       -no-pch. Precompiled header support works properly in version
       10.0.026 and later.
    \li Version 10.0.026 for Intel 64 is known to miscompile qmake when
       building in release mode. For now, configure Qt with
       -debug. Version 10.1.008 and later can compile qmake in release
       mode.
    \li Versions 10.1.008 to 10.1.015 for both IA-32 and Intel 64 are
       known crash with "(0): internal error: 0_47021" when compiling
       QtXmlPatterns, QtWebKit, and Designer in release mode. Version
       10.1.017 compiles these modules correctly in release mode.
    \endlist

*/

/*!
    \page platform-notes-windows.html
    \title Platform and Compiler Notes - Windows
    \contentspage Platform and Compiler Notes

    This page contains information about the Windows platforms Qt is currently
    known to run on, with links to platform-specific notes. More information
    about the combinations of platforms and compilers supported by Qt can be
    found on the \l{Supported Platforms} page.

    \tableofcontents

    \section1 Windows Vista, Windows 7, Windows 8

    At the time Qt %VERSION% was released, there were no known issues on these
    platforms.

    \section1 Windows XP

    \section2 Installation location

    Installing Qt into a directory with spaces, e.g. C:\\Program Files, may
    cause linker errors like the following:
    \snippet doc/src/snippets/code/doc_src_platform-notes.qdoc 2

    Install Qt into a subdirectory without spaces to avoid this problem.

    \section2 Possible GL conflict

    There is a known issue with running Microsoft NetMeeting, Lotus SameTime
    and other applications that require screen grabbing while direct
    rendering is enabled. Other GL-applications may not work as expected,
    unless direct rendering is disabled.

    \section2 GCC (MinGW)

    We have tested Qt with this compiler on Windows XP.
    The minimal version of MinGW
    supported is GCC 4.6. For 64 bit builds, \l{TDM-GCC} can be used.

    \section2 Intel C++ Compiler (Windows, Altix)

    Qt has been tested successfully with:

    \list
    \li Windows - Intel(R) C++ Compiler for 32-bit applications,
       Version 9.1.040.
    \li Altix - Intel(R) C++ Itanium(R) Compiler for Itanium(R)-based
       applications Version 8.1 Build 20050406 Package ID: l_cc_pc_8.1.030
    \endlist

    \section2 Visual Studio (Windows)

    We do most of our Windows development on Windows 7, using Microsoft
    Visual Studio 2008, Visual Studio 2010 or Visual Studio 11 (mostly
    64bit).

    We recommend using Visual Studio 2010 or higher as it supports some
    C++11 features beneficial to performance and memory usage.

    Qt works with all editions of Visual Studio.

    In order to use Qt with the Visual Studio Express Editions
    you need to download and install the Windows SDK.

    The Visual C++ Linker doesn't understand filenames with spaces (as in
    \c{C:\Program files\Qt\}) so you will have to move it to another place,
    or explicitly set the path yourself; for example:

    \snippet doc/src/snippets/code/doc_src_compiler-notes.qdoc 0

    If you are experiencing strange problems with using special flags that
    modify the alignment of structure and union members (such as \c{/Zp2})
    then you will need to recompile Qt with the flags set for the
    application as well.

    Visual Studio 2010 should be updated to Service Pack 1. Otherwise, a
    problem when compiling Qt for 64-bit in release mode may occur (see
    http://support.microsoft.com/kb/2280741).
*/

/*!
    \page platform-notes-mac.html
    \title Platform and Compiler Notes - Mac OS X
    \contentspage Platform and Compiler Notes

    This page contains information about the Mac OS X versions Qt is currently
    known to run on, with links to platform-specific notes. More information
    about the combinations of platforms and compilers supported by Qt can be
    found on the \l{Supported Platforms} page.

    \tableofcontents

    \section1 General Information

    Qt 5 applications can be deployed on Mac OS X 10.6 (Snow Leopard)
    and higher. We recommend using the most recent version of Mac OS
    for developing applications. Qt binaries built on 10.7 can be
    deployed on 10.6.

    \section2 Required Compiler Versions

    Use the latest gcc or clang as supplied with Xcode. Currently
    tested versions are Apple gcc 4.2.1 and Apple clang version 3.1.

    \section2 Binary Package

    \section2 Mac OS X on PowerPC hardware

    Qt 5 does not support OS X on PowerPC.

    \section2 Fink

    If you have installed the Qt for X11 package from \l{Fink},
    it will set the QMAKESPEC environment variable to darwin-g++. This will
    cause problems when you build the Qt for Mac OS X package. To fix this, simply
    unset your QMAKESPEC or set it to macx-g++ before you run configure.
    You need to have a fresh Qt distribution (make confclean).

    \section2 MySQL and Mac OS X

    There seems to be a issue when both -prebind and -multi_module are
    defined when linking static C libraries into dynamic library. If you
    get the following error message when linking Qt:

    \snippet doc/src/snippets/code/doc_src_platform-notes.qdoc 6

    re-link Qt using -single_module. This is only a problem when building the
    MySQL driver into Qt. It does not affect plugins or static builds.

    \section2 Attributes
    The following lists a set of useful attributes that can be used to tweak applications
    on Mac:

    Qt::AA_MacPluginApplication, Qt::AA_DontUseNativeMenuBar, Qt::AA_MacDontSwapCtrlAndMeta
    Qt::WA_MacNoClickThrough, Qt::WA_MacOpaqueSizeGrip, Qt::WA_MacShowFocusRect,
    Qt::WA_MacNormalSize, Qt::WA_MacSmallSize, Qt::WA_MacMiniSize, Qt::WA_MacVariableSize,
    Qt::WA_MacBrushedMetal, Qt::WA_MacAlwaysShowToolWindow, Qt::WA_MacFrameworkScaled,
    Qt::WA_MacNoShadow, Qt::Sheet, Qt::Drawer, Qt::MacWindowToolBarButtonHint,
    QMainWindow::unifiedTitleAndToolBarOnMac

    \section2 Mixing Qt with native code
    Two classes are available for either adding native Cocoa views/controls
    inside a Qt application, or the opposite, embedding Qt into a native
    Cocoa application:

    QMacCocoaViewContainer, QMacNativeWidget

    \section3 Using native Cocoa panels
    Launching native Cocoa panels from within a Qt application can sometimes
    be problematic. The reason is that Qt's event dispatcher is more flexible
    than what Cocoa offers, and lets the user spin the event dispatcher (and
    running QEventLoop::exec) without having to think about whether or not modal
    dialogs are showing on screen (which is a difference to Cocoa). Therefore
    we need to do special bookkeeping in Qt to handle this correctly, which
    unfortunately make mixing in native panels hard. The best way at the moment
    to do this, is to follow the pattern below, where we post the call to the
    function with native code rather than calling it directly. Then we know that
    Qt has cleanly updated any pending event loop recursions before the native
    panel is shown:

    \code
        #include <QtGui>

        class NativeProxyObject : public QObject
        {
            Q_OBJECT
        public slots:
            void execNativeDialogLater()
            {
                QMetaObject::invokeMethod(this, "execNativeDialogNow", Qt::QueuedConnection);
            }

            void execNativeDialogNow()
            {
                NSRunAlertPanel(@"A Native dialog", @"", @"OK", @"", @"");
            }

        };

        #include "main.moc"

        int main(int argc, char **argv){
            QApplication app(argc, argv);
            NativeProxyObject proxy;
            QPushButton button("Show native dialog");
            QObject::connect(&button, SIGNAL(clicked()), &proxy, SLOT(execNativeDialogLater()));
            button.show();
            return app.exec();
        }

    \endcode
*/

/*!
    \page platform-notes-android.html
    \title Platform and Compiler Notes - Android
    \contentspage Platform and Compiler Notes

    This page contains information about using Qt on the Android operating system.
    Using Qt on Android is currently considered to be in an experimental state,
    suited for development, but not for distribution.

    \tableofcontents

    \section1 General information

    Qt 5 applications can be deployed on Android 2.3 and higher.

    \section1 Required tools

    In order to build libraries or applications for Android, you will need an
    Android NDK and an Android SDK. You will also need the Java Development Kit
    version 1.6.

    \section1 Required tools for building on Windows

    To build for Android on Windows, you will need the MinGW collection of tools. This contains
    command-line tools needed for certain build steps and the GNU Compiler Collections which is
    used for building tools for running on the host, such as qmake and moc.

    \section1 Environment variables

    If you are building on the command line, make sure the following environment
    variables are set:

    \list
    \li ANDROID_NDK_ROOT: The path to the Android NDK.
    \li ANDROID_SDK_ROOT: The path to the Android SDK.
    \endlist

    When building the Qt libraries themselves, you can also set the environment
    variable ANDROID_API_VERSION for overriding the default version of the SDK used for
    building Java code.

    \section1 Making an Android app

    Apps on Android are Java applications, and thus a Java-based bindings layer is required
    in order to run Qt code on an Android device using the regular Android app launcher. By
    default, applications configured with qmake's application template will be build as shared
    libraries. The Java code should load all the required libraries in the correct order, including
    the library created for the application, and then use the JNI framework to call into the native
    code.

    \l{Qt Creator} has a tools to generate and maintain this Java bindings layer, enabling you to
    write regular native C++ code with Qt and deploy this to devices or emulators. If you prefer
    to use another IDE for development, it is also possible to use Qt Creator to generate the
    bindings code for your project, but edit the files in a different application. You will then
    have to maintain and build the bindings files manually.

    If you would prefer to write the Android-specific parts of your application manually, then
    this is also possible. For some insight into how Qt Creator manages it, you can look at the
    files under src/android in your Qt directory.

    \section1 Back button on Android

    Android devices have a specialized "Back" button. By default, Qt applications will quit
    when this button is pressed. To customize the behavior, listen for the key code
    Qt::Key_Back which will be generated whenever this button is pressed.

    \section1 Structure of Qt on Android

    Qt on Android consists of the following parts:

    \list
    \li The Qt libraries
    \li The qtforandroid platform plugins: This contains the integration of Qt on Android,
    including the JNI code required to communicate with the Java bindings. There are two
    platform plugins: libqtforandroid.so, which is used for QtWidgets-based applications, and
    libqtforandroidGL.so which is OpenGL-enabled and used for QtQuick 2-based applications.
    \li QtAndroid.jar: Java library used for communicating between the Java-based environment on
    Android and Qt's C++-code.
    \endlist

*/