Add ConanfileProbe item for querying conan recipe files

Conan is a popular C/C++ package manager. Conan packages including their
configuration and dependencies are usually described as conanfile.txt/.py.
ConanfileProbe runs 'conan install -g json' and parses the resulting
conanbuildinfo.json. The resulting JS object tree contains relevant information
about the dependencies and can be used to set module properties in Product,
Profile or even Module items.

Change-Id: Ied6b917f061dac67fb2260eab099bcce4037750d
Reviewed-by: Christian Kandeler <christian.kandeler@qt.io>

1 files changed, 250 insertions, 0 deletions

diff --git a/doc/reference/items/probe/conanfile-probe.qdoc b/doc/reference/items/probe/conanfile-probe.qdoc
new file mode 100644
index 000000000..c18e9b322
--- /dev/null
+++ b/doc/reference/items/probe/conanfile-probe.qdoc
@@ -0,0 +1,250 @@
+/****************************************************************************
+**
+** 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$
+**
+****************************************************************************/
+
+/*!
+    \contentspage list-of-probes.html
+    \qmltype ConanfileProbe
+    \ingroup list-of-probes
+    \ingroup list-of-items
+    \inqmlmodule QbsLanguageItems
+    \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.
+
+    \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.generatorOutputPath + "/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
+*/