Docs: Clarify the connection between file tags, rules and product type.

Task-number: QBS-984
Change-Id: I4324e387ec4124f3f5f638ab8d627fc33f6f21a9
Reviewed-by: Joerg Bornemann <joerg.bornemann@qt.io>

2 files changed, 32 insertions, 2 deletions

diff --git a/doc/qbs.qdoc b/doc/qbs.qdoc
index 80b4764cc..d913c2338 100644
--- a/doc/qbs.qdoc
+++ b/doc/qbs.qdoc
@@ -633,8 +633,10 @@
     \QBS applies a \e rule to a pool of artifacts (in the beginning it is just the set of
     source files of the project) and chooses the ones that match the input file
     tags specified by the rule. Then it creates output artifacts in the build graph that have other
-    filenames and file tags. It also creates a script that transforms the input artifact into the
-    output artifact.
+    filenames and file tags. It also creates a script that transforms the input artifacts into the
+    output artifacts. Artifacts created by one rule can (and typically do) serve as inputs to
+    another rule. In this way, rules are connected to one another via their input and output
+    file tags.
 
     For examples of rules, see the share/qbs/modules directory in the \QBS
     repository.
diff --git a/doc/reference/items/rule.qdoc b/doc/reference/items/rule.qdoc
index a578c14ca..25a5a07cc 100644
--- a/doc/reference/items/rule.qdoc
+++ b/doc/reference/items/rule.qdoc
@@ -89,6 +89,34 @@
     }
     \endcode
 
+    It is important to know that when figuring out which rules to execute, \QBS starts at the
+    product type and then looks for a way to produce artifacts with matching file tags from
+    source files, using a chain of rules that are connected by their respective input and output
+    tags. For instance, consider this simple C++ project:
+    \code
+    Product {
+        type: ["application"]
+        Depends { name: "cpp" }
+        files: ["main.cpp"]
+    }
+    \endcode
+    Here's how this product is built:
+    \list 1
+        \li \QBS looks for a rule that can produce artifacts with the file tag
+            \c{"application"}. Such a rule is found in the \c cpp module (namely, the rule that
+            invokes the linker).
+        \li Since the rule found in the previous step takes inputs of type \c{"obj"}, \QBS now
+            looks for a rule that produces artifacts of that type. Again, such a rule is found in
+            the \c cpp module (the rule that runs the compiler).
+        \li The rule found in the previous step takes inputs of type \c{"cpp"}. No rule is found
+            that creates such artifacts, but we do have a source file with a matching type (because
+            the \c cpp module contains a \l{FileTagger item}{FileTagger} which attached that type
+            to \c{"main.cpp"} due to its file extension).
+        \li Now that there is a chain of rules leading from a source file tag to the product type,
+            the commands of these rules are executed one after the other until we end up with
+            our executable.
+    \endlist
+
     \section1 Rule Properties
 
     \table