From a1f4ffa99d3778c5ca70dfc1bfb453a69d769173 Mon Sep 17 00:00:00 2001 From: Ivan Komissarov Date: Thu, 4 May 2023 08:25:35 +0300 Subject: doc: move Special Property Values to a separate page Also, document values that were not documented such as path, filePath, product, project. Change-Id: Ibad64e2998697b4c8c625c3088b835c8be428f54 Reviewed-by: Christian Kandeler --- doc/qbs.qdoc | 161 ++++++++++++++++++++++++++- doc/reference/items/language/module.qdoc | 57 +--------- doc/reference/items/language/properties.qdoc | 2 +- 3 files changed, 165 insertions(+), 55 deletions(-) diff --git a/doc/qbs.qdoc b/doc/qbs.qdoc index 29f4266de..c77dae824 100644 --- a/doc/qbs.qdoc +++ b/doc/qbs.qdoc @@ -67,6 +67,7 @@ \li \l{Generators} \li \l{Multiplexing} \li \l{Custom Modules and Items} + \li \l{Special Property Values} \li \l{Module Providers} \endlist \li \l{How-tos} @@ -1061,6 +1062,7 @@ \li \l{Generators} \li \l{Multiplexing} \li \l{Custom Modules and Items} + \li \l{Special Property Values} \li \l{Module Providers} \endlist @@ -1649,7 +1651,7 @@ /*! \previouspage multiplexing.html \page custom-modules.html - \nextpage module-providers.html + \nextpage special-property-values.html \title Custom Modules and Items @@ -1721,6 +1723,163 @@ /*! \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 diff --git a/doc/reference/items/language/module.qdoc b/doc/reference/items/language/module.qdoc index 172939537..48ad583c8 100644 --- a/doc/reference/items/language/module.qdoc +++ b/doc/reference/items/language/module.qdoc @@ -173,60 +173,11 @@ } \endqml - \section1 Special Property Values - - For every property defined in a module, \QBS provides the following special - built-in values: - - \list - \li \l base - \li \l original - \li \l outer - \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 original - This is the value of the property in the module itself (possibly overridden from a profile or - the command line). Use it to set a module property conditionally: - \code - Module { // This is mymodule - property string aProperty: "z" - } - ---------- - Product { - Depends { name: "mymodule" } - Depends { name: "myothermodule" } - mymodule.aProperty: myothermodule.anotherProperty === "x" ? "y" : original // => "y" if myothermodule.anotherProperty is "x", "z" otherwise - \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 Special Property Values + For every property defined in a module, \QBS provides the special + \l{Special Property Values#original}{original} value containing the value of the property in + the module itself (possibly overridden from a profile). \section1 Dependency Parameters diff --git a/doc/reference/items/language/properties.qdoc b/doc/reference/items/language/properties.qdoc index 49da1dee1..3a71a035b 100644 --- a/doc/reference/items/language/properties.qdoc +++ b/doc/reference/items/language/properties.qdoc @@ -89,7 +89,7 @@ } \endcode - In Properties items, one can access the \l{Module#outer}{outer value} of a + In Properties items, one can access the \l{Special Property Values#outer}{outer} value of a property. \code Product { -- cgit v1.2.1