From f8ba1f5c8d029840d24f342e92b116e5d107a835 Mon Sep 17 00:00:00 2001
From: Christian Kandeler <christian.kandeler@qt.io>
Date: Fri, 20 Jul 2018 11:11:11 +0200
Subject: Documentation: Add How-to about "generated sources"

We've seen people try to add generated C++ source files to a files
property, so let's make clear how it actually works.

Change-Id: I8a7dd8b1af71662efbeb72a3780775f5a6ca38d6
Reviewed-by: Joerg Bornemann <joerg.bornemann@qt.io>
---
 doc/howtos.qdoc | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

(limited to 'doc')

diff --git a/doc/howtos.qdoc b/doc/howtos.qdoc
index cc982023d..dd1b45130 100644
--- a/doc/howtos.qdoc
+++ b/doc/howtos.qdoc
@@ -38,6 +38,7 @@
     \li \l{How do I build a Qt-based project?}
     \li \l{How do I make my app build against my library?}
     \li \l{How do I use precompiled headers?}
+    \li \l{How do I make sure my generated sources are getting compiled?}
     \li \l{How do I run my autotests?}
     \li \l{How do I create a module for a third-party library?}
     \li \l{How do I create application bundles and frameworks on iOS, macOS, tvOS, and watchOS?}
@@ -130,6 +131,42 @@
     }
     \endcode
 
+    \section1 How do I make sure my generated sources are getting compiled?
+
+    The rules in a \QBS project do not care whether its inputs are actual source files
+    listed on the right-hand side of a \l{Product::files}{files} property or artifacts
+    that were generated by another rule. For instance, the C++ compiler rule considers
+    all input files of type "cpp", no matter how they got into the product. The following
+    example project demonstrates this. One of its source files exists in the repository,
+    the other one is generated at build time. Both are getting compiled the same way.
+    \note Do not try to add the generated files to a \c files property. Declaring them
+    as rule outputs is all that is needed to make \QBS know about them.
+    \code
+    import qbs.TextFile
+    CppApplication {
+        files: ["impl.cpp", "impl.h"]
+        cpp.includePaths: sourceDirectory
+        Rule {
+            multiplex: true
+            Artifact { filePath: "main.cpp"; fileTags: "cpp" }
+            prepare: {
+                var cmd = new JavaScriptCommand();
+                cmd.description = "generating " + output.fileName;
+                cmd.sourceCode = function() {
+                    var f = new TextFile(output.filePath, TextFile.WriteOnly);
+                    f.writeLine("#include <impl.h>");
+                    f.writeLine("int main()");
+                    f.writeLine("{");
+                    f.writeLine("    return functionFromImpl();");
+                    f.writeLine("}");
+                    f.close();
+                };
+                return cmd;
+            }
+        }
+    }
+    \endcode
+
     \section1 How do I run my autotests?
 
     There are two simple things you need to do in your project. Firstly, you
-- 
cgit v1.2.3