From 59644542542202907c6635ae0c05bda975fa383e Mon Sep 17 00:00:00 2001 From: Christian Kandeler Date: Fri, 25 May 2018 10:35:44 +0200 Subject: Documentation: Work around qdoc quirk Apparently, the name of a snippet identifier cannot have the name of another snippet identifier as a substring. Change-Id: Ic82a26f3e05daa627f2de36d330e31216cf0a76e Reviewed-by: Leena Miettinen --- doc/reference/cli/builtin/cli-build.qdoc | 2 +- doc/reference/cli/builtin/cli-install.qdoc | 2 +- doc/reference/cli/builtin/cli-run.qdoc | 2 +- doc/reference/cli/cli-options.qdocinc | 4 ++-- 4 files changed, 5 insertions(+), 5 deletions(-) (limited to 'doc') diff --git a/doc/reference/cli/builtin/cli-build.qdoc b/doc/reference/cli/builtin/cli-build.qdoc index d2a418d85..cc5f4b27f 100644 --- a/doc/reference/cli/builtin/cli-build.qdoc +++ b/doc/reference/cli/builtin/cli-build.qdoc @@ -61,7 +61,7 @@ \include cli-options.qdocinc changed-files \include cli-options.qdocinc check-outputs \include cli-options.qdocinc check-timestamps - \include cli-options.qdocinc clean-install-root + \include cli-options.qdocinc clean_install_root \include cli-options.qdocinc command-echo-mode \include cli-options.qdocinc dry-run \include cli-options.qdocinc project-file diff --git a/doc/reference/cli/builtin/cli-install.qdoc b/doc/reference/cli/builtin/cli-install.qdoc index d68d4d922..3bddc4fcd 100644 --- a/doc/reference/cli/builtin/cli-install.qdoc +++ b/doc/reference/cli/builtin/cli-install.qdoc @@ -54,7 +54,7 @@ \include cli-options.qdocinc changed-files \include cli-options.qdocinc check-outputs \include cli-options.qdocinc check-timestamps - \include cli-options.qdocinc clean-install-root + \include cli-options.qdocinc clean_install_root \include cli-options.qdocinc command-echo-mode \include cli-options.qdocinc dry-run \include cli-options.qdocinc project-file diff --git a/doc/reference/cli/builtin/cli-run.qdoc b/doc/reference/cli/builtin/cli-run.qdoc index aa5441010..42bc8d4f9 100644 --- a/doc/reference/cli/builtin/cli-run.qdoc +++ b/doc/reference/cli/builtin/cli-run.qdoc @@ -58,7 +58,7 @@ \include cli-options.qdocinc changed-files \include cli-options.qdocinc check-outputs \include cli-options.qdocinc check-timestamps - \include cli-options.qdocinc clean-install-root + \include cli-options.qdocinc clean_install_root \include cli-options.qdocinc command-echo-mode \include cli-options.qdocinc dry-run \include cli-options.qdocinc project-file diff --git a/doc/reference/cli/cli-options.qdocinc b/doc/reference/cli/cli-options.qdocinc index 5316f459d..5ce7aab1c 100644 --- a/doc/reference/cli/cli-options.qdocinc +++ b/doc/reference/cli/cli-options.qdocinc @@ -100,13 +100,13 @@ //! [check-timestamps] -//! [clean-install-root] +//! [clean_install_root] \section2 \c --clean-install-root Removes the installation base directory before installing. -//! [clean-install-root] +//! [clean_install_root] //! [command-echo-mode] -- cgit v1.2.3 From 090a8ec57c9eb1559a112a219206dfe7815f5d98 Mon Sep 17 00:00:00 2001 From: Christian Kandeler Date: Mon, 28 May 2018 15:33:56 +0200 Subject: Add how-to for running autotests Change-Id: I438c6e754ea03a53306cc7d55debcc6574d2c2f9 Reviewed-by: Joerg Bornemann --- doc/howtos.qdoc | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) (limited to 'doc') diff --git a/doc/howtos.qdoc b/doc/howtos.qdoc index 714996e34..b9e2ef29c 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 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?} \li \l{How do I apply C/C++ preprocessor macros to only a subset of the files in my product?} @@ -132,6 +133,36 @@ } \endcode + \section1 How do I run my autotests? + + There are two simple things you need to do in your project. Firstly, you + mark your test executables as such. This is done by adding the tag \c{"autotest"} + to the product type: + \code + CppApplication { + name: "test1" + type: base.concat("autotest") + // ... + } + \endcode + The second step is to instantate an \l AutotestRunner product in your project: + \code + Project { + // ... + AutotestRunner { name: "run_my_tests" } + } + \endcode + Building an AutotestRunner product does not produce artifacts, but triggers execution of all + applications whose products are tagged as autotests: + \code + $ qbs -p run_my_tests + test1: PASS + test2: PASS + test3: FAIL + ... + \endcode + See the \l{AutotestRunner}{AutotestRunner documentation} for how to fine-tune the behavior. + \section1 How do I create a module for a third-party library? If you have pre-built binary files in your source tree, you can create -- cgit v1.2.3 From 0f0be9e1a7cc12e47d28c4dbc40185e11ea8256b Mon Sep 17 00:00:00 2001 From: Christian Kandeler Date: Mon, 28 May 2018 15:35:31 +0200 Subject: Fix copy/paste artifact in AutotestRunner documentation The workingDir property is of course a string. Change-Id: If0c5dbccb4debe20640cb4add0d0d13d0dc85d8e Reviewed-by: Joerg Bornemann --- doc/reference/items/convenience/autotestrunner.qdoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/reference/items/convenience/autotestrunner.qdoc b/doc/reference/items/convenience/autotestrunner.qdoc index f471d4bea..f4861835b 100644 --- a/doc/reference/items/convenience/autotestrunner.qdoc +++ b/doc/reference/items/convenience/autotestrunner.qdoc @@ -110,7 +110,7 @@ */ /*! - \qmlproperty stringList AutotestRunner::workingDir + \qmlproperty string AutotestRunner::workingDir If this property is set, it will be the working directory for all invoked test executables. Otherwise, the working directory will the the parent directory of the respective executable. -- cgit v1.2.3 From bb86d55c9e8614e6cf5819f0300d12d021402195 Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Wed, 30 May 2018 09:34:51 +0200 Subject: Doc: Fix a typo Change-Id: I143997ecbda03a290307d62c30adbca1527f7e0a Reviewed-by: Christian Kandeler --- doc/howtos.qdoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/howtos.qdoc b/doc/howtos.qdoc index b9e2ef29c..6039a23fb 100644 --- a/doc/howtos.qdoc +++ b/doc/howtos.qdoc @@ -145,7 +145,7 @@ // ... } \endcode - The second step is to instantate an \l AutotestRunner product in your project: + The second step is to instantiate an \l AutotestRunner product in your project: \code Project { // ... -- cgit v1.2.3 From 40746dae36452398649481fecad9cdc5f25cc80f Mon Sep 17 00:00:00 2001 From: Christian Kandeler Date: Mon, 14 May 2018 12:20:33 +0200 Subject: Add support for system-level settings In addition to the traditional per-user settings, there is now also a system-wide settings file affecting all users. The file's platform- specific default location can be overridden at build time. The qbs-config tool can write these settings via the new --system option. [ChangeLog] Introduced the concept of system-level qbs settings Change-Id: Ie6f675a74e96ce1fa7b2dd0712f6106071e848a6 Reviewed-by: Joerg Bornemann --- doc/qbs.qdoc | 4 +++ doc/reference/cli/cli-options.qdocinc | 37 +++++++++++++++++++++++ doc/reference/cli/tools/cli-config-ui.qdoc | 3 +- doc/reference/cli/tools/cli-config.qdoc | 24 +++++++++++++-- doc/reference/cli/tools/cli-setup-qt.qdoc | 5 +-- doc/reference/cli/tools/cli-setup-toolchains.qdoc | 5 +-- 6 files changed, 70 insertions(+), 8 deletions(-) (limited to 'doc') diff --git a/doc/qbs.qdoc b/doc/qbs.qdoc index b37ef4b95..bfeda503a 100644 --- a/doc/qbs.qdoc +++ b/doc/qbs.qdoc @@ -509,6 +509,10 @@ \row \li qbs_use_bundled_qtscript \li Use the bundled QtScript library. \endtable + In addition, you can set the \c QBS_SYSTEM_SETTINGS_DIR environment variable + before running qmake to specify a custom location for \QBS to look for its + system-level settings. + \section1 Using Docker A set of Docker images for developing \QBS (which are maintained by the \QBS team) is available diff --git a/doc/reference/cli/cli-options.qdocinc b/doc/reference/cli/cli-options.qdocinc index 5ce7aab1c..189a3526a 100644 --- a/doc/reference/cli/cli-options.qdocinc +++ b/doc/reference/cli/cli-options.qdocinc @@ -287,6 +287,33 @@ //! [list-root] +//! [config-user] + + \section2 \c {--user} + + Causes read operations to display only the user-level settings, + while the system-level settings are ignored. + Write operations will target the user-level settings, which is also the default. + +//! [config-user] + +//! [config-system] + + \section2 \c {--system} + + Read and write operations will consider only the system-level settings. + +//! [config-system] + +//! [config-ui-system] + + \section2 \c {--system} + + Instructs the tool to work on the system-level settings. Otherwise, + the user-level settings are presented. + +//! [config-ui-system] + //! [log-level] \section2 \c {--log-level } @@ -418,6 +445,16 @@ //! [show-progress] +//! [setup-tools-system] + + \section2 \c {--system} + + If this option is given, the profile(s) created by this tool will end up + in the system-level settings and thus be available to all users. + Otherwise, they go into the user-level settings. + +//! [setup-tools-system] + //! [type] \section2 \c {--type } diff --git a/doc/reference/cli/tools/cli-config-ui.qdoc b/doc/reference/cli/tools/cli-config-ui.qdoc index 29c0ed732..66f46e3e1 100644 --- a/doc/reference/cli/tools/cli-config-ui.qdoc +++ b/doc/reference/cli/tools/cli-config-ui.qdoc @@ -37,7 +37,7 @@ \section1 Synopsis \code - qbs config-ui [--settings-dir ] + qbs config-ui [--settings-dir ] [--system] \endcode \section1 Description @@ -54,6 +54,7 @@ \section1 Options \include cli-options.qdocinc settings-dir + \include cli-options.qdocinc config-ui-system \include cli-options.qdocinc help \section1 Examples diff --git a/doc/reference/cli/tools/cli-config.qdoc b/doc/reference/cli/tools/cli-config.qdoc index 0d2ba9989..e32ffee0e 100644 --- a/doc/reference/cli/tools/cli-config.qdoc +++ b/doc/reference/cli/tools/cli-config.qdoc @@ -36,10 +36,10 @@ \section1 Synopsis \code - qbs config [--settings-dir ] [--list [ ...]] + qbs config [--settings-dir ] [--user|--system] [--list [ ...]] [--unset ] [--export ] [--import ] - qbs config [--settings-dir ] - qbs config [--settings-dir ] + qbs config [--settings-dir ] [--user|--system] + qbs config [--settings-dir ] [--user|--system] \endcode \section1 Description @@ -52,6 +52,22 @@ The third form sets the specified \c with the specified \c . + There are two sets of settings: The system-level settings affect all users, + while the user-level settings are specific to the current user. + By default, the read operations consider both sources. If the same key is + present in both settings, then for list values, the system value is + appended to the user value, while for other types of values the user-level + one takes precedence. Write operations go to the user-level settings by default. + Use the \c {--user} and \c {--system} options to change this behavior. + \note It is conceivable that the default system value of the + \c {preferences.qbsSearchPaths} setting could pull in unwanted \QBS modules, + in particular when doing cross-builds. In such a case, you can set + \c {preferences.ignoreSystemSearchPaths} to exclude the search paths coming + from the system settings. You'll typically do this for a specific profile: + \code + $ qbs config profiles.myprofile.preferences.ignoreSystemSearchPaths true + \endcode + You can use the \l{config-ui} command to open the Qbs Settings tool for managing settings in a hierarchical view. @@ -65,6 +81,8 @@ \include cli-options.qdocinc unset \include cli-options.qdocinc export \include cli-options.qdocinc import + \include cli-options.qdocinc config-user + \include cli-options.qdocinc config-system \include cli-options.qdocinc help \section1 Parameters diff --git a/doc/reference/cli/tools/cli-setup-qt.qdoc b/doc/reference/cli/tools/cli-setup-qt.qdoc index 9673286b3..1cf961d0d 100644 --- a/doc/reference/cli/tools/cli-setup-qt.qdoc +++ b/doc/reference/cli/tools/cli-setup-qt.qdoc @@ -36,8 +36,8 @@ \section1 Synopsis \code - qbs setup-qt [--settings-dir ] --detect - qbs setup-qt [--settings-dir ] + qbs setup-qt [--settings-dir ] [--system] --detect + qbs setup-qt [--settings-dir ] [--system] \endcode \section1 Description @@ -56,6 +56,7 @@ \include cli-options.qdocinc detect-qt-versions \include cli-options.qdocinc settings-dir + \include cli-options.qdocinc setup-tools-system \include cli-options.qdocinc help \section1 Examples diff --git a/doc/reference/cli/tools/cli-setup-toolchains.qdoc b/doc/reference/cli/tools/cli-setup-toolchains.qdoc index 15490cc2a..af3b25069 100644 --- a/doc/reference/cli/tools/cli-setup-toolchains.qdoc +++ b/doc/reference/cli/tools/cli-setup-toolchains.qdoc @@ -36,8 +36,8 @@ \section1 Synopsis \code - qbs setup-toolchains [--settings-dir ] --detect - qbs setup-toolchains [--settings-dir ] [--type ] + qbs setup-toolchains [--settings-dir ] [--system] --detect + qbs setup-toolchains [--settings-dir ] [--system] [--type ] \endcode @@ -57,6 +57,7 @@ \section1 Options \include cli-options.qdocinc settings-dir + \include cli-options.qdocinc setup-tools-system \include cli-options.qdocinc detect-toolchains \include cli-options.qdocinc type \include cli-options.qdocinc help -- cgit v1.2.3