path: root/doc/src/platforms/qnx.qdoc

/****************************************************************************
**
** Copyright (C) 2019 The Qt Company Ltd.
** Contact: https://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 https://www.qt.io/terms-conditions. For further
** information use the contact form at https://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: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page qnx.html
    \title Qt for QNX
    \brief Platform support for QNX.
    \ingroup supportedplatform
    \keyword 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.

    Qt 5 is currently tested and supported on QNX SDP 7.0, with support for
    both 32-bit and 64-bit target architectures:

    \list
        \li \c ARMle-v7 and \c x86 (32-bit)
        \li \c AArch64le and \c x86-64 (64-bit)
    \endlist

    Support for 64-bit architectures was added in QNX SDP 7.0.

    \section2 Previous Releases

    Older QNX SDP releases and other architectures may also work, but are not
    subject to regular builds and testing.

    \list
        \li \l {https://doc.qt.io/archives/qt-5.10/platform-notes-qnx.html}
               {Qt for QNX SDP 6.6}
    \endlist


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

    \section1 Supported Modules

    All the \l{Qt Essentials} modules are supported in Qt for QNX.

    See \l{Qt Add-Ons} for information about which Qt Add-Ons modules are supported
    in Qt for QNX.

    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} (registration required for access
    to downloads):

    \list
        \li \l {http://blackberry.qnx.com/en/sdp7/sdp70_download}{QNX SDP 7.0}
            with \l {http://www.qnx.com/download/group.html?programid=26808}
    \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.
    However, it is advisable to ensure that you can build Qt for the desktop
    target on the host 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 need to specify the target name for cross-compilation when configuring
    a Qt build:

    \table
    \header \li Architecture
            \li Configure cross-compilation target
    \row \li \c ARMle-v7 (32-bit)
         \li \badcode
             ./configure -xplatform qnx-armle-v7-qcc
             \endcode
    \row \li \c AArch64le (64-bit)
         \li \badcode
             ./configure -xplatform qnx-aarch64le-qcc
             \endcode
    \row \li \c x86 (32-bit)
         \li \badcode
             ./configure -xplatform qnx-x86-qcc
             \endcode
    \row \li \c x86-64 (64-bit)
         \li \badcode
             ./configure -xplatform qnx-x86-64-qcc
             \endcode
    \endtable

    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.

    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.

    See \l{Qt Configure Options} for more details.

    \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/7.0.0/#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:

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

    \section2 System Logger

    QNX provides the
    \l {http://www.qnx.com/developers/docs/7.0.0/#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:

    \badcode
    [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 plug-ins are
            located. It should be set to \c{<Qt-install-path>/qml}
        \li If Qt does not use fontconfig, you must either provide the path
            to the fonts with \c{QT_QPA_FONTDIR}, or place the fonts under
            \c{<Qt-install-path>/lib/fonts} which is the default font
            location.
    \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:

    \badcode
    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 to 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 flexibility provided by QNX Neutrino RTOS
    is a risk that the run environment is slightly different on your target
    than what is expected by Qt. This is a common reason why a Qt application
    on a new target fails to start. A few generic environment variables can
    help locate the root cause for problems:

    \list
        \li Setting \c{QT_DEBUG_PLUGINS} to \c{1} helps to see why the QPA
            plugin 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 plugin failed to load because it
            could not load other shared libraries.
        \li Setting \c{QT_LOGGING_TO_CONSOLE} will force sending all logging
            messages to \c{stderr} instead of \c{slog2}. This is useful for
            analyzing application startup problems, as 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
        \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

    \note This is not a complete list of shared libraries used by Qt on QNX
          Neutrino OS. Multiple shared libraries are already available in a
          typical OS image, or included by other parts of the system, for
          example, the \c 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/7.0.0/#com.qnx.doc.neutrino.prog/topic/devel_pdebug.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
    related \l {http://www.qnx.com/developers/docs/7.0.0/#com.qnx.doc.ide.userguide/topic/debugging.html}
    {QNX documentation} for more details.

    \section2 Other Utilities on the Target Device

    QNX provides board support packages (BSPs) for many common platforms and
    their individual variants. However, if you need a BSP for a board that QNX
    does not provide, you can modify an existing one or develop your own.

    When you develop a BSP for your board, you should include the following
    utilities to enable Qt Creator to deploy, run, debug, and stop applications
    on QNX devices:

    \list
        \li \c awk
        \li \c cat
        \li \c cut
        \li \c df
        \li \c grep
        \li \c kill
        \li \c ln
        \li \c mkdir
        \li \c netstat
        \li \c print
        \li \c printf
        \li \c ps
        \li \c read
        \li \c sed
        \li \c sleep
        \li \c slog2info
        \li \c tail
        \li \c tar
        \li \c zip
        \li \c uname
        \li \c unzip
    \endlist

    The utilities need to be in a standard location, such as \c /bin or
    \c /usr/bin. Alternatively, you can use the \c {~/.ssh/environment} file
    to set variables for remote commands, such as \c PATH. In addition, you
    must set \c{enable PermitUserEnvironment} in the SSH Daemon configuration.

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

    For more information about modifying or developing a BSP for you board, see
    \l{http://www.qnx.com/developers/docs/7.0.0/index.html#com.qnx.doc.neutrino.custom_bsp/topic/about.html}
    {Customizing a BSP} in the QNX developer documentation.

    \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. However,
    there is no standard for 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 can cause some confusion as 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 [QMake] {Installing Files} in the \l {qmake} documentation for more
    details.
*/