// Copyright (C) 2023 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-how-tos.html

    \ingroup creator-how-to-docker

    \title Add Docker devices

    Create Docker devices from \l{https://docs.docker.com/get-started/overview/}
    {Docker images} and use them to build, run, and debug applications. A Docker
    container operates like a virtual machine but uses less system resources at
    the cost of being less flexible.

    While Linux, \macos, and Windows hosts are supported in principle, Linux is
    the recommended platform.

    To build, run, and debug applications on Docker devices, install and
    configure \c docker-cli on the development host. \QC automatically detects
    \l{kits-tab}{build and run kit} items, such \l{Add debuggers}
    {debuggers} and \l{Add Qt versions}{Qt versions}, in the Docker container
    and creates kits for the devices.

    You are advised to use CMake to build applications in the Docker container.

    \note Enable the Docker plugin to use it.

    To pull images from Docker hub or other registries, use the
    \l{https://docs.docker.com/engine/reference/commandline/pull/}{docker pull}
    command.

    \section1 Add Docker images as devices

    To add a Docker image as a device:

    \list 1
        \li Go to \preferences > \uicontrol Devices > \uicontrol Docker.
        \li In \uicontrol Command, enter the path to the Docker CLI.
            \image {qtcreator-preferences-devices-docker.webp} {Docker tab in Devices preferences}
        \li Go to \uicontrol Devices.
        \li Select \uicontrol Add > \uicontrol {Docker Device} >
            \uicontrol {Start Wizard} to search for images in your
            local Docker installation.
        \li Select a Docker image, and then select \uicontrol OK.
        \li In \uicontrol Devices, check and change Docker device preferences.
            \image {qtcreator-preferences-devices-docker-device.png} {Docker device in the Devices tab in Devices preferences}
        \li Select \uicontrol Apply to save your changes.
    \endlist

    \section2 Select Docker images

    The \uicontrol {Docker Image Selection} dialog displays a list of Docker
    images in your local Docker installation. You can sort the images according
    to the repository name or tag or the image ID or size.

    \image {qtcreator-docker-image-selection.webp} {Docker Image Selection dialog}

    Select \uicontrol {Show unnamed images} to show images that are not tagged.

    Double-click an image to select it.

    \section1 Edit Docker device kits

    Go to \preferences > \uicontrol Kits to check
    that the automatically generated kits point to the appropriate kit items.

    \sa {Enable and disable plugins}, {Docker}{How To: Develop for Docker},
    {Manage Kits}{How To: Manage Kits}
*/

/*!
    \page creator-preferences-docker.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-docker

    \title Set preferences for Docker devices

    \note Enable the Docker plugin to use it.

    To set preferences for Docker devices:

    \list 1
        \li Go to \preferences > \uicontrol Devices > \uicontrol Devices.
        \li In \uicontrol Device, select a Docker device.
            \image {qtcreator-preferences-devices-docker-device.png} {Docker device in the Devices tab in Devices preferences}
    \endlist

    The following table summarizes the preferences you can set.

    \table
    \header
        \li Option
        \li Value
    \row
        \li \uicontrol {Run as outside user}
        \li On Linux and \macos, sets the user ID and group ID of the user
            running \QC in the Docker container. This option is not available
            on Windows.
    \row
        \li \uicontrol {Do not modify entry point}
        \li Stops \QC from modifying the \l {Modify entry points}{entry point}
            of the image. Make sure that the entry point of the image does not exit immediately.
    \row
        \li \uicontrol {Enable flags needed for LLDB}
        \li Adds the following flags to the container to allow LLDB to run:
            \badcode
            --cap-add=SYS_PTRACE --security-opt seccomp=unconfined
            \endcode
    \row
        \li \uicontrol {Clangd executable}
        \li The path to a remote Clangd executable for a remote code model.
    \row
        \li \uicontrol {Paths to mount}
        \li Host directories to \l{Specify paths to mount}{mount} into the
            container, such as the project directory.
    \row
        \li \uicontrol {Search locations}
        \li Where to \l{Auto-detect kit items}{automatically detect} kit
            items.
    \endtable

    \section1 Modify entry points

    The entry point of a Docker container is specified in the container settings
    and started as the main process when starting the container. The entry point
    can be a shell, an SSH server, or another process, for example. By default,
    \QC modifies the entry point before it starts a container to make sure that
    the main process is an \c sh shell.

    To stop \QC from modifying the entry point, select
    \uicontrol {Do not modify entry point}. However, if the entry
    point you specify is not a shell, \QC cannot start the container.

    \section1 Specify paths to mount

    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, network mounts 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-detect kit items

    Select \uicontrol {Auto-detect Kit Items} to find kit items and create kits
    for the Docker device. You can search for kit items in the device's PATH or
    in the specified directories.

    In \uicontrol {Search locations}, select:

    \list
        \li \uicontrol {Search in PATH} to find kit items in PATH.
        \li \uicontrol {Search in Selected Directories} to find kit items in
            the selected directories.
        \li \uicontrol {Search in PATH and Additional Directories} to find kit
            items in the PATH and in the selected directories.
    \endlist

    When searching in directories, enter a semicolon-separated list of directory
    paths in the Docker image to scan for kit entries.

    To list the automatically detected kit items, select
    \uicontrol {List Auto-Detected Kit Items}. To remove
    them, select \uicontrol {Remove Auto-Detected Kit Items}.

    \sa {Enable and disable plugins}, {Docker}{How To: Develop for Docker},
    {Manage Kits}{How To: Manage Kits}
*/

/*!
    \page creator-how-to-build-run-docker.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-docker

    \title Build for and run on Docker devices

    \note Enable the Docker plugin to use it.

    To specify build settings for Docker images:

        \list 1
            \li Open a project for an application you want to develop for the
                device.
            \li Go to \uicontrol Projects > \uicontrol {Build & Run}, and
                activate the kit for Docker devices.
        \endlist

    Select \uicontrol Run to specify run settings. Usually, you can use
    the default settings.

    \sa {Enable and disable plugins}, {Docker}{How To: Develop for Docker},
    {Manage Kits}{How To: Manage Kits}
*/

/*!
    \page creator-how-to-build-on-docker.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-docker

    \title Build on Docker devices

    In addition to building applications \e {for} Docker, you can use the
    toolchain in Docker to build the applications \e {in} Docker.

    \note Enable the Docker plugin to use it.

    \include linux-mobile/creator-how-to-build-on-remote-devices.qdocinc {build on remote devices} {Docker device}

    \sa {Add CMake tools}, {Enable and disable plugins},
    {Docker}{How To: Develop for Docker}, {Manage Kits}{How To: Manage Kits}
*/
