diff options
Diffstat (limited to 'doc/reference')
18 files changed, 533 insertions, 166 deletions
diff --git a/doc/reference/cli/builtin/cli-build.qdoc b/doc/reference/cli/builtin/cli-build.qdoc index 8e4b8ed44..cffb19d49 100644 --- a/doc/reference/cli/builtin/cli-build.qdoc +++ b/doc/reference/cli/builtin/cli-build.qdoc @@ -68,6 +68,7 @@ \target build-force-probe-execution \include cli-options.qdocinc force-probe-execution \include cli-options.qdocinc jobs + \include cli-options.qdocinc job-limits \include cli-options.qdocinc keep-going \include cli-options.qdocinc less-verbose \include cli-options.qdocinc log-level diff --git a/doc/reference/cli/cli-options.qdocinc b/doc/reference/cli/cli-options.qdocinc index 189a3526a..9f3c47b39 100644 --- a/doc/reference/cli/cli-options.qdocinc +++ b/doc/reference/cli/cli-options.qdocinc @@ -249,6 +249,22 @@ //! [jobs] +//! [job-limits] + + \section2 \c {--job-limits <pool1>:<limit1>[,<pool2>:<limit2>...]} + + Sets pool-specific job limits. See \l{job-pool-howto}{here} for more information on + job pools. + + \section2 \c {--enforce-project-job-limits} + + Normally, job limits defined in project files via the \l JobLimit item get overridden + by those set on the command line. If this option is passed, they get maximum priority + instead. Use it if there are product-specific limits that make more sense for + that part of the code base than the generic ones you'd like to apply globally. + +//! [job-limits] + //! [keep-going] \section2 \c --keep-going|-k diff --git a/doc/reference/commands.qdoc b/doc/reference/commands.qdoc index 8f0392c32..eb93e8f7a 100644 --- a/doc/reference/commands.qdoc +++ b/doc/reference/commands.qdoc @@ -103,6 +103,13 @@ \endlist All other values are mapped to the default color. \row + \li \c jobPool + \li string + \li empty + \li Determines which job pool the command will use. An empty + string, which is the default, stands for the global job pool. + See \l{JobLimit}{here} and \l{job-pool-howto}{here} for more information on job pools. + \row \li \c silent \li bool \li false diff --git a/doc/reference/items/convenience/androidapk.qdoc b/doc/reference/items/convenience/androidapk.qdoc deleted file mode 100644 index 89a4112b6..000000000 --- a/doc/reference/items/convenience/androidapk.qdoc +++ /dev/null @@ -1,118 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of Qbs. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ -/*! - \contentspage list-of-convenience-items.html - \nextpage AppleApplicationDiskImage - \qmltype AndroidApk - \inherits Product - \inqmlmodule QbsConvenienceItems - \ingroup list-of-items - \keyword QML.AndroidApk - - \brief Android application package. - - An AndroidApk item is a \l{Product}{product} of the \l{Product::}{type} - \c android.apk that has a \l{Depends}{dependency} on the \l{Android.sdk} - module. The final build result is an Android application package (APK) file. - - Here is what the project file could look like for the BasicMediaDecoder - example that comes with the Android SDK: - - \code - import qbs - - AndroidApk { - name: "Basic Media Decoder" - packageName: "com.example.android.basicmediadecoder" - - property string sourcesPrefix: "Application/src/main/" - - resourcesDir: sourcesPrefix + "/res" - sourcesDir: sourcesPrefix + "/java" - manifestFile: sourcesPrefix + "/AndroidManifest.xml" - } - \endcode -*/ - -/*! - \qmlproperty path AndroidApk::assetsDir - - The base directory for Android assets. - - \note Android requires that the file name of this directory is always - \c "assets". - - \defaultvalue \c "assets" -*/ - -/*! - \qmlproperty bool AndroidApk::automaticSources - - If \c true, Java sources as well as Android resources, assets, and the - manifest file will be automatically included in the product via wildcards. - Set this property to \c false if you want to specify these files manually. - - \defaultvalue \c true -*/ - -/*! - \qmlproperty path AndroidApk::manifestFile - - The file path to the Android manifest file. - - \note Android requires that the file name is always "AndroidManifest.xml". - - \defaultvalue \c "AndroidManifest.xml" -*/ - -/*! - \qmlproperty string AndroidApk::packageName - - The package name as given in the manifest file. - - \defaultvalue \c name -*/ - -/*! - \qmlproperty path AndroidApk::resourcesDir - - The base directory for Android resources. - - \note Android requires that the file name of this directory is always - \c "res". - - \defaultvalue \c "res" -*/ - -/*! - \qmlproperty path AndroidApk::sourcesDir - - The base directory for Java sources. This property is only relevant if - \l automaticSources is enabled. - - \defaultvalue \c "src" -*/ diff --git a/doc/reference/items/convenience/appleapplicationdiskimage.qdoc b/doc/reference/items/convenience/appleapplicationdiskimage.qdoc index d8011d66a..69a10c797 100644 --- a/doc/reference/items/convenience/appleapplicationdiskimage.qdoc +++ b/doc/reference/items/convenience/appleapplicationdiskimage.qdoc @@ -26,7 +26,6 @@ ****************************************************************************/ /*! \contentspage list-of-convenience-items.html - \previouspage AndroidApk \nextpage AppleDiskImage \qmltype AppleApplicationDiskImage \since Qbs 1.9 @@ -51,8 +50,6 @@ Here is what the project file could look like for a simple DMG installer: \code - import qbs - AppleApplicationDiskImage { Depends { name: "myapp" } name: "My App" diff --git a/doc/reference/items/convenience/application.qdoc b/doc/reference/items/convenience/application.qdoc index de2bbae48..30b3f9c73 100644 --- a/doc/reference/items/convenience/application.qdoc +++ b/doc/reference/items/convenience/application.qdoc @@ -39,9 +39,31 @@ An Application item is a \l{Product} of the \l{Product::}{type} \c "application". - It exists for the convenience of project file authors. + The target artifact of this type of product is usually an executable binary. + However, on Android, unless you set \l{Product::}{consoleApplication} to \c true, + the application target will be an APK package, and a dependency to the + \l{Android.sdk} module is automatically added to the product. +*/ + +/*! + \qmlproperty bool Application::install + + If \c{true}, the executable that is produced when building the application will be installed + to \l installDir. + + \defaultvalue \c false + \since Qbs 1.13 +*/ + +/*! + \qmlproperty string Application::installDir + + Where to install the executable that is produced when building the application, if \l install + is enabled. + + The value is appended to \l{qbs::installPrefix}{qbs.installPrefix} + when constructing the actual installation directory. - \note On Android, an Application item instead builds a shared library for - products whose \l{Product::}{consoleApplication} property is set to - \c false. + \defaultvalue \c Applications if the app is a \l{bundle::isBundle}{bundle}, \c bin otherwise. + \since Qbs 1.13 */ diff --git a/doc/reference/items/convenience/autotestrunner.qdoc b/doc/reference/items/convenience/autotestrunner.qdoc index f4861835b..defb2814e 100644 --- a/doc/reference/items/convenience/autotestrunner.qdoc +++ b/doc/reference/items/convenience/autotestrunner.qdoc @@ -73,6 +73,8 @@ \qmlproperty stringList AutotestRunner::arguments The list of arguments to invoke the autotest with. + A test can override this by setting the \l{autotest::arguments}{arguments} property + of the \l autotest module. \defaultvalue \c [] */ @@ -114,6 +116,8 @@ 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. + A test can override this by setting the \l{autotest::workingDir}{workingDir} property + of the \l autotest module. \nodefaultvalue \since Qbs 1.12 diff --git a/doc/reference/items/convenience/dynamiclibrary.qdoc b/doc/reference/items/convenience/dynamiclibrary.qdoc index 27aa978d1..488aef3eb 100644 --- a/doc/reference/items/convenience/dynamiclibrary.qdoc +++ b/doc/reference/items/convenience/dynamiclibrary.qdoc @@ -38,7 +38,7 @@ \brief Dynamic library. A DynamicLibrary item is a \l{Product} of the \l{Product::}{type} - \c "dynamiclibrary". It exists for the convenience of project file authors. + \c "dynamiclibrary". For Android targets, the following applies: \list @@ -48,3 +48,50 @@ \endlist */ +/*! + \qmlproperty bool DynamicLibrary::install + + If \c{true}, the library will be installed to \l installDir. + + \defaultvalue \c false + \since Qbs 1.13 +*/ + +/*! + \qmlproperty string DynamicLibrary::installDir + + Where to install the library, if \l install is enabled. On Unix, the symbolic links + are also installed to this location. + + The value is appended to \l{qbs::installPrefix}{qbs.installPrefix} + when constructing the actual installation directory. + + \defaultvalue \c Library/Frameworks if the library is a \l{bundle::isBundle}{bundle}, + otherwise \c bin for Windows and \c lib for Unix-like targets. + \since Qbs 1.13 +*/ + +/*! + \qmlproperty bool DynamicLibrary::installImportLib + + If \c{true}, the import library will be installed to \l importLibInstallDir. + This property is only relevant for Windows targets. + Enable it if you want to create a development package. + + \defaultvalue \c false + \since Qbs 1.13 +*/ + +/*! + \qmlproperty string DynamicLibrary::importLibInstallDir + + Where to install the import library, if \l installImportLib is enabled. + + The value is appended to \l{qbs::installPrefix}{qbs.installPrefix} + when constructing the actual installation directory. + + This property is only relevant for Windows targets. + + \defaultvalue \c lib + \since Qbs 1.13 +*/ diff --git a/doc/reference/items/convenience/staticlibrary.qdoc b/doc/reference/items/convenience/staticlibrary.qdoc index a7a94cc43..cd459cf6e 100644 --- a/doc/reference/items/convenience/staticlibrary.qdoc +++ b/doc/reference/items/convenience/staticlibrary.qdoc @@ -37,11 +37,27 @@ \brief Static library. A StaticLibrary item is a \l{Product}{product} of the \l{Product::}{type} - \c "staticlibrary" that is normally entirely equivalent to the following: + \c "staticlibrary". +*/ + +/*! + \qmlproperty bool StaticLibrary::install + + If \c{true}, the library will be installed to \l installDir. + + \defaultvalue \c false + \since Qbs 1.13 +*/ + +/*! + \qmlproperty string StaticLibrary::installDir + + Where to install the library, if \l install is enabled. + + The value is appended to \l{qbs::installPrefix}{qbs.installPrefix} + when constructing the actual installation directory. - \code - Product { - type: "staticlibrary" - } - \endcode + \defaultvalue \c Library/Frameworks if the library is a \l{bundle::isBundle}{bundle}, + \c lib otherwise. + \since Qbs 1.13 */ diff --git a/doc/reference/items/language/group.qbs b/doc/reference/items/language/group.qbs index 4b478bfa5..c6bbae875 100644 --- a/doc/reference/items/language/group.qbs +++ b/doc/reference/items/language/group.qbs @@ -28,8 +28,6 @@ ** ****************************************************************************/ -import qbs 1.0 - Project { Product { //! [0] diff --git a/doc/reference/items/language/group.qdoc b/doc/reference/items/language/group.qdoc index dae647060..caeffcfaa 100644 --- a/doc/reference/items/language/group.qdoc +++ b/doc/reference/items/language/group.qdoc @@ -28,7 +28,7 @@ /*! \contentspage list-of-language-items.html \previouspage FileTagger - \nextpage Module + \nextpage JobLimit \qmltype Group \inqmlmodule QbsLanguageItems \ingroup list-of-items diff --git a/doc/reference/items/language/joblimit.qdoc b/doc/reference/items/language/joblimit.qdoc new file mode 100644 index 000000000..66697ba3e --- /dev/null +++ b/doc/reference/items/language/joblimit.qdoc @@ -0,0 +1,107 @@ +/**************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qbs. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! + \contentspage list-of-language-items.html + \previouspage Group + \nextpage Module + \qmltype JobLimit + \inqmlmodule QbsLanguageItems + \ingroup list-of-items + \keyword QML.JobLimit + + \brief Restricts concurrent execution of jobs in a given pool. + + In addition to the global limit on concurrently running commands, a project might + want to restrict concurrent execution of certain types of commands even further, + for instance because they are not well-suited to share certain types of resources. + + In the following example, we define a rule that runs a tool of which at most one + instance can be running for the same project at any given time: + \code + Rule { + // ... + prepare: { + var cmd = new Command("my-exclusive-tool", [project.buildDirectory]); + cmd.description = "running the exclusive tool"; + cmd.jobPool = "exclusive_tool"; + return cmd; + } + } + JobLimit { + jobPool: "exclusive_tool" + jobCount: 1 + } + \endcode + + \c JobLimit items can appear inside \l Product, \l Project and \l Module items. + In the case of collisions, that is, items matching the same job pool but setting + different values, the ones defined inside products have the highest precedence, + and the ones inside modules have the lowest. Items defined in sub-projects have + higher precedence than those defined in parent projects. For items with the same + precedence level, the most restrictive one is chosen, that is, the one with the + lowest job number greater than zero. + + \see {How do I limit the number of concurrent jobs for the linker only?} +*/ + +/*! + \qmlproperty bool JobLimit::condition + + Determines whether the job limit is active. + + If this property is set to \c false, the job limit is ignored. + + \defaultvalue \c true +*/ + +/*! + \qmlproperty string JobLimit::jobCount + + The maximum number of commands in the given \l{jobPool}{job pool} that can run + concurrently. + + A value of zero means "unlimited", negative values are not allowed. + + \note The global job limit always applies: For instance, if you set this + property to 100 for some job pool, and "-j 8" was given on the + command line, then no more than eight instances of commands from + the respective job pool will run at any time. + + This property must always be set. + + \nodefaultvalue +*/ + +/*! + \qmlproperty string JobLimit::jobPool + + The job pool to which apply the limit. + + This property must always be set to a non-empty value. + + \nodefaultvalue +*/ diff --git a/doc/reference/items/language/module.qdoc b/doc/reference/items/language/module.qdoc index fb2238e0c..e5472983f 100644 --- a/doc/reference/items/language/module.qdoc +++ b/doc/reference/items/language/module.qdoc @@ -26,7 +26,7 @@ ****************************************************************************/ /*! \contentspage list-of-language-items.html - \previouspage Group + \previouspage JobLimit \nextpage Parameter \qmltype Module \inqmlmodule QbsLanguageItems @@ -41,7 +41,6 @@ characters from them. The module's name is \c{txt_processor}. \code - import qbs import qbs.FileInfo import qbs.TextFile diff --git a/doc/reference/modules/android-ndk-module.qdoc b/doc/reference/modules/android-ndk-module.qdoc index 529f2fb4d..8113a7c68 100644 --- a/doc/reference/modules/android-ndk-module.qdoc +++ b/doc/reference/modules/android-ndk-module.qdoc @@ -34,29 +34,21 @@ \brief Provides support for building native Android libraries. The \c Android.ndk module contains the properties and rules to create native libraries - for use in \l{AndroidApk}{Android application packages}. + for use in Android applications. Normally, you will not use this module directly, but instead work - with the \l{DynamicLibrary} and \l{StaticLibrary} items that \QBS provides. + with the \l{DynamicLibrary}, \l{StaticLibrary} and \l Application items + that \QBS provides. Here is what the project file for the \c hello-jni example that comes with the NDK could look like: \code - import qbs - - Project { - DynamicLibrary { - name: "hello-jni" - qbs.architectures: ["mips", "x86"] - files: ["jni/hello-jni.c"] - } - - AndroidApk { - name: "HelloJni" - packageName: "com.example.hellojni" - Depends { productTypes: ["android.nativelibrary"] } - } + CppApplication { + name: "HelloJni" + Android.sdk.packageName: "com.example.hellojni" + qbs.architectures: ["mips", "x86"] + files: "app/src/main/jni/hello-jni.c" } \endcode diff --git a/doc/reference/modules/android-sdk-module.qdoc b/doc/reference/modules/android-sdk-module.qdoc index bad547311..40d80b021 100644 --- a/doc/reference/modules/android-sdk-module.qdoc +++ b/doc/reference/modules/android-sdk-module.qdoc @@ -35,9 +35,7 @@ The Android.sdk module contains the properties and rules to create Android application packages from Java sources, resources, and so on. - - Normally, you will not use this module directly, but instead work - with the \l{AndroidApk} item that \QBS provides. + It is usually pulled in indirectly by declaring an \l Application product. \section2 Relevant File Tags \target filetags-android-sdk @@ -59,14 +57,8 @@ \li - \li 1.4.0 \li Attached to Android assets, which are typically located in an - \c{assets/} subdirectory. Using the \l{AndroidApk} item takes care - of tagging these files for you. - \row - \li \c{"android.apk"} - \li n/a - \li 1.4.0 - \li Attached to the output artifact of the rule that creates an APK - package. It is the default type of the \l{AndroidApk} item. + \c{assets/} subdirectory. These files are tagged automatically + if the \l automaticSources property is enabled. \row \li \c{"android.manifest"} \li \c{AndroidManifest.xml} @@ -78,8 +70,8 @@ \li - \li 1.4.0 \li Attached to Android resources, which are typically located in a - \c{res/} subdirectory. Using the \l{AndroidApk} item takes care of - tagging these files for you. + \c{res/} subdirectory. These files are tagged automatically + if the \l automaticSources property is enabled. \endtable */ @@ -125,3 +117,78 @@ \defaultvalue \c{true} */ + +/*! + \qmlproperty string Android.sdk::assetsDir + + The base directory for Android assets in the respective product. + + \note Android requires that the file name of this directory is always + \c "assets". + + \defaultvalue \c "src/main/assets" in the product source directory +*/ + +/*! + \qmlproperty bool Android.sdk::automaticSources + + If \c true, Java sources as well as Android resources, assets, and the + manifest file will be automatically included in the respective product + via wildcards. Set this property to \c false if you want to specify + these files manually. + + \defaultvalue \c true +*/ + +/*! + \qmlproperty string Android.sdk::manifestFile + + The file path to the Android manifest file. + This property is only relevant if \l automaticSources is enabled. + + \note Android requires that the file name is always "AndroidManifest.xml". + + \defaultvalue \c "src/main/AndroidManifest.xml" in the product source directory +*/ + +/*! + \qmlproperty string Android.sdk::packageName + + The package name of the respective product. Must match the one given in the manifest file. + + \defaultvalue \c name +*/ + +/*! + \qmlproperty string Android.sdk::resourcesDir + + The base directory for Android resources in the respective product. + + \note Android requires that the file name of this directory is always + \c "res". + + \defaultvalue \c "src/main/res" in the product source directory +*/ + +/*! + \qmlproperty path Android.sdk::sourcesDir + + The base directory for Java sources. This property is only relevant if + \l automaticSources is enabled. + + \defaultvalue \c "src/main/java" in the product source directory +*/ + +/*! + \qmlproperty string Android.sdk::apkBaseName + + The base name of the APK file to to be built, that is, the file name + without the ".apk" extension. + + \defaultvalue \l packageName +*/ + +/*! + \qmlproperty stringList Android.sdk::aidlSearchPaths + Search paths for import statements to pass to the \c aidl tool via the \c{-I} option. +*/ diff --git a/doc/reference/modules/autotest-module.qdoc b/doc/reference/modules/autotest-module.qdoc new file mode 100644 index 000000000..ddd9e0078 --- /dev/null +++ b/doc/reference/modules/autotest-module.qdoc @@ -0,0 +1,69 @@ +/**************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qbs. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \contentspage index.html + \qmltype autotest + \inqmlmodule QbsModules + \since Qbs 1.13 + + \brief Allows to fine-tune autotest execution. + + The \c autotest module provides properties that allow autotest applications to specify + how exactly they should be run. +*/ + +/*! + \qmlproperty bool autotest::allowFailure + + Autotests for which this property is \c true can return a non-zero exit code without + causing the entire \l AutotestRunner to fail. Use this for tests that are known + to be unreliable. + + \defaultvalue \c false +*/ + +/*! + \qmlproperty stringList autotest::arguments + + The list of arguments to invoke the autotest with. If not specified, then + the \l{AutotestRunner::arguments}{arguments} property of the + \l AutotestRunner that invokes the autotest is used. + + \nodefaultvalue +*/ + +/*! + \qmlproperty string autotest::workingDir + + The working directory for running the autotest. If not specified, then + the \l{AutotestRunner::workingDir}{workingDir} property of the + \l AutotestRunner that invokes the autotest is used. + + \nodefaultvalue +*/ + diff --git a/doc/reference/modules/cpp-module.qdoc b/doc/reference/modules/cpp-module.qdoc index 0818af28d..386ac7553 100644 --- a/doc/reference/modules/cpp-module.qdoc +++ b/doc/reference/modules/cpp-module.qdoc @@ -217,6 +217,31 @@ This file tag only has an effect with GCC-like toolchains. The linker needs to be \c{ld}-compatible. \endtable + + \section2 Relevant Job Pools + \target cpp-job-pools + + \table + \header + \li Pool + \li Since + \li Description + \row + \li \c{"assembler"} + \li 1.13 + \li The job pool used by rules that run the toolchain's assembler. This is only + relevant for direct invocations of the assembler binary, not for running it + indirectly via the compiler. + \row + \li \c{"compiler"} + \li 1.13 + \li The job pool used by rules that run a compiler. All language variants use + the same pool. + \row + \li \c{"linker"} + \li 1.13 + \li The job pool used by rules that run a linker. + \endtable */ /*! diff --git a/doc/reference/modules/texttemplate-module.qdoc b/doc/reference/modules/texttemplate-module.qdoc new file mode 100644 index 000000000..7d0c47a6d --- /dev/null +++ b/doc/reference/modules/texttemplate-module.qdoc @@ -0,0 +1,118 @@ +/**************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of Qbs. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \contentspage index.html + \qmltype texttemplate + \inqmlmodule QbsModules + \since Qbs 1.13 + + \brief Provides support for text template files + + The \c texttemplate module provides support for text template files. + + \section2 Example + + Consider the following text file \e{greeting.txt.in}. + + \code + ${greeting} ${name}! + \endcode + + This can be used in a project like this: + + \code + Product { + type: ["text"] + files: ["greeting.txt.in"] + Depends { name: "texttemplate" } + texttemplate.dict: ({ + greeting: "Hello", + name: "World" + }) + } + \endcode + + Which will create the file \e{greeting.txt}. + + \code + Hello World! + \endcode + + + \section2 Placeholder Syntax + + A placeholder \c{${foo}} is replaced by its corresponding value in + \e{texttemplate.dict}. + Placeholder names consist of alphanumeric characters only. + + The placeholder \c{${$}} is always replaced with \c{$}. + If you need a literal \c{${foo}} in your template, use \c{${$}{foo}}. + + Placeholders that are not defined in the dictionary will produce an error. + + + \section2 Relevant File Tags + \target filetags-texttemplate + + \table + \header + \li Tag + \li Auto-tagged File Names + \li Since + \li Description + \row + \li \c{"texttemplate.input"} + \li \c{*.in} + \li 1.13.0 + \li Source files with this tag serve as inputs for the text template rule. + \endtable +*/ + +/*! + \qmlproperty var texttemplate::dict + + The dictionary containing values for all keys used in the template file. + + \defaultvalue \c{{}} +*/ + +/*! + \qmlproperty string texttemplate::outputFileName + + The output file name that is assigned to produced artifacts. + + \defaultvalue Complete base name of the input file +*/ + +/*! + \qmlproperty string texttemplate::outputTag + + The output tag that is assigned to produced artifacts. + + \defaultvalue \c{"text"} +*/ |