/****************************************************************************
**
** Copyright (C) 2020 Richard Weickelt
** Contact: https://www.qt.io/licensing/
**
** This file is part of Qbs.
**
** $QT_BEGIN_LICENSE:FDL$
** 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.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \qmltype ConanfileProbe
    \inqmlmodule QbsProbes
    \ingroup list-of-items
    \keyword QML.ConanfileProbe

    \brief Extracts information about dependencies from a Conan recipe file.

    The \c ConanfileProbe interfaces \QBS to the \l{https://conan.io/}{Conan
    package manager}. It runs
    \l{https://docs.conan.io/en/latest/reference/commands/consumer/install.html}{conan
    install} on a Conan recipe file such as \c conanfile.py or \c conanfile.txt
    and extracts all available meta information about package dependencies using
    the \l{https://docs.conan.io/en/latest/reference/generators/json.html}{json
    generator}. The output may be used to set up \l{Profile} items or module
    properties in products. \c ConanfileProbe can also be used to run other
    Conan generators and to retrieve their output.

    \note This probe only works with Conan 1.x since the \c json generator was removed in Conan
    2.0. Use the \l{conan}{conan} module provider and \c QbsDeps generator with Conan 2.0 instead.

    \section1 Examples

    In the following examples we assume that our project contains a \c conanfile.py.
    This file describes all dependencies of our project. The dependency packages are
    expected to export meta information to be consumed by our project.

    \section2 Including Files Generated by Conan

    Conan has a built-in
    \l{https://docs.conan.io/en/latest/reference/generators/qbs.html}{qbs
    generator} that creates a project file containing dummy products. This is
    the easiest way to access dependencies, but also the least flexible one. It
    requires each Conan package to export correct meta information and works only
    if the dependency is a library.

    \qml
    import qbs.Probes

    Project {
        Probes.ConanfileProbe {
            id: conan
            conanfilePath: project.sourceDirectory + "/conanfile.py"
            generators: "qbs"
        }

        references: conan.generatedFilesPath + "/conanbuildinfo.qbs"

        CppApplication {
            type: "application"
            files: "main.cpp"
            Depends { name: "mylib" }
        }
    }
    \endqml

    \section2 Setting Module Properties in Products

    When a product depends on a Conan package that does not have a
    dedicated \l{List of Modules}{module}, package meta information may be
    directly fed into the \l{cpp} module.

    This approach is very flexible.

    \qml
    import qbs.Probes

    CppApplication {
        Probes.ConanfileProbe {
            id: conan
            conanfilePath: product.sourceDirectory + "/conanfile.py"
            options: ({opt1: "True"; opt2: "TheValue"})
        }
        cpp.includePaths: conan.dependencies["myLib"].include_paths
        cpp.libraryPaths: conan.dependencies["myLib"].lib_paths
        cpp.dynamicLibraries: conan.dependencies["mylib"].libs
    }
    \endqml

    \section2 Setting Up a Profile

    When multiple products depend on one or more Conan packages, the dependency
    information may be combined in a \l{Profile}. This is especially useful when
    \QBS modules are available for some of the packages, but some of their
    properties need to be initialized. Otherwise, it would have to be done
    manually in global profiles.

    \qml
    import qbs.Probes

    Project {
        Probes.ConanfileProbe {
            id: conan
            conanfilePath: project.sourceDirectory + "/conanfile.py"
        }
        Profile {
            name: "arm-gcc"
            cpp.toolchainInstallPath: conan.dependencies["arm-none-eabi-gcc"].rootpath + "/bin"
            cpp.toolchainPrefix: "arm-linux-gnueabi-"
            qbs.toolchainType: "gcc"
        }
    }
    \endqml

    This allows fully automated dependency management, including compiler
    toolchains and is very useful when teams work in heterougeneous
    environments.

*/

/*!
    \qmlproperty stringList ConanfileProbe::additionalArguments

    Additional command line arguments that are appended to the \c{conan install}
    command.

    \defaultvalue []
*/

/*!
    \qmlproperty path ConanfileProbe::conanfilePath

    Path to a \c conanfile.py or \c conanfile.txt that is used by this probe.

    This property cannot be set at the same time as \l{ConanfileProbe::}{packageReference}.

    \nodefaultvalue
*/

/*!
    \qmlproperty var ConanfileProbe::dependencies

    This property contains the same information as
    \l{ConanfileProbe::}{json}.dependencies, but instead of an array, \c
    dependencies is a map with package names as keys for convenient access.

    \readonly
    \nodefaultvalue
*/

/*!
    \qmlproperty path ConanfileProbe::executable

    The name of or the path to the Conan executable.

    \defaultvalue "conan.exe" on Windows, "conan" otherwise
*/

/*!
    \qmlproperty path ConanfileProbe::generatedFilesPath

    The path of the folder where Conan generators store their files. Each
    instance of this probe creates a unique folder under
    \l{Project::buildDirectory}{Project.buildDirectory}. The folder name is a
    hash of the arguments supplied to \c{conan install}.

    \readonly
    \nodefaultvalue
*/

/*!
    \qmlproperty stringList ConanfileProbe::generators

    Conan generators to be executed by this probe. The
    \l{https://docs.conan.io/en/latest/reference/generators/json.html}{JSON
    generator} is always enabled. Generated files are written to the
    \l{ConanfileProbe::generatedFilesPath}{generatedFilesPath} folder.

    \sa {https://docs.conan.io/en/latest/reference/generators.html}{Available
    generators}

    \defaultvalue ["json"]
*/

/*!
    \qmlproperty var ConanfileProbe::json

    The parsed output of Conan's
    \l{https://docs.conan.io/en/latest/reference/generators/json.html}{JSON
    generator} as a JavaScript object.

    \readonly
    \nodefaultvalue
*/

/*!
    \qmlproperty var ConanfileProbe::options

    Options applied to \c{conan install} via the \c{-o} flag.
    This property is an object in the form \c{key:value}.

    Example:
    \qml
    options: ({someOpt: "True", someOtherOpt: "TheValue"})
    \endqml

    \nodefaultvalue
*/

/*!
    \qmlproperty string ConanfileProbe::packageReference

    Reference of a Conan package in the form \c{name/version@user/channel}.
    Use this property if you want to probe an existing package in the local
    cache or on a remote.

    This property cannot be set at the same time as \l{ConanfileProbe::}{conanfilePath}.

    \nodefaultvalue
*/

/*!
    \qmlproperty var ConanfileProbe::settings

    Settings applied to \c{conan install} via the \c{-s} flag.
    This property is an object in the form \c{key:value}.

    Example:
    \qml
    settings: ({os: "Linux", compiler: "gcc"})
    \endqml

    \nodefaultvalue
*/

/*!
    \qmlproperty var ConanfileProbe::verbose

    Set to \c{true} to print all output of `conan install`.
    If this property is \c{false} only error output will be printed.

    \defaultvalue \c{false}
*/
