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>

7 files changed, 92 insertions, 167 deletions

diff --git a/doc/qtcreator/images/qtcreator-embedded-linux-deployment-overview.png b/doc/qtcreator/images/qtcreator-embedded-linux-deployment-overview.png
deleted file mode 100644
index 25cdf5c7bf..0000000000
--- a/doc/qtcreator/images/qtcreator-embedded-linux-deployment-overview.png
+++ /dev/null
diff --git a/doc/qtcreator/src/cmake/creator-projects-cmake-deploying.qdocinc b/doc/qtcreator/src/cmake/creator-projects-cmake-deploying.qdocinc
deleted file mode 100644
index abef5908c8..0000000000
--- a/doc/qtcreator/src/cmake/creator-projects-cmake-deploying.qdocinc
+++ /dev/null
@@ -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]
-*/
diff --git a/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc b/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc
index 80f0e326ea..0258564a0b 100644
--- a/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc
+++ b/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
-    Android devices. You can also build single files to test your changes.
+    You can use CMake from \QC to build applications for the desktop, as well
+    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
 */
diff --git a/doc/qtcreator/src/linux-mobile/creator-deployment-b2qt.qdoc b/doc/qtcreator/src/linux-mobile/creator-deployment-b2qt.qdoc
index 40af933a85..b2b9b12805 100644
--- a/doc/qtcreator/src/linux-mobile/creator-deployment-b2qt.qdoc
+++ b/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
-    for \l{Boot2Qt} devices.
+    You can specify settings for deploying applications to \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}.
 */
diff --git a/doc/qtcreator/src/linux-mobile/creator-deployment-embedded-linux.qdoc b/doc/qtcreator/src/linux-mobile/creator-deployment-embedded-linux.qdoc
index 11d7ac3351..f149f741db 100644
--- a/doc/qtcreator/src/linux-mobile/creator-deployment-embedded-linux.qdoc
+++ b/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,42 +41,86 @@
     \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
-    the \uicontrol Projects mode, in \uicontrol {Run Settings}.
+    Linux devices in the project configuration file and in the
+    \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
-    project \c .pro file to add the missing files.
+    missing.
+
+    \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
-    on the remote device. Additional files can be deployed by adding them to
-    further targets and adding those to \c INSTALLS as well.
+    To deploy additional files, add them to further targets that you also add
+    to \c INSTALLS.
 
-    \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.
+
+    \section2 Finding Configured Devices
+
+    The \uicontrol {Check for a configured device} step looks for a device that
+    is ready for deployment.
+
+    \section2 Checking for Free Disk Space
 
-    When you run the application on the device, \QC
-    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.
+    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
+    space left to deploy your project. Errors due to lack of disk space can
+    otherwise be hard to detect.
+
+    \note If the SFTP upload fails, make sure that the remote device has SFTP
+    enabled in its SSH daemon. Some versions of Dropbear that come without SFTP
+    support will crash when an SFTP upload is being attempted. This is not a bug
+    in \QC.
+
+    \section2 Uploading Files
+
+    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
@@ -87,24 +131,12 @@
     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.
-
-    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
-    space left to deploy your project. Errors due to lack of disk space can
-    otherwise be hard to detect.
-
-    \note If the SFTP upload fails, make sure that the remote device has SFTP
-    enabled in its SSH daemon. Some versions of Dropbear that come without SFTP
-    support will crash when an SFTP upload is being attempted. This is not a bug
-    in \QC.
-
-    \if defined(qtcreator)
-    \include creator-projects-cmake-deploying.qdocinc cmake deploying embedded
-    \endif
 */
diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-generic.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-generic.qdoc
index df454aaa6d..ce96890fac 100644
--- a/doc/qtcreator/src/projects/creator-only/creator-projects-generic.qdoc
+++ b/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
-    \l {Deploying CMake Projects to Generic Remote Linux Devices}{here},
+    information. This works the same way as explained for CMake in
+    \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
diff --git a/doc/qtcreator/src/qnx/creator-deployment-qnx.qdoc b/doc/qtcreator/src/qnx/creator-deployment-qnx.qdoc
index 232a371e26..5ec8464312 100644
--- a/doc/qtcreator/src/qnx/creator-deployment-qnx.qdoc
+++ b/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
-    described in \l{Deploying Applications to Generic Remote Linux Devices}.
+    You can specify settings for deploying applications to QNX Neutrino
+    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 \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 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.
+    The deployment process is described in more detail in
+    \l{Deploying Applications to Generic Remote Linux Devices}.
 */