Doc: Describe deploying apps to embedded Linux devices

- Describe deployment process in the instructions for generic
  remote Linux devices and link to there from the instructions
  for specific devices.
- Update instructions for adding files when using CMake and remove
  the include file.
- Add an example of adding files to deploy when using qmake.

Fixes: QTCREATORBUG-26616
Change-Id: I07cf9169da384dd65adc6935110e4dcbeb3e308b
Reviewed-by: Samuli Piippo <samuli.piippo@qt.io>

doc/qtcreator/src/cmake/creator-projects-cmake-deploying.qdocinc

@@ -1,106 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2017 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the Qt Creator documentation.
-**
-** 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.
-**
-****************************************************************************/
-
-// **********************************************************************
-// NOTE: the sections are not ordered by their logical order to avoid
-// reshuffling the file each time the index order changes (i.e., often).
-// Run the fixnavi.pl script to adjust the links to the index order.
-// **********************************************************************
-
-/*!
-//! [cmake deploying embedded]
-
-    \section1 Deploying CMake Projects to Generic Remote Linux Devices
-
-    \QC cannot directly extract files to be installed from a CMake project.
-    Therefore, a special deploy step is created that installs the project into
-    a local directory. The files in that directory are then deployed to the
-    remote device.
-    Alternatively, you can provide a \c {QtCreatorDeployment.txt} file in which
-    you must specify all files to be deployed which are not executables or
-    libraries. You place this file in either the root directory of the CMake
-    project or the build directory of the active build configuration.
-    Currently, \QC first checks the root directory and only if no
-    \c {QtCreatorDeployment.txt} exists it checks the active build directory.
-
-    Use the following syntax in the file:
-
-    \code
-    <deployment/prefix>
-    <relative/source/file1>:<relative/destination/dir1>
-    ...
-    <relative/source/filen>:<relative/destination/dirn>
-    \endcode
-
-    Where:
-
-    \list
-
-        \li \c {<deployment/prefix>} is the (absolute) path prefix to where
-            files are copied on the remote machine.
-
-        \li \c {<relative/source/file>} is the file path relative to the CMake
-            project root. No directories or wildcards are allowed in this
-            value.
-
-        \li \c {<relative/destination/dir>} is the destination directory path
-            relative to \c {deployment/prefix}.
-
-    \endlist
-
-    To automate the creation of \c {QtCreatorDeployment.txt} file:
-
-    \list 1
-
-        \li Define the following macros in the top level \c {CMakeLists.txt}
-            file:
-
-            \code
-            file(WRITE "${CMAKE_SOURCE_DIR}/QtCreatorDeployment.txt" "<deployment/prefix>\n")
-
-            macro(add_deployment_file SRC DEST)
-                file(RELATIVE_PATH path ${CMAKE_SOURCE_DIR} ${CMAKE_CURRENT_SOURCE_DIR})
-                file(APPEND "${CMAKE_SOURCE_DIR}/QtCreatorDeployment.txt" "${path}/${SRC}:${DEST}\n")
-            endmacro()
-
-            macro(add_deployment_directory SRC DEST)
-                file(GLOB_RECURSE files RELATIVE "${CMAKE_CURRENT_SOURCE_DIR}" "${SRC}/*")
-                foreach(filename ${files})
-                    get_filename_component(path ${filename} PATH)
-                    add_deployment_file("${filename}" "${DEST}/${path}")
-                endforeach(filename)
-            endmacro()
-            \endcode
-
-        \li Use \c {add_deployment_file(<file/name>)} to add files and
-            \c {add_deployment_directory(<folder/name>)} to add directories
-             (including subdirectories) to the \c QtCreatorDeployment.txt file.
-
-        \li Re-run \c cmake after you add or remove files using the macros.
-
-    \endlist
-
-//! [cmake deploying embedded]
-*/

doc/qtcreator/src/cmake/creator-projects-cmake.qdoc

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2021 The Qt Company Ltd.
+** Copyright (C) 2022 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -42,8 +42,9 @@
     native build configurations and workspaces that you can use in the compiler
     environment of your choice.
 
-    You can use CMake from \QC to build applications for the desktop and
+    You can use CMake from \QC to build applications for the desktop, as well
-    Android devices. You can also build single files to test your changes.
+    as mobile and embedded devices. You can also build single files to test
+    your changes.
 
     \QC automatically detects the CMake executable specified in the \c PATH.
     You can add paths to other CMake executables and use them in different
@@ -168,6 +169,6 @@
         \li \l {Opening Projects}
         \li \l {CMake Build Configuration}
         \li \l {Specifying Run Settings}
-        \li \l {Deploying CMake Projects to Generic Remote Linux Devices}
+        \li \l {Deploying Applications to Generic Remote Linux Devices}
     \endlist
 */

doc/qtcreator/src/linux-mobile/creator-deployment-b2qt.qdoc

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2021 The Qt Company Ltd.
+** Copyright (C) 2022 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -30,13 +30,18 @@
 
     \title Deploying Applications to Boot2Qt Devices
 
-    You can specify the generic deployment steps for remote Linux devices also
+    You can specify settings for deploying applications to \l{Boot2Qt} devices
-    for \l{Boot2Qt} devices.
+    in the project configuration file and in \uicontrol Projects >
+    \uicontrol {Run Settings} > \uicontrol Deployment.
 
     \image qtcreator-boot2qt-deployment-steps.png "Boot2Qt deployment steps"
 
-    For more information, see \l{Generic Deployment Steps}.
+    The deployment process is described in more detail in
+    \l{Deploying Applications to Generic Remote Linux Devices}.
+
+    \section1 Launching Applications on Boot
 
     In addition, to have your application launch on boot, select
-    \uicontrol {Add Deploy Step} > \uicontrol {Change Default Application}.
+    \uicontrol {Add Deploy Step} > \uicontrol {Change default application}
+    > \uicontrol {Set this application to start by default}.
 */

doc/qtcreator/src/linux-mobile/creator-deployment-embedded-linux.qdoc

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2020 The Qt Company Ltd.
+** Copyright (C) 2022 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -41,58 +41,70 @@
     \title Deploying Applications to Generic Remote Linux Devices
 
     You can specify settings for deploying applications to generic remote
-    Linux devices in the project .pro file. You can view the settings in
+    Linux devices in the project configuration file and in the
-    the \uicontrol Projects mode, in \uicontrol {Run Settings}.
+    \uicontrol Projects mode, in \uicontrol {Run Settings}.
 
-    \image qtcreator-embedded-linux-deployment-overview.png "Deploy to device"
+    \image qtcreator-embedded-linux-deployment-details.png "Deploy to embedded Linux"
 
     The files to be installed are listed in the \uicontrol {Deployment} step,
     the \uicontrol {Files to deploy} field. The \uicontrol {Local File Path}
     field displays the location of the file on the development PC. The
-    \uicontrol {Remote Directory} field displays the folder where the file is
+    \uicontrol {Remote Directory} field displays the directory where the file is
     installed on the device. Text in red color indicates that the information is
-    missing. Edit the qmake \l{Variables#installs} {INSTALLS variable} in the
+    missing.
-    project \c .pro file to add the missing files.
+
+    \section1 Adding Missing Files
+
+    The process to add files to deploy depends on the build system you use.
+
+    \section2 CMake
+
+    When using CMake as the build system, use the \l{CMake: install command}
+    {install} command in the CMakeLists.txt file to add the missing files.
+
+    For example, add the following lines to the CMakeLists.txt file to install
+    the binary of your project to the \c /opt directory on the remote device:
+
+    \badcode
+    set(INSTALL_DESTDIR "/opt")
+
+    install(TARGETS <target>
+        RUNTIME DESTINATION "${INSTALL_DESTDIR}"
+        BUNDLE DESTINATION "${INSTALL_DESTDIR}"
+        LIBRARY DESTINATION "${INSTALL_DESTDIR}"
+    )
+    \endcode
+
+    \section2 qmake
+
+    When using qmake, edit the \l{Variables#installs}{INSTALLS variable} in
+    the project \c .pro file.
 
     When you run the application, \QC copies the necessary files to the device
     and starts the application on it.
 
-    For example, adding
+    For example, add the following lines to the \c .pro file to copy the binary
+    of your project to the \c /opt directory on the remote device:
 
     \code
-      target.path = /root
+      target.path = /opt
       INSTALLS += target
     \endcode
 
-    to the project .pro file will copy the binary of your project to \c /root
+    To deploy additional files, add them to further targets that you also add
-    on the remote device. Additional files can be deployed by adding them to
+    to \c INSTALLS.
-    further targets and adding those to \c INSTALLS as well.
 
-    \section1 Generic Deployment Steps
+    \section1 Deploy Steps
 
-    \image qtcreator-embedded-linux-deployment-details.png "Deploy to embedded Linux"
+    When you run the application on the device, \QC first uploads the
+    necessary files to it, as specified by the deploy steps.
 
-    When you run the application on the device, \QC
+    \section2 Finding Configured Devices
-    deploys the application as specified by the deploy steps. By default, \QC
-    copies the application files to the device by using the SSH file transfer
-    protocol (SFTP), as specified by the \uicontrol {Upload files via SFTP}
-    step.
 
-    If you have a lot of data to copy, select \uicontrol Details in the
+    The \uicontrol {Check for a configured device} step looks for a device that
-    \uicontrol {Upload Files via SFTP} step, and then select the
+    is ready for deployment.
-    \uicontrol {Incremental deployment} check box. \QC takes note of the
-    deployment time and only copies files that have changed since the last
-    deployment. However, when you make major changes on the device, such as
-    removing files from the device manually or flashing a new disk image, or
-    when you use another device with the same IP address, deselect the check box
-    once, to have \QC deploy all files again.
 
-    To only create a tarball and not copy the files to the device, select
+    \section2 Checking for Free Disk Space
-    \uicontrol {Add Deploy Step} > \uicontrol {Create tarball}. Then remove all
-    other deploy steps.
-
-    The \uicontrol {Deploy tarball via SFTP upload} step specifies that \QC
-    uploads the tarball to the device and extracts it.
 
     The \uicontrol {Check for free disk space} step is by default the first
     deploy step. Use it to find out whether the remote file system has enough
@@ -104,7 +116,27 @@
     support will crash when an SFTP upload is being attempted. This is not a bug
     in \QC.
 
-    \if defined(qtcreator)
+    \section2 Uploading Files
-    \include creator-projects-cmake-deploying.qdocinc cmake deploying embedded
+
-    \endif
+    By default, \QC copies the application files to the device by
+    using the SSH file transfer protocol (SFTP), as specified by
+    the \uicontrol {Upload files via SFTP} step.
+
+    If you have a lot of data to copy, select \uicontrol Details in the
+    \uicontrol {Upload Files via SFTP} step, and then select the
+    \uicontrol {Incremental deployment} check box. \QC takes note of the
+    deployment time and only copies files that have changed since the last
+    deployment. However, when you make major changes on the device, such as
+    removing files from the device manually or flashing a new disk image, or
+    when you use another device with the same IP address, deselect the check box
+    once, to have \QC deploy all files again.
+
+    \section2 Creating a Tarball
+
+    To only create a tarball and not copy the files to the device, select
+    \uicontrol {Add Deploy Step} > \uicontrol {Create tarball}. Then remove all
+    other deploy steps.
+
+    The \uicontrol {Deploy tarball via SFTP upload} step specifies that \QC
+    uploads the tarball to the device and extracts it.
 */

doc/qtcreator/src/projects/creator-only/creator-projects-generic.qdoc

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2019 The Qt Company Ltd.
+** Copyright (C) 2022 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -144,8 +144,8 @@
     If you want to run your application on a generic remote Linux device,
     you first need to deploy your executable and possibly other files.
     \QC does that for you automatically if you provide the necessary
-    information. This works the same way as explained for CMake
+    information. This works the same way as explained for CMake in
-    \l {Deploying CMake Projects to Generic Remote Linux Devices}{here},
+    \l {Deploying Applications to Generic Remote Linux Devices},
     except that you also need to include your application binary in the list.
 
     \section1 Creating a Run Configuration

doc/qtcreator/src/qnx/creator-deployment-qnx.qdoc

@@ -1,13 +1,13 @@
 /****************************************************************************
 **
-** This file is part of Qt Creator
-**
 ** Copyright (C) 2018 Blackberry
-**
 ** Contact: Blackberry (qt@blackberry.com)
 ** Contact: KDAB (info@kdab.com)
 **
-** This file is part of the documentation of the Qt Toolkit.
+** Copyright (C) 2022 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt Creator documentation.
 **
 ** Commercial License Usage
 ** Licensees holding valid commercial Qt licenses may use this file in
@@ -40,19 +40,12 @@
 
     \title Deploying Applications to QNX Neutrino Devices
 
-    You can deploy applications to QNX Neutrino devices in the way that is
+    You can specify settings for deploying applications to QNX Neutrino
-    described in \l{Deploying Applications to Generic Remote Linux Devices}.
+    devices in the project configuration file and in \uicontrol Projects
+    > \uicontrol {Run Settings} > \uicontrol Deployment.
 
     \image qtcreator-qnx-deployment.png "Deploy to device"
 
-    The files to be installed are listed in the \uicontrol {Deployment} step,
+    The deployment process is described in more detail in
-    the \uicontrol {Files to deploy} field. The
+    \l{Deploying Applications to Generic Remote Linux Devices}.
-    \uicontrol {Local File Path} field displays the location of the file on the
-    development PC. The \uicontrol {Remote Directory} field displays the folder
-    where the file is installed on the device. Text in red color indicates that
-    the information is missing. Edit the qmake \l{Variables#installs}
-    {INSTALLS variable} in the project \c .pro file to add the missing files.
-
-    When you run the application, \QC copies the necessary files to the device
-    and starts the application on it.
 */