diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/appendix/json-api.qdoc | 1 | ||||
| -rw-r--r-- | doc/qbs.qdoc | 1 | ||||
| -rw-r--r-- | doc/reference/cli/builtin/cli-build.qdoc | 2 | ||||
| -rw-r--r-- | doc/reference/cli/builtin/cli-resolve.qdoc | 1 | ||||
| -rw-r--r-- | doc/reference/module-providers/qbspkgconfig-module-provider.qdoc | 11 | ||||
| -rw-r--r-- | doc/tutorial.qdoc | 96 |
6 files changed, 107 insertions, 5 deletions
diff --git a/doc/appendix/json-api.qdoc b/doc/appendix/json-api.qdoc index 02ec6aef3..7b093bc4e 100644 --- a/doc/appendix/json-api.qdoc +++ b/doc/appendix/json-api.qdoc @@ -126,7 +126,6 @@ \row \li dry-run \li bool \li no \row \li environment \li \l Environment \li no \row \li error-handling-mode \li string \li no - \row \li fallback-provider-enabled \li bool \li no \row \li force-probe-execution \li bool \li no \row \li log-time \li bool \li no \row \li log-level \li \l LogLevel \li no diff --git a/doc/qbs.qdoc b/doc/qbs.qdoc index bde1da008..83e461f29 100644 --- a/doc/qbs.qdoc +++ b/doc/qbs.qdoc @@ -80,6 +80,7 @@ \li \l{tutorial-6.html}{Project Properties} \li \l{tutorial-7.html}{Buildconfig Module} \li \l{tutorial-8.html}{Configurable Library} + \li \l{tutorial-9.html}{Version Header} \endlist \li \l{How-tos} \li \l{Reference} diff --git a/doc/reference/cli/builtin/cli-build.qdoc b/doc/reference/cli/builtin/cli-build.qdoc index 683b1ebb8..8547a78d2 100644 --- a/doc/reference/cli/builtin/cli-build.qdoc +++ b/doc/reference/cli/builtin/cli-build.qdoc @@ -78,8 +78,6 @@ \include cli-options.qdocinc products-specified \include cli-options.qdocinc settings-dir \include cli-options.qdocinc show-progress - \target no-fallback-module-provider - \include cli-options.qdocinc no-fallback-module-provider \include cli-options.qdocinc wait-lock \section1 Parameters diff --git a/doc/reference/cli/builtin/cli-resolve.qdoc b/doc/reference/cli/builtin/cli-resolve.qdoc index 4569980bd..99f1658ea 100644 --- a/doc/reference/cli/builtin/cli-resolve.qdoc +++ b/doc/reference/cli/builtin/cli-resolve.qdoc @@ -55,7 +55,6 @@ \include cli-options.qdocinc more-verbose \include cli-options.qdocinc settings-dir \include cli-options.qdocinc show-progress - \include cli-options.qdocinc no-fallback-module-provider \include cli-options.qdocinc deprecation-warnings \section1 Parameters diff --git a/doc/reference/module-providers/qbspkgconfig-module-provider.qdoc b/doc/reference/module-providers/qbspkgconfig-module-provider.qdoc index b5d720d01..a7f6fe6b7 100644 --- a/doc/reference/module-providers/qbspkgconfig-module-provider.qdoc +++ b/doc/reference/module-providers/qbspkgconfig-module-provider.qdoc @@ -99,6 +99,17 @@ */ /*! + \qmlproperty stringList qbspkgconfig::executableNames + + The names of the \c pkg-config executable to search for. + + Note that since newer distributions use \l{http://pkgconf.org}{pkgconf} by default, it has + higher priority over \c pkg-config. + + \defaultvalue \c{["pkgconf", "pkg-config"]} +*/ + +/*! \qmlproperty path qbspkgconfig::sysroot Set this property if you need to overwrite the default search sysroot path used by diff --git a/doc/tutorial.qdoc b/doc/tutorial.qdoc index 681d84758..b17cf4faf 100644 --- a/doc/tutorial.qdoc +++ b/doc/tutorial.qdoc @@ -44,6 +44,7 @@ \li \l{tutorial-6.html}{Project Properties} \li \l{tutorial-7.html}{Buildconfig Module} \li \l{tutorial-8.html}{Configurable Library} + \li \l{tutorial-9.html}{Version Header} \endlist */ @@ -481,7 +482,7 @@ /*! \previouspage tutorial-7.html \page tutorial-8.html - \nextpage howtos.html + \nextpage tutorial-9.html \title Configurable Library @@ -551,3 +552,96 @@ libmylib.a \endcode */ + +/*! + \previouspage tutorial-8.html + \page tutorial-9.html + \nextpage howtos.html + + \title Version Header + + To create new files, such as version headers, during the build, use \l{Rules}. Every command + \QBS executes, such as compile or linker commands, is described by a corresponding Rule in a + Module or a Product. + + In this section, we will create a simple header with a string constant based on the variable + in our project. + + First, we add this variable to our \c mybuildconfig module: + \snippet ../tutorial/chapter-9/qbs/modules/mybuildconfig/mybuildconfig.qbs 0 + + Next, we create a new file, \c{version.h.in}, located in the \c{version-header} directory. This + file contains the template for our header: + \snippet ../tutorial/chapter-9/version-header/version.h.in 0 + + Now we create a file called \c{version-header.qbs} in the same directory. This file contains + a \l{Product} with a \l{Rule} that turns the \c{version.h.in} into a real header. + Let's go through the contents of the file: + \snippet ../tutorial/chapter-9/version-header/version-header.qbs 0 + + First, we import \l{TextFile Service}{TextFile}. We will need this class to read the template + and write the resulting header. Second, we declare a new \l{Product} named \c{"version_header"} + and with the \c{"hpp"} type. This is the type of the artifact we will create in the Rule. + Third, we add the dependency on the \c mybuildconfig module to use the new + \c mybuildconfig.productVersion variable. + + We also add a \l{Group} with the template file and assign the \c{version_h_in} tag to the file: + \snippet ../tutorial/chapter-9/version-header/version-header.qbs 1 + + \QBS Rules work with file tags, instead of working with files directly, which makes + it easy to reuse rules. The name of the tag is chosen arbitrarily here. We could use the name + of the file as a tag, but to avoid confusion between file name and file tag, we use underscores + in the tag instead of dots. + + Now we can create a Rule itself: + \snippet ../tutorial/chapter-9/version-header/version-header.qbs 2 + Here, we specify that our Rule takes files tagged as \c "version_h_in" and produces an + \l{Artifact} with the name \c "version.h" and tagged \c "hpp". By default, files are created in + the \l{Product::destinationDirectory}{Product.destinationDirectory} folder. We add the \c "hpp" + tag for the header as this is the tag the \l{cpp}{cpp module} uses for headers. That way, \QBS + can track changes and process our generated file the same way it treats all other + headers. Note that earlier we set the product type to \c "hpp" as well. \QBS requires that + artifact type should match the product type directly or be accessible via the chain of Rules. + Otherwise, the Rule won't be executed. For details, see the \l{Rules and Product Types} + section. + + The actual code generation happens in the \l{Rule::prepare}{Rule.prepare} script: + \snippet ../tutorial/chapter-9/version-header/version-header.qbs 3 + + In this script, we create a \l {JavaScriptCommand} object and set some meta properties, such as + the description and highlight. For details about Commands, see + \l{Command and JavaScriptCommand}. In the sourceCode variable, we create a JavaScript + function that opens the \l{The inputs and outputs Variables}{input file}, reads its content + using the \l{TextFile Service}{TextFile} object, replaces the \c "${PRODUCT_VERSION}" + placeholder with the actual value in the \c product.mybuildconfig.productVersion variable, and + writes the resulting content into the \l{The inputs and outputs Variables}{output file}. + + Finally, we export the \l{Product::buildDirectory}{exportingProduct.buildDirectory} so that + products that depend on this product can include our generated header: + + \snippet ../tutorial/chapter-9/version-header/version-header.qbs 4 + + The full content of the file should look like this: + + \snippet ../tutorial/chapter-9/version-header/version-header.qbs 5 + + Let's now add our Product into the root project so \QBS will be aware of it: + \snippet ../tutorial/chapter-9/myproject.qbs 0 + + We also need to add the dependency on the \c "version_header" to our application: + \snippet ../tutorial/chapter-9/app/app.qbs 0 + + Now we can include the header in the \c main.c file and print the contents of the string + constant: + + \snippet ../tutorial/chapter-9/app/main.c 0 + + Let's try and run our application. You should see something like this: + \code + $ qbs run -p "My Application" + Starting target. Full command line: .../default/install-root/usr/local/bin/myapp + Hello, world + Hello from library + ProductVersion = 1.0.0 + \endcode +*/ |