diff options
Diffstat (limited to 'doc/qbs.qdoc')
| -rw-r--r-- | doc/qbs.qdoc | 216 |
1 files changed, 181 insertions, 35 deletions
diff --git a/doc/qbs.qdoc b/doc/qbs.qdoc index 7fcc7e68b..83e461f29 100644 --- a/doc/qbs.qdoc +++ b/doc/qbs.qdoc @@ -67,8 +67,21 @@ \li \l{Generators} \li \l{Multiplexing} \li \l{Custom Modules and Items} + \li \l{Special Property Values} \li \l{Module Providers} \endlist + \li \l{Tutorial} + \list + \li \l{tutorial-1.html}{Console Application} + \li \l{tutorial-2.html}{Static Library} + \li \l{tutorial-3.html}{Dynamic Library} + \li \l{tutorial-4.html}{Convenience Items} + \li \l{tutorial-5.html}{Autotest} + \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} \list @@ -461,7 +474,7 @@ To build \QBS from the source, you need: \list - \li Qt 5.14, or later + \li Qt 5.15, or later \li Windows: MinGW with GCC 4.9 or Microsoft Visual Studio 2015, or later \li Linux: GCC 4.9, or later, or Clang 3.9.0, or later @@ -556,7 +569,6 @@ \row \li qbs_no_dev_install \li Exclude header files from installation, that is, perform a non-developer build. \row \li qbs_no_man_install \li Exclude the man page from installation. - \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 @@ -643,11 +655,6 @@ \li Holds whether the Qt libraries that \QBS depends on will be bundled with \QBS during the \c install step. This option is only implemented on macOS. \row - \li useBundledQtScript - \li \c false - \li Use the bundled QtScript module instead of the one shipped with Qt. In that case, - QtScript should be checked out as a git submodule. - \row \li libDirName \li \c "lib" \li Directory name used by \c libInstallDir and \c importLibInstallDir properties. @@ -1067,12 +1074,12 @@ \li \l{Generators} \li \l{Multiplexing} \li \l{Custom Modules and Items} + \li \l{Special Property Values} \li \l{Module Providers} \endlist */ - /*! \previouspage usage.html \page language-introduction.html @@ -1213,27 +1220,17 @@ } \endcode - A module can implicitly depend on other modules. For example, the - \l{Qt.core} module depends on the \l{cpp} module. However, to set the - properties of a module, you must make the dependency explicit. + A module can depend on other modules. For example, the + \l{Qt.core} module depends on the \l{cpp} module. The module dependencies are transitive, + i.e. in a Product, all dependent modules are accessible: \code - // THIS DOES NOT WORK - Application { - name: "helloworld" - files: ["main.cpp"] - Depends { name: "Qt.core" } - cpp.optimization: "ludicrousSpeed" - // ERROR! We do not know about "cpp" here, - // though "Qt.core" depends on "cpp". - } - - // THIS WORKS Application { name: "helloworld" files: ["main.cpp"] Depends { name: "Qt.core" } - Depends { name: "cpp" } + // the "cpp" module is available since + // "Qt.core" depends on "cpp". cpp.optimization: "ludicrousSpeed" } \endcode @@ -1263,7 +1260,7 @@ This is how you do it: \code Group { - condition: qbs.targetOS.contains("windows") + condition: qbs.targetOS.includes("windows") files: [ "harddiskdeleter_win.cpp", "blowupmonitor_win.cpp", @@ -1271,7 +1268,7 @@ ] } Group { - condition: qbs.targetOS.contains("linux") + condition: qbs.targetOS.includes("linux") files: [ "harddiskdeleter_linux.cpp", "blowupmonitor_linux.cpp", @@ -1287,8 +1284,6 @@ \list \li \l{qbs::}{buildVariant} that specifies the name of the build variant for the current build. - \li \l{qbs::}{hostOS} that is set by \QBS internally and specifies the - operating system \QBS is running on. \li \l{qbs::}{targetOS} that specifies the operating system you want to build the project for. \endlist @@ -1667,7 +1662,7 @@ /*! \previouspage multiplexing.html \page custom-modules.html - \nextpage module-providers.html + \nextpage special-property-values.html \title Custom Modules and Items @@ -1739,8 +1734,165 @@ /*! \previouspage custom-modules.html + \page special-property-values.html + \nextpage module-providers.html + + \title Special Property Values + + Depending on the context, \QBS provides the following special values for use in property + bindings and JavaScript code: + + \list + \li \l base + \li \l exportingProduct + \li \l filePath + \li \l importingProduct + \li \l original + \li \l outer + \li \l path + \li \l product + \li \l project + \endlist + + \section2 \c base + This value is useful when making use of inheritance. It stands for the value of the respective + property in the item one level up in the inheritance chain. For instance: + \code + Product { // defined in MyProduct.qbs + Depends { name: "mymodule" } + mymodule.someProperty: ["value1"] + } + ------ some other file ------ + MyProduct { + mymodule.someProperty: base.concat(["value2"]) // => ["value1", "value2"] + } + \endcode + + \section2 \c exportingProduct + Within an \l Export item, you can use the \c exportingProduct variable to refer to + the product which defines the Export item: + + \code + Product { + Export { + Depends { name: "cpp" } + cpp.includePaths: exportingProduct.sourceDirectory + } + } + \endcode + + \section2 \c filePath + + This value holds the full file path to the \c .qbs file it appears in. This property is + rarely used, but might be useful when debugging: + \code + Product { + property bool dummy: { + console.info("I'm located at " + filePath); + } + } + \endcode + + \section2 \c importingProduct + Within an \l Export item, you can use the \c importingProduct variable to refer to + the product that pulls in the resulting module: + + \code + Product { + Export { + Depends { name: "cpp" } + cpp.includePaths: importingProduct.buildDirectory + } + } + \endcode + Usually, you should use the \l product variable instead for consistency with \l Module items. + + \section2 \c original + On the right-hand side of a module property binding, this refers to the value of the property + in the module itself (possibly overridden from a profile). Use it to set a module property + conditionally: + \code + Module { // This is mymodule + property string aProperty: "z" + } + ---------- + Product { + Depends { name: "mymodule" } + Depends { name: "myothermodule" } + // "y" if myothermodule.anotherProperty is "x", "z" otherwise: + mymodule.aProperty: myothermodule.anotherProperty === "x" ? "y" : original + } + \endcode + + \section2 \c outer + This value is used in nested items, where it refers to the value of the respective property + in the surrounding item. It is only valid in \l{Group} and \l{Properties} items: + \code + Product { + Depends { name: "mymodule" } + mymodule.someProperty: ["value1"] + Group { + name: "special files" + files: ["somefile1", "somefile2"] + mymodule.someProperty: outer.concat(["value"]) // => ["value1", "value2"] + } + } + \endcode + + \section2 \c path + + This value holds the path to the folder where the \c .qbs file is located. Use it to e.g. add + the product's directory to file paths: + \code + Product { + Depends { name: "cpp" } + cpp.includePaths: path + } + \endcode + + \section2 \c product + + This value holds the properties of the product that contains the current item or pulls in the + current module: + \code + Module { + Rule { + Artifact { + fileTags: product.type + filePath: { + var result = input.fileName; + // module properties are available as well + if (product.qbs.buildVariant === "debug") + result = result + "_debug"; + result = result + ".out"; + return result; + } + } + } + } + \endcode + Within the \l Export item, same as \l importingProduct. + + \section2 \c project + This value holds the properties of the project that references the current item or pulls in the + current module: + \code + Project { + property bool enableProduct: true + Product { + name: "theProduct" + condition: project.enableProduct + } + } + \endcode + If the nearest project in the project tree does not have the desired property, \QBS looks it + up in the parent project, potentially all the way up to the top-level project. +*/ + +/*! + \previouspage special-property-values.html \page module-providers.html - \nextpage howtos.html + \nextpage tutorial.html \title Module Providers @@ -1775,12 +1927,6 @@ a second attempt will be made to locate the dependency using the new paths. The search for a matching module provider ends as soon as one was found, regardless of whether it created any modules or not. - \li If no matching module provider was found in any of the search paths, \QBS will fall back - to a generic module provider, which creates a module that attempts to locate the - dependency via \c pkg-config. - This fallback mechanism can be disabled in the respective - \l{Depends::enableFallback}{Depends} item or globally via the - \l{no-fallback-module-provider}{--no-fallback-module-provider} option. \endlist \section1 Selecting Module Providers |