Merge 1.5 into master.

Change-Id: I93e4943cf8112ce1088c34a43928d2133bc7dca7

2 files changed, 38 insertions, 2 deletions

diff --git a/doc/qbs.qdoc b/doc/qbs.qdoc
index 574ed4a2f..8e09f22df 100644
--- a/doc/qbs.qdoc
+++ b/doc/qbs.qdoc
@@ -319,9 +319,15 @@
 
     The \a name is the name of the product. In this case it is also the
     name of the produced executable (on Windows, the ".exe" extension is added by default).
+
     In the property \a files, we specify the source files for our product.
     Unlike QML, the right-hand side can be either a string or a string list.
     A single string is converted to a stringlist containing just one element.
+    So we could have also written
+
+    \code
+    files: [ "main.cpp" ]
+    \endcode
 
     \a Depends adds the dependency to the module \l{Module cpp}{cpp}. This is necessary to let \QBS know that
     we have a C++ project and want to compile main.cpp with a C++ compiler. For more information
@@ -621,8 +627,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 509839d2d..659405912 100644
--- a/doc/reference/items/rule.qdoc
+++ b/doc/reference/items/rule.qdoc
@@ -122,6 +122,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