Add documentation for qbs build helper and qbs toolchain (#1978)

* Add documentation for qbs build helper

* Add documentation for qbs toolchain

* Add documentation for attributes of qbs build helper

* Update reference/build_helpers/qbs.rst

* Update reference/build_helpers/qbs.rst

* Update creating_packages/toolchains/qbs.rst

* Update creating_packages/toolchains/qbs.rst

* Update creating_packages/toolchains/qbs.rst

* Update creating_packages/toolchains/qbs.rst

* Update creating_packages/toolchains/qbs.rst

* Update creating_packages/toolchains/qbs.rst

* Update creating_packages/toolchains/qbs.rst

* Update creating_packages/toolchains/qbs.rst

* Update creating_packages/toolchains/qbs.rst

* Update creating_packages/toolchains/qbs.rst

* Update creating_packages/toolchains/qbs.rst

* Update creating_packages/toolchains/qbs.rst

* Update creating_packages/toolchains/qbs.rst

* Fixed copy & paste error

* Removed project name to simplify line

* Referenced rst files

Co-authored-by: Daniel <[email protected]>

creating_packages/toolchains.rst

@@ -117,3 +117,4 @@ Built-in toolchains
    toolchains/make
    toolchains/meson
    toolchains/msbuild
+   toolchains/qbs

creating_packages/toolchains/qbs.rst

@@ -0,0 +1,66 @@
+.. _conan-qbs-toolchain:
+
+QbsToolchain
+==============
+
+.. warning::
+
+    This is an **experimental** feature subject to breaking changes in future releases.
+
+
+The ``QbsToolchain`` can be used in the ``generate()`` method:
+
+
+.. code:: python
+
+    from conans import ConanFile
+    from conan.tools.qbs import QbsToolchain
+
+    class App(ConanFile):
+        settings = "os", "arch", "compiler", "build_type"
+        requires = "hello/0.1"
+        options = {"shared": [True, False]}
+        default_options = {"shared": False}
+
+        def generate(self):
+            tc = QbsToolchain(self)
+            tc.generate()
+
+
+The ``QbsToolchain`` will generate the following file during :command:`conan install`
+command (or before calling the ``build()`` method when the package is being
+built in the cache): *conan_toolchain.qbs*. This file will contain a qbs profile
+named *conan_toolchain_profile*.
+
+
+*conan_toolchain.qbs* will contain the definitions of all the Qbs properties
+related to the Conan options and settings for the current package, platform,
+etc. This includes the following:
+
+  * Detection of compiler.
+
+  * Based on the compiler set in environment variable ``CC``.
+
+  * Uses detected system compiler based on Conan setting ``compiler`` if environment variable ``CC`` is not set.
+
+* Detection of compiler flags from environment (as defined at https://www.gnu.org/software/make/manual/html_node/Implicit-Variables.html):
+
+  * ``ASFLAGS``
+
+  * ``CFLAGS``
+
+  * ``CPPFLAGS``
+
+  * ``CXXFLAGS``
+
+  * ``LDFLAGS``
+
+* Detection of sysroot from environment.
+
+* Detection of ``build_type`` from Conan settings.
+
+* Detection of ``arch`` from Conan settings.
+
+* Detection of ``compiler.cxxstd`` from Conan settings.
+
+* Detection of ``fPIC`` based on the existence of such option in the recipe.

reference/build_helpers.rst

@@ -16,8 +16,9 @@ Contents:
    build_helpers/visual_studio
    build_helpers/meson
    build_helpers/run_environment
+   build_helpers/qbs
 
 .. important::
 
     If you need a build helper for any other tools, please check how you can create your own
-    :ref:`custom_build_helper`.
+    :ref:`custom_build_helper`.

reference/build_helpers/qbs.rst

@@ -0,0 +1,159 @@
+.. _qbs_build_reference:
+
+Qbs
+===
+
+If you are using **Qbs** as your build system, you can use the **Qbs** build helper.
+
+.. code-block:: python
+
+    from conans import ConanFile, tools, Qbs
+    import os
+
+    class ConanFileToolsTest(ConanFile):
+        ...
+
+        def build(self):
+            qbs = Qbs(self)
+            qbs.build()
+
+Constructor
+-----------
+
+.. code-block:: python
+
+    class Qbs(object):
+
+        def __init__(self, conanfile, project_file=None)
+
+Parameters:
+    - **conanfile** (Required): Use ``self`` inside a ``conanfile.py``.
+    - **project_file** (Optional, Defaulted to ``None``): Path to the root project file.
+
+Attributes
+----------
+
+use_toolchain_profile
++++++++++++++++++++++
+
+**Defaulted to**: ``conan_toolchain_profile``
+
+Specifies the qbs profile to build the project for.
+
+jobs
+++++
+
+**Defaulted to**: ``tools.cpu_count()``
+
+Specifies the number of concurrent build jobs.
+
+Methods
+-------
+
+add_configuration()
++++++++++++++++++++
+
+.. code-block:: python
+
+    def add_configuration(self, name, values)
+
+Add a build configuration to use.
+
+Parameters:
+    - **name** (Required): Specifies build configuration name.
+    - **values** (Required): A dict of properties set for this build configuration.
+
+
+build()
++++++++
+
+.. code-block:: python
+
+    def build(self, products=None)
+
+Build Qbs project.
+
+Parameters:
+    - **products** (Optional, Defaulted to ``None``): Specifies a list of products to build. If ``None`` build all products which have the qbs property ``buildByDefault`` set to ``true``.
+
+
+build_all()
++++++++++++
+
+.. code-block:: python
+
+    def build_all(self)
+
+Build all products of Qbs project, even products which set the qbs property ``buildByDefault`` set to ``false``
+
+
+install()
++++++++++
+
+.. code-block:: python
+
+    def install(self)
+
+Install products.
+
+
+Example
+-------
+
+A typical usage of the Qbs build helper, if you want to be able to both execute :command:`conan create` and also build your package for a
+library locally (in your user folder, not in the local cache), could be:
+
+.. code-block:: python
+
+    from conans import ConanFile, Qbs
+
+    class HelloConan(ConanFile):
+        name = "hello"
+        version = "0.1"
+        settings = "os", "compiler", "build_type", "arch"
+        generators = "qbs"
+        exports_sources = "src/*", "*.qbs"
+        no_copy_source = True
+        requires = "zlib/1.2.11"
+
+        def build(self):
+            qbs = Qbs(self)
+            qbs.add_configuration("default", {
+                "project.conanBuildInfo", self.build_folder + "/conanbuildinfo.qbs"
+            })
+            qbs.build()
+
+        def package(self):
+            self.copy("*.h", dst="include", src="src")
+            self.copy("*.lib", dst="lib", keep_path=False)
+            self.copy("*.dll", dst="bin", keep_path=False)
+            self.copy("*.dylib*", dst="lib", keep_path=False)
+            self.copy("*.so", dst="lib", keep_path=False)
+            self.copy("*.a", dst="lib", keep_path=False)
+
+        def package_info(self):
+            self.cpp_info.libs = ["hello"]
+
+Note the ``qbs`` generator, which generates the *conanbuildinfo.qbs* file, to process
+dependencies information. Setting ``no_copy_source = True`` helps qbs to pick the right project file
+and not get confused by the generated files.
+
+The *hello.qbs* could be as simple as:
+
+.. code-block:: text
+
+    Project {
+        readonly property path conanBuildInfo
+
+        references: conanBuildInfo
+
+        DynamicLibrary {
+            name: "hello"
+            version: "0.1.0"
+            files: "src/hello.cpp"
+            cpp.cxxLanguageVersion: "c++11"
+
+            Depends { name: "cpp" }
+            Depends { name: "zlib" }
+        }
+    }