Doc: Restructure info on developing for Boot2Qt devices

- Split the topic into how-to and reference topics
- Remove redundant information
- Make the instructions consistent with the remote Linux topics
- Include info about SSH connections from the remote Linux topic
- Add the \B2Q macro for "Boot to Qt" and use it where possible
  (some UI text still says "Boot2Qt"

Task-number: TCREATORBUG-29361
Change-Id: I7fe5f957049d84ec7402f4c11a070ac2d44fcb38
Reviewed-by: hjk <hjk@qt.io>
Reviewed-by: Inkamari Harjula <inkamari.harjula@qt.io>
Reviewed-by: Samuli Piippo <samuli.piippo@qt.io>
This commit is contained in:
Leena Miettinen
2024-05-07 15:32:03 +02:00
parent 898203aa6e
commit 5b5c61c519
19 changed files with 178 additions and 179 deletions

View File

@@ -16,6 +16,7 @@ macro.macos = "macOS"
macro.note = "\\b{Note:}"
macro.oslash.HTML = "&oslash;"
macro.ouml.HTML = "&ouml;"
macro.B2Q = "Boot to Qt"
macro.Q3DS = "Qt 3D Studio"
macro.QA = "Qt Assistant"
macro.QB = "Qt Bridge"

View File

@@ -464,7 +464,8 @@
\list
\li Perf events may be globally disabled on your system.
The preconfigured \l Boot2Qt images come with Perf events enabled.
The preconfigured \l{\B2Q: Documentation}{\B2Q} images come with Perf
events enabled.
For a custom configuration you need to make sure that the file
\c {/proc/sys/kernel/perf_event_paranoid} contains a value smaller
than \c {2}. For maximum flexibility in recording traces you can

View File

@@ -11,7 +11,7 @@
If you have set up \l{Qt Application Manager}, you can deploy, run, and
debug applications on the desktop, remote generic SSH Linux targets, or
\l{Boot2Qt}{Boot2Qt devices}. The applications can be either
\B2Q devices. The applications can be either
\e {built-in applications} or \e {third-party applications}. The former
are part of the System UI or the base installation, while the latter
are dynamically installed, updated, and uninstalled.
@@ -118,7 +118,7 @@
\li The path to the controller that installs the application package into
the target system.
When you run applications on a Boot2Qt device, you can see the device
When you run applications on a \B2Q device, you can see the device
ID here.
\row
\li \uicontrol {Application ID}
@@ -148,7 +148,10 @@
slowness and unresponsive, stuttering user interfaces. You cannot profile an
in-process runtime as an individual process.
\sa {Activate kits for a project}, {Connecting Boot2Qt Devices},
{Remote Linux}{How To: Develop for remote Linux}, {Enable and disable plugins},
{Run on many platforms}, {Debugging}, {Debuggers}, {Debugger}, {Profiling QML Applications}
\sa {Activate kits for a project}, {Enable and disable plugins},
{\B2Q}{How To: Develop for \B2Q},
{Remote Linux}{How To: Develop for remote Linux},
{Run on many platforms}, {Debugging}, {Debuggers}, {Debugger},
{Developing for \B2Q Devices}, {Developing for Remote Linux Devices},
{Profiling QML Applications}
*/

View File

@@ -3,11 +3,11 @@
/*!
\externalpage https://doc.qt.io/Boot2Qt/index.html
\title Boot2Qt: Documentation
\title \B2Q: Documentation
*/
/*!
\externalpage https://doc.qt.io/Boot2Qt/b2qt-requirements-x11.html#setting-up-usb-access-to-embedded-devices
\title Boot2Qt: Setting Up USB Access to Embedded Devices
\title \B2Q: Setting Up USB Access to Embedded Devices
*/
/*!
\externalpage https://doc.qt.io/qt/qtqml-index.html

View File

@@ -103,6 +103,13 @@
\generatelist creator-how-to-bare-metal
\section2 \B2Q
Run, debug, and analyze applications on \l{\B2Q: Documentation}{\B2Q}
devices.
\generatelist creator-how-to-b2qt
\section2 iOS
Install \l {Qt for iOS} and Xcode, and connect iOS devices to the computer.

View File

@@ -1,143 +1,79 @@
// Copyright (C) 2023 The Qt Company Ltd.
// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page creator-developing-b2qt.html
\previouspage creator-developing-baremetal.html
\nextpage creator-adding-docker-devices.html
\previouspage creator-reference.html
\title Connecting Boot2Qt Devices
\ingroup creator-reference-devices
You can connect \l{Boot2Qt} devices to the development PC to run, debug,
and analyze applications built for them from \QC. For this, you need the
appropriate \l{http://qt.io/licensing/}{Qt license}.
\title Developing for \B2Q Devices
If you have a tool chain for building applications for Boot2Qt devices
installed on the development PC, you can add it to \QC. You can then
select a \l{glossary-buildandrun-kit}{kit} with the \uicontrol Boot2Qt
device type to build applications for and run them on the devices.
\brief Connect \B2Q devices to the computer to run,
debug, and analyze applications built for them from \QC.
To be able to run and debug applications on Boot2Qt devices,
you must add devices and select them in the \QC
\l{kits-tab}{kit}.
The \l{\B2Q: Documentation}{\B2Q} stack runs on a variety of hardware.
\l{http://qt.io/licensing/}{Qt license} holders can customize the contents of
the stack and take it into production hardware.
\section1 Enabling the Boot2Qt Plugin
\note Enable the \B2Q plugin to use it.
To enable the Boot2Qt plugin:
\list 1
\li Select \uicontrol Help > \uicontrol {About Plugins} >
\uicontrol {Device Support} > \uicontrol Boot2Qt to
enable the plugin.
\li Select \uicontrol {Restart Now} to restart \QC and load the plugin.
\endlist
\section1 Adding Boot2Qt Devices
If \QC does not automatically detect a device you connected with USB, select
\preferences > \uicontrol Devices >
\uicontrol Devices > \uicontrol Add > \uicontrol {Boot2Qt Device} to create
either a network connection or a USB connection to it.
If you have a toolchain for building applications for \B2Q devices
installed on the computer, add it to a \l{Kits}{kit} with the
\uicontrol \B2Q device type to build applications for and run them on
the devices.
\image qtcreator-boot2qt-device-configurations.webp {Devices tab in Preferences}
To add a device without using a wizard, select \uicontrol {Boot2Qt Device} in
the pull-down menu of the \uicontrol Add button.
\include linuxdev.qdoc openssh
\note On Ubuntu Linux, the development user account must have access to the
plugged-in devices. To grant them access to the device via USB, create a new
\c udev rule, as described in
\l{Boot2Qt: Setting Up USB Access to Embedded Devices}.
\sa {\B2Q}{How To: Develop for \B2Q},
{Manage Kits}{How To: Manage Kits}, {Run in Qt Application Manager},
{\B2Q Deploy Configuration}, {\B2Q Run Settings},
{\B2Q: Documentation}
*/
You can edit the settings later in \preferences >
\uicontrol Devices > \uicontrol Devices.
/*!
\page creator-how-to-connect-b2qt.html
\previouspage creator-how-tos.html
To reboot the selected device, select \uicontrol {Reboot Device}.
\ingroup creator-how-to-b2qt
To restore the default application to the device, select
\uicontrol {Restore Default App}.
\title Connect \B2Q devices
\section2 Protecting Connections
Create connections between \l{\B2Q: Documentation}{\B2Q} devices and
\QC to run, debug, and analyze applications on them.
You can protect the connections between \QC and a device by using an
\l{OpenSSH} connection. OpenSSH is a
connectivity tool for remote login using the SSH protocol. The OpenSSH
suite is not delivered with \QC, so you must download it and install it
on the development PC. Then, you must configure the paths to the tools in
\QC. For more information, see \l {Configure SSH connections}.
\note Enable the \B2Q plugin to use it.
You need either a password or an SSH public and private key pair for
authentication. If you do not have an SSH key, you can use the \c ssh-keygen
tool to create it in \QC. For more information, see \l {Generate SSH keys}.
\QC does not store passwords. If you use password authentication, you may
need to enter the password upon every connection to the device, or if
caching is enabled, at every \QC restart. If you frequently run into the
timeout, consider using key-based authentication. On \macos and Linux, you
can also select \preferences > \uicontrol Devices > \uicontrol SSH
and increase the time (in minutes) to use the same SSH connection in the
\uicontrol {Connection sharing timeout} field. Windows does not support
shared connections.
\image qtcreator-ssh-options.png {SSH preferences}
\section1 Flashing Boot2Qt Devices
To flash the Boot2Qt image to an SD card with Flashing Wizard, select
\uicontrol Tools > \uicontrol {Flash Boot to Qt Device} and follow the
instructions of the wizard.
\image qtcreator-boot2qt-flashing-wizard.png {Boot2Qt Flashing Wizard}
\section1 Configuring Connections
To configure connections between \QC and a Boot2Qt device and to
specify build and run settings for the device:
To configure connections between \QC and a \B2Q device:
\list 1
\li Check that you can reach the IP address of the device, or use USB to
connect it.
\li Select \preferences > \uicontrol Kits > \uicontrol {Qt Versions} >
\uicontrol Add to add the Qt version for Boot2Qt.
\li Select \preferences > \uicontrol Kits >
\uicontrol Compilers > \uicontrol Add to add the compiler for
building the applications.
\li Select \uicontrol Tools > \uicontrol {Flash Boot to Qt Device}
to flash the Boot2Qt image to an SD card with Flashing Wizard.
\li To deploy applications and run them remotely on devices, specify
parameters for connecting to the devices over the network (\QC
automatically detects devices connected with USB):
\list 1
\li Select \preferences > \uicontrol Devices >
\uicontrol Devices > \uicontrol Add > \uicontrol Boot2Qt.
\image qtcreator-devices-boot2qt.png {Boot2Qt Network Device Setup wizard}
\li In the \uicontrol {Device name} field, enter a name for
the connection.
\li In the \uicontrol {Device address} field, enter the host
name or IP address of the device. This value will be
available in the \c %{Device:HostAddress} variable.
\li Click \uicontrol {Finish} to test the connection and
add the device.
\li Go to \preferences > \uicontrol Kits > \uicontrol {Qt Versions}.
\li Select \uicontrol Add to add the Qt version for \B2Q.
\li Go to \preferences > \uicontrol Kits > \uicontrol Compilers.
\li Select \uicontrol Add to add the compiler for building the
applications.
\li Go to \uicontrol Tools > \uicontrol {Flash \B2Q}
to flash the \B2Q image to an SD card with \B2Q Flashing Wizard.
\image qtcreator-boot2qt-flashing-wizard.png {\B2Q Flashing Wizard}
\li Follow the instructions of the wizard to flash the image to the SD
card.
\li Go to \preferences > \uicontrol Devices > \uicontrol Devices.
\li Select \uicontrol Add to add a \B2Q device.
You can edit the connection parameters in the
\uicontrol Devices tab. The wizard does not show
parameters that have sensible default values. One of
these is the SSH port number, which is available in
the variable \c %{Device:SshPort}.
To add a device without using the wizard, select
\uicontrol {Boot2Qt Device} in the pull-down menu of the
\uicontrol Add button.
\endlist
\li Select \preferences > \uicontrol Kits >
\uicontrol Add to add a kit for building applications for the
device. Select the Qt version, compiler, and device that you
added above, and choose \uicontrol Boot2Qt as the device type.
\QC automatically detects devices connected with USB.
\li Go to \preferences > \uicontrol Kits.
\li Select \uicontrol Add to add a kit for building for the device.
\li Select the Qt version, compiler, and device that you added above.
\li In \uicontrol {Run device type}, select \uicontrol {Boot2Qt Device}.
\li To specify build settings:
\list 1
\li Open a project for an application you want to develop for the
device.
\li Select \uicontrol Projects > \uicontrol {Build & Run} to enable
\li Go to \uicontrol Projects > \uicontrol {Build & Run} to activate
the kit that you specified above.
\endlist
\li Select \uicontrol Run to specify run settings. Usually, you can use
@@ -145,9 +81,62 @@
When you run the project, \QC deploys the application as
specified by the deploy steps. By default, \QC copies the
application files to the device. For more information, see
\l{Boot2Qt Run Settings}.
application files to the device.
\endlist
\sa {Boot2Qt: Setting Up USB Access to Embedded Devices}
\sa {Configure SSH connections}, {Generate SSH keys},
{Enable and disable plugins}, {\B2Q}{How To: Develop for \B2Q},
{Manage Kits}{How To: Manage Kits}, {\B2Q Deploy Configuration},
{\B2Q Run Settings}, {Developing for \B2Q Devices}
*/
/*!
\page creator-how-to-add-b2qt.html
\previouspage creator-how-tos.html
\ingroup creator-how-to-b2qt
\title Add \B2Q devices
\note Enable the \B2Q plugin to use it.
If \QC does not automatically detect a \l{\B2Q: Documentation}{\B2Q}
device you connect with USB:
\list 1
\li Go to \preferences > \uicontrol Devices > \uicontrol Devices.
\image qtcreator-boot2qt-device-configurations.webp {Devices tab in Preferences}
\li Select \uicontrol Add > \uicontrol {Boot2Qt Device} to create
either a network connection or a USB connection to the device.
\image qtcreator-devices-boot2qt.png {Boot to Qt Network Device Setup wizard}
\li In \uicontrol {Device name}, enter a name for the connection.
\li In \uicontrol {Device address}, enter the host
name or IP address of the device. This value becomes the value of the
\c %{Device:HostAddress} variable.
\li Select \uicontrol {Finish} to test the connection and add the device.
\endlist
The wizard does not show parameters that have sensible default values, such
as the SSH port number. It is available in the variable \c %{Device:SshPort}.
To add a device without using a wizard, select \uicontrol {Boot2Qt Device} in
the pull-down menu of the \uicontrol Add button.
\note On Ubuntu Linux, the development user account must have access to the
plugged-in devices. To grant them access to the device via USB, create a new
\c udev rule, as described in
\l{\B2Q: Setting Up USB Access to Embedded Devices}.
\section1 Reboot devices
To reboot the selected device, select \uicontrol {Reboot Device}.
\section1 Restore default applications
To restore the default application to the device, select
\uicontrol {Restore Default App}.
\sa {Enable and disable plugins}, {\B2Q}{How To: Develop for \B2Q},
{Developing for \B2Q Devices},
{\B2Q: Setting Up USB Access to Embedded Devices}
*/

View File

@@ -7,15 +7,15 @@
\ingroup creator-reference-deploy-configurations
\title Boot2Qt Deploy Configuration
\title \B2Q Deploy Configuration
\brief Copy application files to Boot2Qt devices.
\brief Copy application files to \B2Q devices.
Specify settings for deploying applications to \l{Boot2Qt} devices
in the project configuration file and in \uicontrol Projects >
\uicontrol {Run Settings} > \uicontrol Deployment.
Specify settings for deploying applications to \l{\B2Q: Documentation}
{\B2Q} devices in the project configuration file and in \uicontrol Projects
> \uicontrol {Run Settings} > \uicontrol Deployment.
\image qtcreator-boot2qt-deployment-steps.png "Boot2Qt deployment steps"
\image qtcreator-boot2qt-deployment-steps.png {Boot to Qt deployment steps}
The deployment process is described in more detail in
\l{Remote Linux Deploy Configuration}.
@@ -26,5 +26,7 @@
\uicontrol {Add Deploy Step} > \uicontrol {Change default application}
> \uicontrol {Set this application to start by default}.
\sa {Build and Run}{How To: Build and Run}, {Boot2Qt Run Settings}
\sa {Build and Run}{How To: Build and Run},
{\B2Q}{How To: Develop for \B2Q}, {\B2Q Run Settings},
{Developing for \B2Q Devices}
*/

View File

@@ -15,7 +15,7 @@
\list
\li Bare Metal
\li \l {Boot2Qt}
\li \B2Q
\li Remote Linux
\li Microcontrollers (MCU)
\li \l QNX
@@ -31,23 +31,6 @@
You can connect embedded devices to the development PC to run, debug, and
analyze applications built for them from \QC.
\section1 Boot2Qt
The Boot2Qt stack runs on a variety of hardware. License holders can use
tools to customize the contents of the stack and to take it into
production hardware.
The following topics have more information about developing applications
for Boot2Qt devices:
\list
\li \l{Boot2Qt: Documentation}
\li \l{Connecting Boot2Qt Devices}
\li \l{Boot2Qt Run Settings}
\li \l{Boot2Qt Deploy Configuration}
\li \l{Run in Qt Application Manager}
\endlist
\section1 QNX
The QNX Neutrino RTOS has more command-line tools

View File

@@ -1,30 +1,30 @@
// Copyright (C) 2023 The Qt Company Ltd.
// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page creator-run-settings-boot2qt.html
\page creator-run-settings-\B2Q.html
\previouspage creator-reference.html
\ingroup creator-reference-run-configurations
\title Boot2Qt Run Settings
\title \B2Q Run Settings
\brief Settings for running applications on Boot2Qt devices.
\brief Settings for running applications on \B2Q devices.
Specify settings for running applications on the \l {kits-tab}{Run device} that
you select for a kit in \uicontrol Projects > \uicontrol {Build & Run} >
\uicontrol Run > \uicontrol {Run Settings}.
To run and debug an application on a \l Boot2Qt device (commercial only), you
must create connections from the development host to the device and add the
device configurations to kits. Select \uicontrol {Manage Kits} to add devices
to kits. For more information, see
\l{http://doc.qt.io/Boot2Qt/b2qt-installation-guides.html}
{Boot2Qt: Installation Guide}.
To run and debug an application on a \l{\B2Q: Documentation}{\B2Q} device
(commercial only), create connections from the development host to the device
and add the device configurations to kits.
Select \uicontrol {Manage Kits} to add devices to kits.
The run settings display the path to the executable file on the development
host and on the device.
\sa {Activate kits for a project}, {Configure projects for running}, {kits-tab}{Kits},
{Boot2Qt Deploy Configuration}
\sa {\B2Q}{How To: Develop for \B2Q}, {Manage Kits}{How To: Manage Kits},
{Configure projects for running}, {kits-tab}{Kits},
{\B2Q Deploy Configuration}
*/

View File

@@ -53,7 +53,7 @@
\ingroup creator-how-to-remote-linux
\title Generate SSH Keys
\title Generate SSH keys
To protect the connections between \QC and a device, use \l{OpenSSH}.

View File

@@ -22,6 +22,7 @@
\image qtcreator-preferences-devices-remote-linux.webp {Remote Linux Device in Devices}
//! [openssh]
\section1 Protecting Device Connections
To protect the connections between \QC and a device, use \l{OpenSSH} for
@@ -37,6 +38,17 @@
you may need to enter the password on every connection to the device,
or, if caching is enabled, at every \QC restart.
If you frequently run into the timeout, consider using key-based
authentication. Create an SSH key in \QC with the \c ssh-keygen tool.
On \macos and Linux, go to \preferences > \uicontrol Devices > \uicontrol SSH
and increase the time (in minutes) for sharing an SSH connection in the
\uicontrol {Connection sharing timeout} field. Windows does not support
shared connections.
\image qtcreator-ssh-options.png {SSH preferences}
//! [openssh]
\sa {Adding Docker Devices}, {Remote Linux}{How To: Develop for remote Linux},
{Run in Qt Application Manager}, {Remote Linux Deploy Configuration},
{Remote Linux Run Settings}

View File

@@ -39,9 +39,9 @@
You can connect bare metal devices to the development PC and use \QC
to debug applications on them with GDB or a hardware debugger.
\li \l{Connecting Boot2Qt Devices}
\li \l{Developing for \B2Q Devices}
You can connect \l{Boot2Qt} devices to the development PC to run,
You can connect \B2Q devices to the development PC to run,
debug, and analyze applications built for them from \QC.
\li \l {Adding Docker Devices}

View File

@@ -204,7 +204,7 @@
\list
\li \l {Developing for Bare Metal Devices}{Bare Metal}
\li \l {Boot2Qt}
\li \l {\B2Q}
\li \l {Remote Linux}
\li \l {Developing for MCUs}{Microcontrollers (MCU)}
\li \l {Connecting QNX Devices}{QNX}

View File

@@ -38,7 +38,7 @@
\li \image ok.png
\li \image ok.png
\row
\li \l Boot2Qt
\li \l {\B2Q}
\li \image ok.png
\li \image ok.png
\li \image ok.png

View File

@@ -25,10 +25,10 @@
the development environment for Android or iOS. For more information, see
\l{Developing for Android} and \l{Developing for iOS}.
To run an example application on a Boot2Qt device, you must set up
Boot2Qt on the development host and create connections
To run an example application on a \B2Q device, you must set up
\B2Q on the development host and create connections
between the host and devices. For more information, see
\l{Boot2Qt: Documentation}.
\l{\B2Q: Documentation}.
If you have \l{Qt Design Studio Manual}{\QDS} installed, you can open
\QDS examples from \QC in \QDS.
@@ -47,8 +47,8 @@
\li Select an example in the list of examples.
You can also use tags (3) to filter examples. For instance, enter
the \uicontrol Boot2Qt tag (commercial only) in the search field
(4) to list examples that you can run on Boot2Qt devices.
the \uicontrol \B2Q tag (commercial only) in the search field
(4) to list examples that you can run on \B2Q devices.
\li To check that you can compile and link the application code for a
device, click the \uicontrol {Kit Selector} and select a
@@ -80,5 +80,5 @@
\sa {Add compilers}, {Add kits}, {Add Qt versions},
{Developing for Android}, {Developing for iOS},
{Compile Output}, {Boot2Qt: Documentation}, {Qt Design Studio Manual}
{Compile Output}, {\B2Q: Documentation}, {Qt Design Studio Manual}
*/

View File

@@ -27,7 +27,7 @@
\list
\li \l{Developing for Android}{Android}
\li \l{Developing for Bare Metal Devices}{Bare Metal}
\li \l{Boot2Qt: Documentation}{Boot2Q} (commercial only)
\li \l{\B2Q: Documentation}{\B2Q} (commercial only)
\li \l{Adding Docker Devices}{Docker} (experimental)
\li \l{Developing for iOS}{iOS}
\li iOS Simulator
@@ -134,7 +134,7 @@
cross-compiling, leave this field empty.
\row
\li \uicontrol {Emulator skin}
\li Skin to use for the \l {Emulator}{Boot2Qt Emulator Device}.
\li Skin to use for the \l {Emulator}{\B2Q Emulator Device}.
\row
\li \uicontrol {Compiler}
\li C or C++ compiler that you use to build the project. You can add

View File

@@ -27,7 +27,7 @@
\list
\li \l {Android Run Settings}{Android}
\li \l {Boot2Qt Run Settings}{Boot2Qt}
\li \l {\B2Q Run Settings}{\B2Q}
\li \l {Desktop Device Run Settings}{Desktop}
\li \l {Python Run Settings}{Python}
\li \l {QNX Run Settings}{QNX}

View File

@@ -24,7 +24,6 @@
\li \l{Configuring Projects}
\li \l{Connecting Devices}
\list
\li \l{Connecting Boot2Qt Devices}
\li \l{Adding Docker Devices}
\li \l{Connecting QNX Devices}
\li \l{Building Applications for the Web}
@@ -58,6 +57,8 @@
\generatelist creator-how-to-android
\li Bare Metal
\generatelist creator-how-to-bare-metal
\li \B2Q
\generatelist creator-how-to-b2qt
\li iOS
\generatelist creator-how-to-ios
\li MCUs

View File

@@ -20,7 +20,7 @@
To preview a UI on an Android device, turn on USB debugging on the device
and connect it to the computer with a USB cable.
To preview a UI on a Boot2Qt device, connect the device to the computer
To preview a UI on a \B2Q device, connect the device to the computer
with a USB cable, or a wired or wireless connection, depending on
the device, and configure a connection to it. The necessary kits have been
predefined, but you need to select the one appropriate for your current
@@ -74,12 +74,12 @@
Learn more about \l{Viewing Applications on Android}.
\endif
\section2 On Boot2Qt
\section2 On \B2Q
Preview a UI on a supported Boot2Qt device that you configure as
instructed in the Boot2Qt documentation.
Preview a UI on a supported \B2Q device that you configure as
instructed in the \B2Q documentation.
\sa {Boot2Qt: Documentation}, {Support Levels for Target Hardware}
\sa {\B2Q: Documentation}, {Support Levels for Target Hardware}
\if defined(qtcreator)
\sa {Design UIs}{How To: Design UIs}, {UI Design}