From f4ba1c69e2e06e7bb443b1a6fbd30833d2fcdc24 Mon Sep 17 00:00:00 2001
From: Ivan Komissarov <abbapoh@gmail.com>
Date: Tue, 3 Mar 2020 18:09:04 +0200
Subject: doc: add How-To section about separating debug info

Change-Id: I8ae6f90da242b47ecbae7f9aeb11cebdf227ca73
Reviewed-by: Christian Kandeler <christian.kandeler@qt.io>
---
 doc/howtos.qdoc                       | 59 +++++++++++++++++++++++++++++++++++
 doc/reference/modules/cpp-module.qdoc |  2 ++
 2 files changed, 61 insertions(+)

(limited to 'doc')

diff --git a/doc/howtos.qdoc b/doc/howtos.qdoc
index b63e2ca96..9512cb0a9 100644
--- a/doc/howtos.qdoc
+++ b/doc/howtos.qdoc
@@ -37,6 +37,7 @@
     \list
     \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 separate and install debugging symbols?}
     \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?}
@@ -129,6 +130,64 @@
     }
     \endcode
 
+    \section1 How do I separate and install debugging symbols?
+
+    First, you need to set the \l{cpp::debugInformation}{cpp.debugInformation} and
+    \l{cpp::separateDebugInformation}{cpp.separateDebugInformation}
+    properties to \c true or use some conditional expression in your product:
+    \code
+    CppApplication {
+        // ...
+        cpp.debugInformation: qbs.buildVariant !== "release"
+        cpp.separateDebugInformation: true
+    }
+    \endcode
+
+    If the \l{cpp::separateDebugInformation}{cpp.separateDebugInformation} property is set to
+    \c true, \QBS will create debugging symbols with the corresponding file tags
+    \c "debuginfo_app" (for an application), \c "debuginfo_dll" (for a dynamic library),
+    or \c "debuginfo_loadablemodule" (for a macOS plugin).
+
+    Now, you can install your application and its debugging symbols as follows:
+    \code
+    CppApplication {
+        // ...
+        Group {
+            fileTagsFilter: cpp.separateDebugInformation ? ["debuginfo_app"] : []
+            qbs.install: true
+            qbs.installDir: "bin"
+            qbs.installSourceBase: buildDirectory
+        }
+    }
+    \endcode
+
+    If you're building a shared library, you need to use the \c "debuginfo_dll" tag instead:
+    \code
+    DynamicLibrary {
+        // ...
+        Group {
+            fileTagsFilter: cpp.separateDebugInformation ? ["debuginfo_dll"] : []
+            qbs.install: true
+            qbs.installDir: "lib"
+            qbs.installSourceBase: buildDirectory
+        }
+    }
+    \endcode
+
+    If you're building a macOS plugin, you need to use the \c "debuginfo_loadablemodule"
+    tag instead:
+    \code
+    LoadableModule {
+        // ...
+        Group {
+            fileTagsFilter: cpp.separateDebugInformation ? ["debuginfo_loadablemodule"] : []
+            qbs.install: true
+            qbs.installDir: "PlugIns"
+            qbs.installSourceBase: buildDirectory
+        }
+    }
+    \endcode
+
     \section1 How do I use precompiled headers?
 
     If you use a \l Group item to add a precompiled header file to a product
diff --git a/doc/reference/modules/cpp-module.qdoc b/doc/reference/modules/cpp-module.qdoc
index 72a934847..2fc592d4e 100644
--- a/doc/reference/modules/cpp-module.qdoc
+++ b/doc/reference/modules/cpp-module.qdoc
@@ -390,6 +390,8 @@
 
     \defaultvalue \c{true} for MSVC and with GCC or Clang on Apple platforms,
     otherwise \c{false}.
+
+    \sa debugInformation, {How do I separate and install debugging symbols?}
 */
 
 /*!
-- 
cgit v1.2.3