diff --git a/doc/qtcreator/images/qtcreator-docker-image-selection.png b/doc/qtcreator/images/qtcreator-docker-image-selection.png new file mode 100644 index 00000000000..72401c2f320 Binary files /dev/null and b/doc/qtcreator/images/qtcreator-docker-image-selection.png differ diff --git a/doc/qtcreator/images/qtcreator-docker-preferences.png b/doc/qtcreator/images/qtcreator-docker-preferences.png new file mode 100644 index 00000000000..0b087201778 Binary files /dev/null and b/doc/qtcreator/images/qtcreator-docker-preferences.png differ diff --git a/doc/qtcreator/src/docker/creator-docker.qdoc b/doc/qtcreator/src/docker/creator-docker.qdoc new file mode 100644 index 00000000000..5f758065a4e --- /dev/null +++ b/doc/qtcreator/src/docker/creator-docker.qdoc @@ -0,0 +1,133 @@ +/**************************************************************************** +** +** 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 +** 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. +** +****************************************************************************/ + + /*! + \page creator-adding-docker-devices.html + \previouspage creator-developing-b2qt.html + \nextpage creator-developing-generic-linux.html + + \title Adding Docker Devices + + You can add \l{ https://docs.docker.com/get-started/overview/} + {Docker images} as \e devices to run, debug, and analyze applications + built for the Docker container from \QC. A Docker device operates like + a virtual machine but uses less system resources at the cost of being + less flexible. + + Docker support is experimental. While Linux, \macos, and Windows hosts are + supported in principle, Linux is the recommended platform. + + Currently, only CMake is supported for building applications in the Docker + container. + + You can run applications locally or in a compatible Docker container. To be + able to run and debug applications on Docker devices, you must install Docker + as well as add Docker devices and select them in the kit. \QC automatically + detects kits in the shared Docker directories, but you need to check that + they point to the correct kit items. + + Use a wizard to search for Docker images available on your local Docker + installation and add them as devices. To access images from Docker hub or + other registries, you first need to pull the images using the + \l{https://docs.docker.com/engine/reference/commandline/pull/}{docker pull} + command. You can edit the Docker device preferences later in + \uicontrol Edit > \uicontrol Preferences > \uicontrol Devices. + + To enable the experimental Docker plugin: + + \list 1 + \li In \QC, select \uicontrol Help > \uicontrol {About Plugins} > + \uicontrol Utilities > \uicontrol {Docker (experimental)}. + \li Select \uicontrol {Restart Now} to restart \QC and load the plugin. + \endlist + + To add a Docker image as a device: + + \list 1 + \li Select \uicontrol Edit > \uicontrol Preferences > \uicontrol Devices + > \uicontrol Devices > \uicontrol Add > \uicontrol {Docker Device} + > \uicontrol {Start Wizard} to search for images in your local Docker + installation. + \image qtcreator-docker-image-selection.png "Docker Image Selection dialog" + \li Select the Docker image to use, and then select \uicontrol OK. + \note If the Docker process is not found, make sure that Docker is + running and the Docker CLI executable is set in PATH. + \li In \uicontrol Devices, check and modify Docker device preferences. + \image qtcreator-docker-preferences.png "Docker Device preferences" + \li Select \uicontrol {Run as outside user} to use the user ID and + group ID of the user running \QC in the Docker container. + \li In \uicontrol {Paths to mount}, specify host directories to mount + into the container, such as the project directory. + \li Select \uicontrol {Auto-detect Kit Items} to generate an initial + \l{Adding Kits}{build and run kit} for the Docker device. + \endlist + + \section1 Specifying Paths to Mount + + You can either copy your project files into the Docker container or specify + paths to them in \uicontrol {Paths to mount}. Shared mounts are restricted + to locations in the host system that can end up in the same absolute location + in the Docker container. On Windows, mounted drives cannot be used as shared + mounts. + + The paths in \uicontrol {Paths to mount} are mapped one-to-one to the Docker + container. Select \uicontrol Insert to browse directories to add. Select + \uicontrol {Delete Line} to delete the selected path or \uicontrol Clear + to delete all paths. + + \section1 Auto-detecting Kit Items + + Select \uicontrol {Auto-detect Kit Items} to generate an initial + \l{Adding Kits}{build and run kit} for the Docker device. You can + either set the kit items, such \l{Adding Debuggers}{debuggers} and + \l{Adding Qt Versions}{Qt version}, in PATH or install them in the + Docker container. + + Select \uicontrol {Search in PATH} to detect kit items that are set in PATH. + + Select \uicontrol {Search in Selected Directories} to detect kit items in + the selected directories. + + To view the automatically detected kit items, select + \uicontrol {List Auto-Detected Kit Items}. To remove + them, select \uicontrol {Remove Auto-Detected Kit Items}. + + \section1 Editing Docker Device Kits + + Select \uicontrol Edit > \uicontrol Preferences > \uicontrol Kits to check + that the automatically generated kit points to the appropriate kit items. + + 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 + the kit that you specified above. + \endlist + + Select \uicontrol Run to specify run settings. Usually, you can use + the default settings. +*/ diff --git a/doc/qtcreator/src/linux-mobile/b2qtdev.qdoc b/doc/qtcreator/src/linux-mobile/b2qtdev.qdoc index ffbfcb4feaf..bb2b7214725 100644 --- a/doc/qtcreator/src/linux-mobile/b2qtdev.qdoc +++ b/doc/qtcreator/src/linux-mobile/b2qtdev.qdoc @@ -26,7 +26,7 @@ /*! \page creator-developing-b2qt.html \previouspage creator-developing-baremetal.html - \nextpage creator-developing-generic-linux.html + \nextpage creator-adding-docker-devices.html \title Connecting Boot2Qt Devices diff --git a/doc/qtcreator/src/linux-mobile/linuxdev.qdoc b/doc/qtcreator/src/linux-mobile/linuxdev.qdoc index acc5f5591d7..1af5707f830 100644 --- a/doc/qtcreator/src/linux-mobile/linuxdev.qdoc +++ b/doc/qtcreator/src/linux-mobile/linuxdev.qdoc @@ -29,7 +29,7 @@ \previouspage creator-developing-android.html \nextpage studio-advanced.html \else - \previouspage creator-developing-b2qt.html + \previouspage creator-adding-docker-devices.html \nextpage creator-developing-ios.html \endif diff --git a/doc/qtcreator/src/overview/creator-only/creator-mobile-targets.qdoc b/doc/qtcreator/src/overview/creator-only/creator-mobile-targets.qdoc index 4b54044fcbe..ed7ff74f5aa 100644 --- a/doc/qtcreator/src/overview/creator-only/creator-mobile-targets.qdoc +++ b/doc/qtcreator/src/overview/creator-only/creator-mobile-targets.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. @@ -74,6 +74,13 @@ You can connect \l{Boot2Qt} devices to the development PC to run, debug, and analyze applications built for them from \QC. + \if defined(qtcreator) + \li \l {Adding Docker Devices} + + You can add Docker images as \e devices to run, debug, and analyze + applications built for Docker containers from \QC. + \endif + \li \l{Connecting Generic Remote Linux Devices} If you have a tool chain for building applications for embedded diff --git a/doc/qtcreator/src/qtcreator-toc.qdoc b/doc/qtcreator/src/qtcreator-toc.qdoc index ec7e5148726..c904ac14892 100644 --- a/doc/qtcreator/src/qtcreator-toc.qdoc +++ b/doc/qtcreator/src/qtcreator-toc.qdoc @@ -169,6 +169,8 @@ \list \li \l{Connecting Android Devices} \li \l{Connecting Bare Metal Devices} + \li \l{Connecting Boot2Qt Devices} + \li \l{Adding Docker Devices} \li \l{Connecting Generic Remote Linux Devices} \li \l{Connecting iOS Devices} \li \l{Connecting MCUs}