diff options
Diffstat (limited to 'doc/howtos.qdoc')
| -rw-r--r-- | doc/howtos.qdoc | 179 |
1 files changed, 179 insertions, 0 deletions
diff --git a/doc/howtos.qdoc b/doc/howtos.qdoc index f394719e0..696c444cb 100644 --- a/doc/howtos.qdoc +++ b/doc/howtos.qdoc @@ -37,6 +37,8 @@ \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 build release with debug information?} + \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?} @@ -48,6 +50,8 @@ \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?} + \li \l{How do I print the value of a property?} \endlist \section1 How do I build a Qt-based project? @@ -127,6 +131,89 @@ } \endcode + \section1 How do I build release with debug information? + + You can simply use the \c{"profiling"} \l{qbs::buildVariant}{qbs.buildVariant}: + \code + qbs build qbs.buildVariant:profiling + \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 + + Now, you can install your \l{Application}{application}, \l{DynamicLibrary}{dynamic library} + or \l{LoadableModule}{loadable module} among with its debugging symbols as follows: + \code + CppApplication { + // ... + install: true + installDir: "bin" + installDebugInformation: true + debugInformationInstallDir: "bin" + } + \endcode + + If you are not using \l{List of Convenience Items}{convenience items}, + you can install debug symbols manually using the \l{Group} item. 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). + + \code + Product { + type: "application" + Depends { name: "cpp" } + cpp.debugInformation: qbs.buildVariant !== "release" + cpp.separateDebugInformation: true + 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 + Product { + type: "dynamic_library" + // ... + 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 + Product { + type: "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 @@ -491,4 +578,96 @@ 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 + + \section1 How do I print the value of a property? + + Use the \l {Console API}{console API}. For example, suppose your project + is not built the way you expect it to be, and you suspect that + \c qbs.targetOS has the wrong value: + + \code + readonly property bool unix: qbs.targetOS.contains("unix") + \endcode + + To find out the value of \c qbs.targetOS, use \c {console.info()}: + + \code + readonly property bool unix: { + console.info("qbs.targetOS: " + qbs.targetOS) + return qbs.targetOS.contains("unix") + } + \endcode */ |