qt-creator/doc/qtcreator/src/docker/creator-docker.qdoc

// Copyright (C) 2022 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

    /*!
    \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.
*/