| /**************************************************************************** |
| ** |
| ** 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. |
| \contentspage Platform and Compiler Notes |
| \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. |
| */ |