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

/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing/
**
** 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 The Qt Company. For licensing terms
** and conditions see http://www.qt.io/terms-conditions. For further
** information use the contact form at http://www.qt.io/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 platform-notes-vxworks.html
    \title Platform and Compiler Notes - VxWorks
    \contentspage Platform and Compiler Notes
    \target VxWorks

    Qt for VxWorks is available only under a commercial license.

    Please contact Qt sales at Digia to find out more:
    http://info.qt.digia.com/contact-qt

*/

/*!
    \page platform-notes-qnx.html
    \title Platform and Compiler Notes - QNX
    \contentspage Platform and Compiler Notes
    \target QNX

    \section1 Supported Architectures and QNX Releases

    From the perspective of an application development platform, Qt runs on top of
    \l {http://www.qnx.com/products/neutrino-rtos/neutrino-rtos.html}{QNX Neutrino RTOS}.
    System integrators and application developers use a QNX SDP (Software Development Platform)
    which includes QNX Neutrino RTOS components for various targets and a full set of development
    tools. \l {http://www.qnx.com/}{QNX Software Systems} also provides additional packages which
    enrich the standard feature set of QNX Neutrino RTOS. Currently, those packages are:

    \list
        \li \l {http://www.qnx.com/download/group.html?programid=26072}{QNX SDK for Apps and Media 1.0}.
        \li \l {http://www.qnx.com/download/group.html?programid=26076}{QNX CAR Platform 2.1}.
    \endlist

    Qt 5 is currently tested and supported on QNX SDP 6.5 SP1 and on SDP 6.6 with QNX SDK for
    Apps and Media, see the section \l {Build Requirements} for more details. Supported
    architectures are ARMle-v7 and x86. Older QNX SDP releases and other architectures may also
    work, but are not subject to regular builds and testing.

    For a specific list of available boards, displays and input devices, contact QNX Software
    Systems (info@qnx.com) or KDAB (qnx-info@kdab.com). Qt on the QNX Neutrino OS is also supported
    by Qt Enterprise Embedded, \l {http://www.qt.io/contact-us/}{contact The Qt Company}
    for more details.

    \section1 Supported Modules

    Almost all Qt Essential \l{All Modules}{modules} and some add-ons are supported on
    the QNX Neutrino RTOS. See the \l{http://wiki.qt.io/Qt_Status_on_QNX}
    {status page on the Qt Project wiki} for details.

    If you build Qt from a released source code distribution archive, the \c{configure} tool ensures
    that the build will be made only for modules which are known to build for the target specified.
    Additionally, you can explicitly exclude unsupported or not needed modules from the build via the
    \c{-skip <module>} option when running the \c{configure} tool.

    If you build Qt directly from the Git repository, you should initialize the repository only with
    modules which are supported or build and install modules separately. This helps to prevent
    unexpected build problems.

    \section1 Build Requirements

    Building Qt 5 requires the following packages available from the \l {http://www.qnx.com/}{QNX website}
    (an access requires registration):

    \list
        \li \l {http://www.qnx.com/download/group.html?programid=26071}{SDP 6.6} with
        \l{http://www.qnx.com/download/group.html?programid=26072}{QNX SDK for Apps and Media 1.0}. This
        combination forms the current reference platform for Qt on QNX Neutrino RTOS and should be your
        first choice.
        \li \l {http://www.qnx.com/download/group.html?programid=26071}{SDP 6.6}. Compared to the
        previous configuration, this choice does not not use
        \l{http://www.qnx.com/download/group.html?programid=26072}{QNX SDK for Apps and Media 1.0} which provides
        \c{fontconfig} and multimedia support along with other features. In this case, Qt will use the
        internal font database instead of \c{fontconfig}, and \l{Multimedia}{multimeida} will be not functional.
        \li \l {http://www.qnx.com/download/group.html?programid=20905}{SDP 6.5.0 SP1}
        supplemented by the \l {http://www.qnx.com/developers/docs/660/topic/com.qnx.doc.screen/topic/manual/cscreen_about.html}
        {QNX Screen Graphics Subsystem} (also called just "Screen") as an add-on. The Screen is
        a standard component of SDP 6.6 and newer, but for SDP 6.5 it is available upon a request
        only, contact QNX Software Systems (info@qnx.com). You should also install possibly all
        patches for SDP 6.5 as provided by QNX Software Systems.
    \endlist

    The compiler and other parts of the tool chain are provided in the SDP packages. You do not need
    any additional installations on your host PC. Still, it is advisable to ensure that you can build
    Qt on the host for the desktop target as well. See \l {Building Qt Sources} for more details.
    All supported QNX Neutrino RTOS targets are fully integrated in the makespecs provided in the Qt
    sources. You just need to specify the target name for cross-compilation when configuring a Qt build:

    For ARM:

    \code
    ./configure -xplatform qnx-armle-v7-qcc
    \endcode

    For x86:

    \code
    ./configure -xplatform qnx-x86-qcc
    \endcode

    The \c{configure} tool runs various tests to detect capabilities of the SDP and its add-ons.
    It sets related flags according the test results. Check the configure summary on the
    console or in \c{./qtbase/config.summary} if needed and set other flags manually as required.
    See \l{Qt Configure Options} for more details.

    Independent of the platform you are building for, consider using the \c{-prefix}
    option with \c{configure} as well, for example, \c{-prefix <Qt-install-path>}. This specifies the
    target folder where Qt will be installed and places all build artifacts outside of the
    source code tree.

    As noted above, building Qt 5 with QNX SDP 6.5.0 SP1 requires the Screen. Qt 5 needs
    related headers and libraries and will not build if they are not available. QNX SDP 6.5.0 SP1
    contains an older version of SQLite which is not supported by Qt 5 anymore. You should use the
    SQLite provided with the Qt 5 source code. This is the default behavior of \c{configure} anyway,
    just do not force the system SQLite with \c{-system-sqlite}. QNX SDP 6.5.0 SP1 does not provide
    fontconfig. Qt will fall back to its internal font database. This limits the flexibility with
    handling fonts, but it is not a serious issue for most projects. Many other Qt 5 add-on modules
    will probably not build with QNX SDP 6.5.0 SP1, since their development has advanced too far
    to support that older release of SDP.

    \section1 Qt Runtime Target Requirements

    QNX Software Systems delivers software solutions for making embedded devices. This includes
    creation of QNX Neutrino RTOS boot images in a very flexible way. Even though QNX provides
    several reference scripts for the OS image creation, sooner or later you will need to make
    changes or you might decide to create an OS image from scratch. Qt relies on the existence of
    several third-party components and selected OS services. Due to this, QNX Neutrino RTOS
    boot images for a target device running Qt must meet a couple of requirements to ensure
    that Qt works as expected. The sections below list the crucial parts for Qt.

    \section2 QNX Screen Graphics Subsystem

    Before any Qt application can be started, the \l {http://www.qnx.com/developers/docs/660/topic/com.qnx.doc.screen/topic/manual/cscreen_about.html}{QNX Screen Graphics Subsystem} (also called just "Screen") must be running.
    The Screen consists not only of a driver, but also includes several utilities and other services
    which are used by Qt. This includes processing of mouse and keyboard events as well. You can
    ensure that the Screen is configured and running correctly by verifying that a graphics application,
    like \c gles2-gears, can be started and runs without problems. Most of the recent sample OS build
    scripts in the SDP include sections with all components and start commands for the Screen.
    Use them as a reference.

    \section2 IPv6 Support

    \l {Qt Network}{Qt's networking stack} requires IPv6 support to be enabled, independent of
    whether the actual networking uses IPv4 or IPv6. That means, that \c{io-pkt-v6-hc} must be
    running, \e {not} \c{io-pkt-v4}.

    \section2 Random device \c{/dev/random}

    Qt requires \c{/dev/random} to be present and functional. Start it before starting any Qt
    application or during the system startup:

    \code
    random -p
    waitfor /dev/random
    \endcode

    \section2 System Logger

    QNX provides the \l {http://www.qnx.com/developers/docs/660/topic/com.qnx.doc.neutrino.utilities/topic/s/slogger2.html}{slog2}
    logging framework tailored to specifics of embedded systems. The major advantage of it is
    a much better performance than a text output to files. Qt uses this framework by default for
    any logging output going through QDebug on QNX Neutrino RTOS. The \c{slog2} service should
    be started during the system startup. The \c{slog2} also relies on the existence of the
    \c{/tmp} folder which has to be configured as well, for example:

    \code
    [type=link] /tmp=/dev/shmem
    display_msg "Starting slogger2..."
    slogger2 -U1001:1000 &
    waitfor /dev/slog2
    \endcode

    \section2 Environment Variables

    There is a set of environment variables you should set when starting a Qt application. Most
    of them are actually not specific to QNX Neutrino RTOS. They are still mentioned here, since
    knowing them just saves a lot of time in case of problems.

    \section3 Qt Runtime Location

    If you did not build Qt with RPATH enabled, you can place the Qt runtime components in any
    folder in the file system. The following environment variables should point to valid locations
    assuming that the Qt installation is located in \c{<Qt-install-path>}:

    \list
        \li \c{LD_LIBRARY_PATH} should contain the path to the Qt libraries
        in \c{<Qt-install-path>/lib}
        \li \c{QT_PLUGIN_PATH} defines where the Qt plug-ins are located. It should be set
        to \c{<Qt-install-path>/plugins}
        \li \c{QML2_IMPORT_PATH} defines where the Qt Quick 2 plug-ins are located. It should be set
        to \c{<Qt-install-path>/qml}
        \li \c{QML_IMPORT_PATH} is required only when using the Qt Quick 1 compatibility module.
        It should be set to \c{<Qt-install-path>/imports}
        \li If Qt does not use fontconfig, you have to specify the path to the fonts provided in
        Qt and set \c{QT_QPA_FONTDIR} to \c{<Qt-install-path>/lib/fonts}
    \endlist

    \section3 Physical Screen Size

    Qt needs information about the physical dimensions of the attached display to determine DPI
    values and thus set correct font sizes. Usually, this information is provided by the Screen.
    In some cases you may see an invalid screen size such as 0mmx0mm.
    In such a case Qt requires an environment variable \c QQNX_PHYSICAL_SCREEN_SIZE set to
    according values to get the required information. If Qt applications exit with an error
    message saying that the physical screen size couldn't be determined, set the variable like
    this before starting the Qt application:

    \code
    export QQNX_PHYSICAL_SCREEN_SIZE=150,100
    \endcode

    to inform Qt that the screen has a width of 150mm and a height of 100mm in this particular
    case. The physical screen size is measured in millimeters (mm) and should correspond the
    actual physical size of the display in the final configuration.

    \section3 Troubleshooting the First Start of a Qt Application

    The only drawback of the large flexibility provided by QNX Neutrino RTOS is a risk that
    something is still different on your target than it is expect to be by Qt. This is a very
    common reason why the first Qt application on a new target fails to start. A few generic
    environment variables can help finding the root cause for problems:

    \list
        \li Setting \c{QT_DEBUG_PLUGINS} to \c{1} helps to see why the QPA plug-in cannot load.
        \li Setting \c{LD_DEBUG} to \c{1} helps to see where and how shared libraries are loaded.
        This can be used in combination with \c{QT_DEBUG_PLUGINS} when a plug-in cannot be
        loaded because it cannot load some other shared libraries.
        \li Setting \c{QT_LOGGING_TO_CONSOLE} will force sending all logging message to
        \c{stderr} instead of \c{slog2}. This is very handy to analyze application startup
        problems, since you do not need to use another tool to see the messages.
    \endlist

    \section2 Third Party Libraries

    Make sure that your system image contains the following additional 3rd-party libraries
    which are not always included in minimal QNX Neutrino RTOS images:

    \list
        \li \c libfontconfig (provided in addition to a standard SDP 6.6 installation)
        \li \c libfreetype
        \li \c libiconv
        \li \c libicui18n
        \li \c libicudata
        \li \c libicuuc
        \li \c libpng14
        \li \c libxml2
        \li \c libsqlite3
        \li \c libssl
        \li \c libcrypto
    \endlist

    Please note that the above list is not a full list of shared libraries used by Qt on QNX Neutrino OS. Quite some shared libraries are already available in typical OS images or included by other parts of the system, e.g. by the Screen.

    \section2 Accessing Environment Variables

    \c setconf and \c getconf are required to access POSIX environment variables, especially for
    the host name and time and date.

    \section1 Qt Creator Target Requirements

    A QNX Neutrino RTOS target used for development with Qt Creator should provide a few additional
    command line tools and services.

    \section2 SSH

    Deployment and remote application startup relies on SSH. The SSH daemon (\c{sshd}) must
    be installed and running during the system startup. Please note that it requires
    \c{/dev/random} which was already mentioned. It also expects specific access rights to
    be set correctly to its configuration files. The latter makes it impossible starting SSH
    from a file system which does not have full access rights support, for example, FAT.

    \section2 SCP and SFTP

    \c{scp} and \c{sftp} utilities are used by Qt Creator for deployment and should be
    available on the target. Additionally, \c{inetd} daemon has to be started at the system
    startup which then launches according services, including FTP when needed.

    \section2 QNX Tools for Remote Debugging

    Remote debugging requires the \c{pdebug} (\l{http://www.qnx.com/developers/docs/660/topic/com.qnx.doc.ide.userguide/topic/debug_Base_.html}{process-level debugger}) to be running on the development device. It is usually
    started by the \c{qconn} process which also provides various process information to
    Qt Creator. Generally, Qt Creator uses the same remote debugging interfaces as the QNX
    Momentics IDE provided in the SDP. See the according \l{http://www.qnx.com/developers/docs/660/topic/com.qnx.doc.ide.userguide/topic/debug_test_debug.html}{documentation} for more details.

    \section2 Other Utilities on the Target Device

    Most of the OS build scripts include a set of standard command line utilities.
    A few more utilities are expected by Qt Creator and should be provided on a target:

    \list
        \li \c printf
        \li \c awk
        \li \c ps
        \li \c tar
        \li \c zip
        \li \c unzip
        \li \c sed
    \endlist

    Run the test when you configure a new target device in Qt Creator to verify that all
    required components are available and running.

    \section2 Deployment Destination Folder

    Qt Creator deploys an application to the target device before starting it remotely.
    On most embedded devices, it is just copying application binaries and related data
    files to a folder on the target device. The challenge herewith is that there is no standard
    so far how this folder is called and where it is located. Quite a few configurations use
    \c{/tmp} for this, which is often mapped to a RAM disk. This case causes a lot of confusion
    since deployed applications disappear on the next device shutdown. Another popular target is
    \c{/opt}. This folder is located in a read-only partition on many systems making deployment
    impossible. Make sure that you use a destination folder which meets your needs. You can
    set it in the \c{install.path} variable in the \c{.pro} file of your project, see
    \l{Installing Files} in the \l {QMake} documentation for more details.

    \section1 Take a look at the Qt port for BlackBerry 10

    The BlackBerry 10 platform is based on the QNX Neutrino RTOS. Even though BlackBerry 10
    devices and other embedded device running QNX Neutrino RTOS are very different, Qt on
    BlackBerry 10 and Qt on QNX Neutrino RTOS have a lot in common. Take a look at
     \l{Platform and Compiler Notes - BlackBerry} to learn more.

*/

/*!
    \page platform-notes-integrity.html
    \title Platform Notes - INTEGRITY
    \contentspage Platform Notes
    \target INTEGRITY

    \note \l {http://www.ghs.com/products/rtos/integrity.html}{INTEGRITY} is a community supported platform

    \sa {http://blog.qt.io/blog/2012/06/01/developing-with-qt-commercial-for-integrity-on-windows-a-step-by-step-guide-to-configure-and-compile-qt-commercial-on-integrity-2/}{Developing with Qt Commercial for INTEGRITY on Windows}
    \sa {http://qt.gitorious.org/qt/qt-integrity}{the git repository}
*/