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

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

    \ingroup creator-how-to-build
    \ingroup creator-how-to-docker

    \title Use Development Containers

    Use Development Containers (dev container) to define and configure a consistent
    development environment for your project across developers and automated build
    or test systems.

    You can run dev containers either locally or remotely in a cloud for running
    applications, for separating tools, libraries, or runtimes that you need when
    working with a codebase, or for continuous integration and testing.

    A dev container environment can differ from the deployment environment as they
    typically include tools and utilities needed during development that are not
    required for final deployment.

    For the full specification and the \c devcontainer.json file format, see the
    \l{Development Containers} documentation.

    \note Enable the Development Container Support plugin to use it.

    \section1 Configure dev containers

    To configure a dev container for \QC:

    \list 1
        \li Create a \c devcontainer.json file in your project directory.
        \li Add a \c qt-creator section under \c customizations in the
            \c devcontainer.json file.
        \li Use the customization options described in this topic to customize
            the dev container.
    \endlist

    \section1 Customization options for dev containers

    The following table shows the available options for customizing \QC in the
    \c devcontainer.json file.

    \table
    \header
        \li Property
        \li Type
        \li Description
    \row
        \li \c auto-detect-kits
        \li \c boolean
        \li Set to \c true to try to automatically detect a kit in the dev container.
    \row
        \li \c run-processes-in-terminal
        \li \c boolean
        \li Set to \c true to run some of the dev container setup processes in
            a terminal window. Currently only used for \c {docker build}.
    \row
        \li \c copy-cmd-bridge
        \li \c boolean
        \li Set to \c true to copy the Command Bridge Helper, a service for
            communicating with remote devices, into the dev container
            instead of trying to mount it. This is useful if the dev container is
            not able to mount the host filesystem.
    \row
        \li \c mount-libexec
        \li \c boolean
        \li Set to \c true to mount the \c libexec directory into the dev container.
            This is used for the Command Bridge Helper.
    \row
        \li \c libexec-mount-point
        \li \c string
        \li Specify the mount point for the \c libexec directory in the dev container.
            This is used for the Command Bridge Helper.
    \row
        \li \c kits
        \li an array of objects
        \li Specify the custom kits to be used in the dev container.
    \endtable

    \section2 Configuration for typical local development

    The following example \c devcontainer.json file shows how to configure the dev
    container for a typical local development workflow. It enables automatic detection
    of kits, mounts the \c libexec directory into the container, and specifies the
    mount point.

    This setup is useful when you want \QC to automatically find available build
    kits and ensure that required helper tools from the \c libexec directory are
    accessible inside the container.

    \code
    {
        "customizations": {
            "qt-creator": {
                "device": {
                    "auto-detect-kits": true,
                    "run-processes-in-terminal": false,
                    "copy-cmd-bridge": false,
                    "mount-libexec": true,
                    "libexec-mount-point": "/devcontainer/libexec"
                }
            }
        }
    }
    \endcode

    \section2 Configuration for custom kits and toolchains

    The following example \c devcontainer.json file demonstrates how to configure
    a dev container when you need to use a specific Qt version, compiler, or toolchain
    inside the container. This is useful for cross-compilation, supporting multiple
    build configurations, or ensuring a consistent development environment across teams.

    This configuration file disables automatic kit detection and instead defines a
    custom kit using the \c kits property. The kit specifies the Qt version, compiler
    paths, CMake binary and generator, and debugger to be used by \QC within the
    dev container.

    The configuration file also uses the optional \c {cmake.variables} property
    to pass arbitrary CMake variables when \QC configures the project. Each key
    is a CMake variable name, and the value can be:

    \list
        \li A plain string
        \li An array of strings (joined with \c {;} into a single CMake list value)
        \li An object with a \c value field and an optional \c type field
            (\c BOOL, \c STRING, \c FILEPATH, \c PATH, \c STATIC, or \c INTERNAL).
            The type is appended to the CMake command line as
            \c {-DVAR_NAME:TYPE=value}.
    \endlist

    \code
    {
        "customizations": {
            "qt-creator": {
                "auto-detect-kits": false,
                "kits": [
                    {
                        "name": "My DevContainer Kit",
                        "qt": "/6.7.0/gcc_64/bin/qmake6",
                        "compiler": {
                            "Cxx": "/usr/bin/c++",
                            "C": "/usr/bin/gcc"
                        },
                        "cmake": {
                            "binary": "/usr/bin/cmake",
                            "generator": "Unix Makefiles",
                            "variables": {
                                "CMAKE_BUILD_TYPE": "Release",
                                "CMAKE_PREFIX_PATH": ["/opt/qt", "/usr/local"],
                                "BUILD_TESTING": {
                                    "type": "BOOL",
                                    "value": "OFF"
                                }
                            }
                        },
                        "debugger": "/usr/bin/lldb"
                    }
                ]
            }
        }
    }
    \endcode

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