Document how to create a reusable Group of files

Change-Id: I46050db2a95292a298e448fc2cfbfde04b1228d6
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Richard Weickelt <richard@weickelt.de>
Reviewed-by: Christian Kandeler <christian.kandeler@qt.io>

1 files changed, 74 insertions, 0 deletions

diff --git a/doc/howtos.qdoc b/doc/howtos.qdoc
index f394719e0..3a2f02525 100644
--- a/doc/howtos.qdoc
+++ b/doc/howtos.qdoc
@@ -48,6 +48,7 @@
     \li \l{How do I make the state of my Git repository available to my source files?}
     \li \l{How do I limit the number of concurrent jobs for the linker only?}
     \li \l{How do I add QML files to a project?}
+    \li \l{How do I define a reusable Group of files that can be included in other \QBS files?}
     \endlist
 
     \section1 How do I build a Qt-based project?
@@ -491,4 +492,77 @@
     In the example above, we declare each QML file as having the
     \l {filetags-qtcore}{"qt.core.resource_data"} file tag. This ensures
     that it is added to a generated resource file.
+
+    \section1 How do I define a reusable Group of files that can be included in other \QBS files?
+
+    Suppose you have an application and tests for that application, and that
+    the project is structured in the following way:
+
+    \badcode
+    ├── app
+    │   ├── app.qbs
+    │   ├── ...
+    │   └── qml
+    │       └── ui
+    │           ├── AboutPopup.qml
+    │           └── ...
+    ├── my-project.qbs
+    └── tests
+        ├── tst_app.cpp
+        ├── ...
+        └── tests.qbs
+    \endcode
+
+    Both projects need access to the QML files used by the
+    application. To demonstrate how this can be done, we'll create a file
+    named \c qml-ui.qbs and put it in the \c app/qml/ui directory:
+
+    \code
+    Group {
+        prefix: path + "/"
+        fileTags: ["qt.qml.qml", "qt.core.resource_data"]
+        files: [
+            "AboutPopup.qml",
+            // ...
+        ]
+    }
+    \endcode
+
+    This Group is a variation of the one in the
+    \l {How do I add QML files to a project?}{section above}.
+
+    If no prefix is specified, the file names listed in the \c files property
+    are resolved relative to the \e importing product's (e.g. \c app.qbs)
+    directory. For that reason, we set the prefix to inform \QBS that the file
+    names should be resolved relative to the \e imported item instead:
+    \c qml-ui.qbs. Conveniently, this also means that we don't need to specify
+    the path prefix for each file.
+
+    The application can then import the file like so:
+
+    \code
+    import "qml/ui/qml-ui.qbs" as QmlUiFiles
+
+    QtGuiApplication {
+        // ...
+
+        files: "main.cpp"
+
+        QmlUiFiles {}
+    }
+    \endcode
+
+    The tests can use a relative path to import the file:
+
+    \code
+    import "../app/qml/ui/qml-ui.qbs" as QmlUiFiles
+
+    QtGuiApplication {
+        // ...
+
+        files: "tst_app.cpp"
+
+        QmlUiFiles {}
+    }
+    \endcode
 */