aboutsummaryrefslogtreecommitdiffstats
path: root/doc/reference/items/language
diff options
context:
space:
mode:
Diffstat (limited to 'doc/reference/items/language')
-rw-r--r--doc/reference/items/language/artifact.qdoc84
-rw-r--r--doc/reference/items/language/depends.qdoc136
-rw-r--r--doc/reference/items/language/export.qdoc69
-rw-r--r--doc/reference/items/language/filetagger.qdoc86
-rw-r--r--doc/reference/items/language/group.qbs46
-rw-r--r--doc/reference/items/language/group.qdoc158
-rw-r--r--doc/reference/items/language/module.qdoc201
-rw-r--r--doc/reference/items/language/probe.qdoc70
-rw-r--r--doc/reference/items/language/product.qdoc189
-rw-r--r--doc/reference/items/language/project.qdoc111
-rw-r--r--doc/reference/items/language/properties.qdoc115
-rw-r--r--doc/reference/items/language/propertyoptions.qdoc67
-rw-r--r--doc/reference/items/language/rule.qdoc294
-rw-r--r--doc/reference/items/language/scanner.qdoc95
-rw-r--r--doc/reference/items/language/subproject.qdoc75
15 files changed, 1796 insertions, 0 deletions
diff --git a/doc/reference/items/language/artifact.qdoc b/doc/reference/items/language/artifact.qdoc
new file mode 100644
index 000000000..9bda03e59
--- /dev/null
+++ b/doc/reference/items/language/artifact.qdoc
@@ -0,0 +1,84 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 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
+ \page artifact-item.html
+ \nextpage depends-item.html
+ \ingroup list-of-language-items
+ \ingroup list-of-items
+
+ \title Artifact Item
+ \brief Describes a file produced by a \c Rule.
+
+ An \c Artifact represents a single file produced by a \l{Rule Item}{Rule}.
+
+ For example, if a rule produces three files, it needs to contain three Artifact items.
+
+ In addition to the properties listed in the section below, you can also set module properties
+ within an \c Artifact item:
+ \code
+ Artifact {
+ filePath: "somefile.cpp"
+ fileTags: ["cpp"]
+ cpp.cxxLanguageVersion: "c++11"
+ // ...
+ }
+ \endcode
+
+ \section1 Artifact Properties
+
+ \note The code on the right-hand side of these properties has access to the set of input
+ artifacts, that is, it can refer to the \c inputs map and, if the rule is not a multiplex rule,
+ the \c input variable.
+
+ \table
+ \header
+ \li Property
+ \li Type
+ \li Default
+ \li Description
+ \row
+ \li alwaysUpdated
+ \li bool
+ \li true
+ \li Setting this to \c false means the file is not necessarily always written to by any
+ command run by the rule. The timestamps of such artifacts are therefore not checked to
+ find out whether they are up to date. Consequently, if all artifacts of a rule have this
+ property set to \c false, the commands of the rule are always executed.
+ \row
+ \li filePath
+ \li string
+ \li undefined
+ \li The file path of the target artifact.
+ \row
+ \li fileTags
+ \li list
+ \li empty list
+ \li The tags to attach to the target file. These can then be matched by a rule.
+ \endtable
+
+*/
diff --git a/doc/reference/items/language/depends.qdoc b/doc/reference/items/language/depends.qdoc
new file mode 100644
index 000000000..5d944cba6
--- /dev/null
+++ b/doc/reference/items/language/depends.qdoc
@@ -0,0 +1,136 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 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 artifact-item.html
+ \page depends-item.html
+ \nextpage export-item.html
+ \ingroup list-of-language-items
+ \ingroup list-of-items
+
+ \title Depends Item
+ \brief Represents dependencies between products and modules.
+
+ A \c Depends item can appear inside a \l{Product Item} or \l{Module Item}.
+
+ For example, the following product will load the \c cpp module. In addition, it will try
+ to load modules that may or may not exist, and in the latter case use a fallback.
+ \code
+ Product {
+ Depends { name: "cpp" }
+ Depends {
+ name: "awesome_module"
+ versionAtLeast: "2.0"
+ required: false
+ }
+ Depends {
+ name: "adequate_module"
+ condition: !awesome_module.present
+ required: false
+ }
+ Depends {
+ name: "crappy_module"
+ condition: !awesome_module.present && !adequate_module.present
+ }
+
+ // ...
+ }
+ \endcode
+
+
+ \section1 Depends Properties
+
+ \table
+ \header
+ \li Property
+ \li Type
+ \li Default
+ \li Description
+ \row
+ \li condition
+ \li bool
+ \li true
+ \li Determines whether the dependency will actually be applied.
+ \row
+ \li versionAtLeast
+ \li string
+ \li undefined
+ \li The minimum value that the dependency's \c version property needs to have. If the
+ actual version is lower than that, loading the dependency will fail.
+ The value consists of integers separated by dots.
+ \row
+ \li versionBelow
+ \li string
+ \li undefined
+ \li A value that the dependency's \c version property must be lower than. If the
+ actual version is equal to or higher than that, loading the dependency will fail.
+ The value consists of integers separated by dots.
+ \row
+ \li productTypes
+ \li stringList
+ \li undefined
+ \li A list of product types. Any enabled product in the project that has a matching type
+ will become a dependency of the product containing the \c Depends item.
+ This property is mutually exclusive with the \c name and \c submodules properties.
+ The \c required and \c profiles properties are ignored if \c productTypes is set.
+ \row
+ \li required
+ \li bool
+ \li \c true
+ \li Setting this property to \c false creates a \e{soft dependency}, meaning that it is not
+ considered an error if the given module cannot be found. In such a case, an instance of
+ the respective module will be created, but only the \c present property will be
+ available for querying, and it will be set to \c false.
+ \row
+ \li name
+ \li string
+ \li undefined
+ \li The name of the dependent product or module.
+ \row
+ \li profiles
+ \li stringList
+ \li \c{[product.profile]}
+ \li If the dependency is on a product and that product is going to be built for more than
+ one profile, then you can specify here which instance of the product the dependency is on.
+ See the \c profiles property of the \c Product item for more information.
+ An empty list means a dependency on all instances of the product with the given name,
+ regardless of their profile.
+ \row
+ \li limitToSubProject
+ \li bool
+ \li \c false
+ \li If \c productTypes is set and this property is \c true, then only products that
+ are in the same sub-project as the product containing the \c Depends item are
+ considered.
+ \row
+ \li submodules
+ \li stringList
+ \li undefined
+ \li The submodules of \c module to depend on, if applicable.
+ \endtable
+
+*/
diff --git a/doc/reference/items/language/export.qdoc b/doc/reference/items/language/export.qdoc
new file mode 100644
index 000000000..16d073df4
--- /dev/null
+++ b/doc/reference/items/language/export.qdoc
@@ -0,0 +1,69 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 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 depends-item.html
+ \page export-item.html
+ \nextpage filetagger-item.html
+ \ingroup list-of-language-items
+ \ingroup list-of-items
+
+ \title Export Item
+ \brief Exports dependencies and properties to other products.
+
+ An \c Export item can appear inside a \l{Product Item}. It defines a Module with the product's
+ name that can be depended on by other products.
+ The properties attached to the Export item will take effect in all products that depend on the
+ product inside which the Export item is defined.
+ As an example, consider these two products:
+ \code
+ Product {
+ name: "A"
+ Export {
+ Depends { name: "cpp" }
+ cpp.includePaths: product.sourceDirectory
+ cpp.defines: ["USING_" + product.name.toUpperCase()]
+ }
+ }
+
+ Product {
+ name: "B"
+ Depends { name: "A" }
+ }
+ \endcode
+
+ The sources in product B will be able to use headers from product A without specifiying
+ the full path to them, because the include path has been made known to the compiler via
+ A's Export item. Additionally, product B will be compiled with the define \c{USING_A}.
+
+ \note This relationship is transitive, so a product C depending on product B will also
+ get the include paths and preprocessor macros via A's Export item.
+
+ In contrast to Module items, \c{product} within Export items refers to the product which defines
+ the Export item. Use the \c{importingProduct} variable to refer to the product that
+ pulls in the resulting module.
+*/
diff --git a/doc/reference/items/language/filetagger.qdoc b/doc/reference/items/language/filetagger.qdoc
new file mode 100644
index 000000000..578dad21c
--- /dev/null
+++ b/doc/reference/items/language/filetagger.qdoc
@@ -0,0 +1,86 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 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 export-item.html
+ \page filetagger-item.html
+ \nextpage group-item.html
+ \ingroup list-of-language-items
+ \ingroup list-of-items
+
+ \title FileTagger Item
+ \brief Maps file patterns to tags.
+
+ This item maps file patterns to tags. It can be attached to a product or a module.
+ In the latter case, its effect is the same as if it had been attached to all products having
+ a dependency on the respective module. For instance, the cpp module of \QBS has, among others,
+ the following file tagger:
+ \code
+ FileTagger {
+ patterns: "*.cpp"
+ fileTags: ["cpp"]
+ }
+ \endcode
+
+ As a result, the "cpp" tag is automatically attached to all files ending with ".cpp" in
+ products depending on the cpp module. This causes them to be compiled, because a C++
+ compiler rule has "cpp" in its list of matching input tags.
+
+ File taggers are disabled if file tags are set explicitly in a product or group.
+ For example, the "cpp" tag is not attached to the cpp files in the following product:
+
+ \code
+ Product {
+ Depends { name: "cpp" }
+ Group {
+ files: "*.cpp"
+ fileTags: "other"
+ }
+ }
+ \endcode
+
+ \section1 FileTagger Properties
+
+ \table
+ \header
+ \li Property
+ \li Type
+ \li Default
+ \li Description
+ \row
+ \li patterns
+ \li stringList
+ \li none
+ \li The patterns to match against. Supports the usual wildcards '*', '?' and '[]'.
+ Neither the list itself nor any of its elements may be empty.
+ \row
+ \li fileTags
+ \li list
+ \li empty list
+ \li Tags to attach to a product's files. These can then be matched by a rule.
+ \endtable
+*/
diff --git a/doc/reference/items/language/group.qbs b/doc/reference/items/language/group.qbs
new file mode 100644
index 000000000..4b478bfa5
--- /dev/null
+++ b/doc/reference/items/language/group.qbs
@@ -0,0 +1,46 @@
+/****************************************************************************
+**
+** Copyright (C) 2015 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing
+**
+** This file is part of the Qt Build Suite.
+**
+** 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 http://www.qt.io/terms-conditions. For further information
+** use the contact form at http://www.qt.io/contact-us.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 or version 3 as published by the Free
+** Software Foundation and appearing in the file LICENSE.LGPLv21 and
+** LICENSE.LGPLv3 included in the packaging of this file. Please review the
+** following information to ensure the GNU Lesser General Public License
+** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
+** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, The Qt Company gives you certain additional
+** rights. These rights are described in The Qt Company LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+****************************************************************************/
+
+import qbs 1.0
+
+Project {
+ Product {
+//! [0]
+ Group {
+ name: "Word processing documents"
+ files: ["*.doc", "*.rtf"]
+ prefix: "**/"
+ qbs.install: true
+ qbs.installDir: "share"
+ excludeFiles: "do_not_install_this_file.*"
+ }
+//! [0]
+ }
+}
diff --git a/doc/reference/items/language/group.qdoc b/doc/reference/items/language/group.qdoc
new file mode 100644
index 000000000..16eeb3ea2
--- /dev/null
+++ b/doc/reference/items/language/group.qdoc
@@ -0,0 +1,158 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 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 filetagger-item.html
+ \page group-item.html
+ \nextpage module-item.html
+ \ingroup list-of-language-items
+ \ingroup list-of-items
+
+ \title Group Item
+ \brief Groups files in a product.
+
+ This item is attached to a product and used to group files that have something in common.
+ For example:
+
+ \code
+ Application {
+ Group {
+ name: "common files"
+ files: ["myclass.h", "myclass_common_impl.cpp"]
+ }
+ Group {
+ name: "Windows files"
+ condition: targetOS.contains("windows")
+ files: "myclass_win_impl.cpp"
+ }
+ Group {
+ name: "Unix files"
+ condition: targetOS.contains("unix")
+ files: "unixhelper.cpp"
+ Group {
+ name: "Linux files"
+ condition: targetOS.contains("linux")
+ files: "myclass_linux_impl.cpp"
+ }
+ Group {
+ name: "FreeBSD files"
+ condition: targetOS.contains("freebsd")
+ files: "myclass_freebsd_impl.cpp"
+ }
+ }
+ Group {
+ name: "Files to install"
+ qbs.install: true
+ qbs.installDir: "share"
+ files: "runtime_resource.txt"
+ }
+ }
+ \endcode
+ When specifying files, you can use the wildcards "*", "?" and "[]", which have their usual meaning.
+ By default, matching files are only picked up directly from the parent directory, but you can tell \QBS to
+ consider the whole directory tree. It is also possible to exclude certain files from the list.
+ The pattern ** used in a pathname expansion context will match all files and zero or more
+ directories and subdirectories.
+ For example:
+ \snippet reference/items/language/group.qbs 0
+
+ A group can also be used to attach properties to build artifacts such as executables or
+ libraries. In the following example, an application is installed to "<install root>/bin".
+ \code
+ Application {
+ Group {
+ fileTagsFilter: "application"
+ qbs.install: true
+ qbs.installDir: "bin"
+ }
+ }
+ \endcode
+
+ Groups may also appear in modules, which causes the respective sources to be added to the
+ products depending on said module.
+ Groups can be nested. In this case, child groups inherit the module properties and the file
+ tags of their parent group. The condition of a child group gets logically ANDed with the one
+ of its parent group.
+
+ \section1 Group Properties
+
+ \table
+ \header
+ \li Property
+ \li Type
+ \li Default
+ \li Description
+ \row
+ \li name
+ \li string
+ \li "Group x", where x is a unique number among all the groups in the product
+ \li The name of the group. Not used internally; mainly useful for IDEs.
+ \row
+ \li files
+ \li list
+ \li empty list
+ \li The files in the group. Mutually exclusive with fileTagsFilter.
+ \row
+ \li prefix
+ \li string
+ \li empty string
+ \li A string to prepend to all files. Slashes are allowed and have directory semantics.
+ \row
+ \li fileTagsFilter
+ \li list
+ \li empty list
+ \li Artifact file tags to match. Any properties set in this group will be applied
+ to the product's artifacts whose file tags intersect with the ones
+ listed here. Mutually exclusive with files.
+ \row
+ \li condition
+ \li bool
+ \li true
+ \li Determines whether the files in the group are actually considered part of the project.
+ \row
+ \li fileTags
+ \li list
+ \li empty list
+ \li Tags to attach to the group's files. These can then be matched by a rule.
+ Note that file taggers are never applied to a file that has this property set.
+ \row
+ \li overrideTags
+ \li bool
+ \li true
+ \li Determines how tags on files that are listed both at the top level of
+ a product (or the parent group, if there is one) and a group are handled.
+ If this property is true, then the file tags set via the group
+ replace the ones set via the product or parent group.
+ If it is false, the "group tags" are added to the "parent tags".
+ \row
+ \li excludeFiles
+ \li list
+ \li empty list
+ \li For use with wildcards; the files in this list are "subtracted" from the files list.
+ \endtable
+*/
diff --git a/doc/reference/items/language/module.qdoc b/doc/reference/items/language/module.qdoc
new file mode 100644
index 000000000..69d9d8896
--- /dev/null
+++ b/doc/reference/items/language/module.qdoc
@@ -0,0 +1,201 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 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-item.html
+ \page module-item.html
+ \nextpage probe-item.html
+ \ingroup list-of-language-items
+ \ingroup list-of-items
+
+ \title Module Item
+ \brief Represents a collection of properties and items that can be loaded into a product.
+
+ A \c Module item is a collection of properties and language items that are used for building a
+ product if the product has a \l{Depends Item}{dependency} on the module.
+ The following (somewhat artificial) module pre-processes text files by removing certain
+ characters from them:
+
+ \code
+ import qbs
+ import qbs.FileInfo
+ import qbs.TextFile
+
+ Module {
+ property stringList unwantedCharacters: []
+ FileTagger {
+ patterns: ["*.raw"]
+ fileTags: ["raw-txt"]
+ }
+ Rule {
+ inputs: ["raw-txt"]
+ Artifact {
+ filePath: FileInfo.relativePath(input.filePath, product.sourceDirectory) +
+ "/" + input.fileName + ".processed"
+ fileTags: ["processed-txt"]
+ }
+ prepare: {
+ var cmd = new JavaScriptCommand();
+ cmd.description = "Processing " + input.fileName;
+ cmd.sourceCode = function() {
+ var inFile = new TextFile(input.filePath, TextFile.ReadOnly);
+ var content = inFile.readAll();
+ inFile.close();
+ var unwantedChars = product.moduleProperty("txt_processor",
+ "unwantedCharacters");
+ for (var c in unwantedChars)
+ content = content.replace(unwantedChars[c], "");
+ var outFile = new TextFile(output.filePath, TextFile.WriteOnly);
+ outFile.write(content);
+ outFile.close();
+ };
+ return cmd;
+ }
+ }
+ }
+ \endcode
+
+ And this is how a product would use the module:
+
+ \code
+ Product {
+ type: "processed-txt"
+ Depends { name: "txt_processor" }
+ txt_processor.unwantedCharacters: ["\r"]
+ files: [
+ "file1.raw",
+ "file2.raw"
+ ]
+ }
+ \endcode
+
+ Of course, normally the pre-processed files would not be the target artifacts of the product,
+ but rather serve as inputs to a different rule that will often come from a different module.
+
+ How you make your own modules available to \QBS is explained
+ \l{Custom Modules and Items}{here}.
+
+ \section1 Special Property Values
+
+ For every property defined in a module, \QBS provides the following special built-in values:
+ \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 often encountered in \l{Group Item}{groups}:
+ \code
+ Product {
+ Depends { name: "mymodule" }
+ mymodule.someProperty: ["value1"]
+ Group {
+ name: "special files"
+ files: ["somefile1", "somefile2"]
+ mymodule.someProperty: outer.concat(["value"]) // => ["value1", "value2"]
+ }
+ }
+ \endcode
+
+
+ \section1 Module Properties
+
+ \table
+ \header
+ \li Property
+ \li Type
+ \li Default
+ \li Description
+ \row
+ \li additionalProductTypes
+ \li string list
+ \li empty list
+ \li The elements of this list will be added to the \c type property of a product
+ that has a dependency on the module.
+ \row
+ \li condition
+ \li bool
+ \li \c true
+ \li Controls whether the module is enabled. If this property is \c false, the
+ surrounding \c Module item will not be considered in the module look-up.
+ \row
+ \li present
+ \li bool
+ \li \c true
+ \li This property is read-only. Its value is \c false if and only if the respective
+ \c Depends item had its \c required property set to \c false and the module was
+ not found.
+ \row
+ \li setupBuildEnvironment
+ \li script
+ \li \c undefined
+ \li Script for setting up the environment in which the project is built.
+ Use the \c putEnv, \c getEnv, and \c unsetEnv functions to alter the environment.
+ The return value of this script is ignored.
+ \row
+ \li setupRunEnvironment
+ \li script
+ \li \c setupBuildEnvironment
+ \li Script for setting up the environment in which the project is run.
+ \row
+ \li validate
+ \li script
+ \li \c undefined
+ \li Script that is run after the module is loaded. It can be used to check property
+ values and throw errors in unexpected cases. The return value is ignored.
+ \row
+ \li version
+ \li string
+ \li \c undefined
+ \li The module's version. It consists of integer values separated by dots. You can check
+ for specific values of this property in a \l{Depends item}{Depends} item.
+ \endtable
+*/
diff --git a/doc/reference/items/language/probe.qdoc b/doc/reference/items/language/probe.qdoc
new file mode 100644
index 000000000..b7f61a912
--- /dev/null
+++ b/doc/reference/items/language/probe.qdoc
@@ -0,0 +1,70 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 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 module-item.html
+ \page probe-item.html
+ \nextpage product-item.html
+ \ingroup list-of-language-items
+ \ingroup list-of-items
+
+ \title Probe Item
+ \brief Locates files outside the project.
+
+ A \c Probe item can appear inside a \l{Product Item} and is run prior to building products in
+ order to locate dependent headers, libraries, and other files outside the project directory
+ whose locations are not known ahead of time. \c Probes are similar to configure scripts.
+ \note Because Probes often invoke external processes, which is relatively expensive compared
+ to evaluating normal properties, their results are cached. To force re-evaluation
+ of a Probe, you can supply the \c{--force-probe-execution} command-line option.
+
+ \section1 Probe Properties
+
+ \table
+ \header
+ \li Property
+ \li Type
+ \li Default
+ \li Description
+ \row
+ \li condition
+ \li bool
+ \li true
+ \li Determines whether the probe will actually be run.
+ \row
+ \li found
+ \li bool
+ \li undefined
+ \li Indicates whether the probe was run successfully. Set by \c configure.
+ \row
+ \li configure
+ \li script
+ \li undefined
+ \li Script that is executed when the probe is run.
+ \endtable
+
+*/
diff --git a/doc/reference/items/language/product.qdoc b/doc/reference/items/language/product.qdoc
new file mode 100644
index 000000000..4dd3089ae
--- /dev/null
+++ b/doc/reference/items/language/product.qdoc
@@ -0,0 +1,189 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 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 probe-item.html
+ \page product-item.html
+ \nextpage project-item.html
+ \ingroup list-of-language-items
+ \ingroup list-of-items
+
+ \title Product Item
+ \brief Represents the result of a build process.
+
+ A \e product typically represents the result of a build process. It specifies a set of
+ input and output files and a way to transform the former into the latter. For example, the
+ following product sets up a very simple C++ application:
+ \code
+ Product {
+ name: "helloworld"
+ type: "application"
+ files: "main.cpp"
+ Depends { name: "cpp" }
+ }
+ \endcode
+ The \c type property specifies what will be built (an executable). The \c files property specifies
+ the input files (one C++ source file), and the \c Depends item pulls in the logic from the \c cpp module
+ about how to do the necessary transformations.
+ For some often-used types of products, \QBS pre-defines special derived items that save
+ users some typing. These are:
+ \list
+ \li Application
+ \li CppApplication
+ \li DynamicLibrary
+ \li StaticLibrary
+ \endlist
+ Therefore, the above example could also be written like this:
+ \code
+ CppApplication {
+ name: "helloworld"
+ files: "main.cpp"
+ }
+ \endcode
+ Any property \c prop attached to this item is available in sub-items as \c product.prop, as
+ well as in modules that are loaded from this product.
+
+ \table
+ \header
+ \li Property
+ \li Type
+ \li Default
+ \li Description
+ \row
+ \li builtByDefault
+ \li bool
+ \li true
+ \li If false, the product will only be built if this is explicitly requested,
+ either by listing the product name as an argument to \c --products or by giving
+ the \c build command the \c --all-products option.
+ \row
+ \li condition
+ \li bool
+ \li true
+ \li If false, the product will not be built.
+ \row
+ \li name
+ \li string
+ \li empty string
+ \li The name of the product. Used to identify the product in a \c Depends item, for
+ example. The value of this property must be a simple JavaScript expression that
+ does not depend on module properties or values that are non-local to this product.
+ \code
+ CppApplication {
+ name: "hello" + "world" // valid
+ }
+ CppApplication {
+ name: "app_for_" + qbs.targetOS.join("_") // invalid
+ }
+ \endcode
+ To change the name of your product's target artifact, modify \c{Product.targetName}
+ instead.
+ \row
+ \li profiles
+ \li stringList
+ \li \c{[project.profile]}
+ \li The profiles for which the product should be built. For each profile listed here,
+ one instance of the product will be built according to the properties set in
+ the respective profile.
+ This property is only relevant for projects that require products being built for
+ different architectures. Otherwise it can be left at its default value.
+ \row
+ \li type
+ \li stringList
+ \li empty list
+ \li The file tags matching the product's target artifacts.
+ \row
+ \li targetName
+ \li string
+ \li \c{name} with illegal file name characters replaced by underscores
+ \li The base file name of the product's target artifacts.
+ \row
+ \li destinationDirectory
+ \li string
+ \li product.buildDirectory
+ \li The directory where the target artifacts will be located. If a relative path is
+ given, the base directory will be \c project.buildDirectory.
+ \row
+ \li files
+ \li stringList
+ \li empty list
+ \li A list of source files. Syntactic sugar to save a \c Group item for simple products.
+ \row
+ \li excludeFiles
+ \li stringList
+ \li empty list
+ \li A list of source files not to include. Useful with wildcards.
+ For more information, see \l {Group Item}.
+
+ \row
+ \li consoleApplication
+ \li bool
+ \li linker-dependent
+ \li If true, a console application is generated. If false, a GUI application is generated.
+ Only takes effect on Windows.
+ This property also influences the default application type on Apple platforms.
+ If true, an application bundle is generated. If false, a normal executable is
+ generated.
+ \row
+ \li qbsSearchPaths
+ \li stringList
+ \li project.qbsSearchPaths
+ \li See the documentation of the \l {Project Item} property of the same name.
+ The value set here will be merged with the one inherited from
+ the project.
+ \row
+ \li version
+ \li string
+ \li undefined
+ \li The version number of the product. Used in shared library filenames and generated
+ Info.plist files in Apple application and framework bundles, for example.
+ \endtable
+
+ The following properties are automatically set by \QBS and cannot be changed by the user:
+
+ \table
+ \header
+ \li Property
+ \li Type
+ \li Description
+ \row
+ \li buildDirectory
+ \li path
+ \li The build directory for this product. This is the directory where generated files
+ are placed.
+ \row
+ \li profile
+ \li string
+ \li The profile for building this particular instance of the product. Derived
+ automatically from the \c profiles property.
+ \row
+ \li sourceDirectory
+ \li path
+ \li The source directory for this product. This is the directory of the file where this
+ product is defined.
+ \endtable
+*/
diff --git a/doc/reference/items/language/project.qdoc b/doc/reference/items/language/project.qdoc
new file mode 100644
index 000000000..33d4eb50b
--- /dev/null
+++ b/doc/reference/items/language/project.qdoc
@@ -0,0 +1,111 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 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 product-item.html
+ \page project-item.html
+ \nextpage properties-item.html
+ \ingroup list-of-language-items
+ \ingroup list-of-items
+
+ \title Project Item
+ \brief Represents a collection of products and properties.
+
+ A \c Project item represents a collection of of products. In a
+ non-trivial project, these products are typically defined in their own files and
+ referenced in the main project file:
+ \code
+ Project {
+ references: [
+ "product1/product1.qbs",
+ "product2/product2.qbs"
+ ]
+ }
+ \endcode
+ Any property \c prop attached to this item is available in sub-items as \c project.prop.
+
+ While the root of the item hierarchy is always a \c Project, this kind of item can also
+ appear further down the hierarchy. Such sub-projects are ususally introduced to group products.
+ See the \l{SubProject Item} for details.
+
+ \note If your project consists of only one product, the \c Project item can be omitted.
+
+ \table
+ \header
+ \li Property
+ \li Type
+ \li Default
+ \li Description
+ \row
+ \li buildDirectory
+ \li path
+ \li n/a
+ \li The build directory of the top-level project. This property is read-only.
+ \row
+ \li name
+ \li string
+ \li basename of the file the project is defined in
+ \li The project name. Only relevant for e.g. displaying a project tree in an IDE.
+ \row
+ \li profile
+ \li string
+ \li n/a
+ \li The top-level profile for building the project. This property is read-only and
+ is set by \QBS when the project is being set up.
+ \row
+ \li condition
+ \li bool
+ \li true
+ \li Whether the project is enabled. If false, no products or sub-projects will be
+ collected.
+ \row
+ \li qbsSearchPaths
+ \li stringList
+ \li empty
+ \li These paths are searched for imports and modules in addition to the ones listed
+ in \c{preferences.qbsSearchPaths}. The value set here is merged with the value
+ inherited from the parent project, if there is one. The result is inherited by
+ all products in the project.
+ \row
+ \li references
+ \li path list
+ \li empty
+ \li A list of files from which to import products. This is equivalent to defining
+ the respective \c Product items directly under this \c Project item.
+ \row
+ \li sourceDirectory
+ \li path
+ \li n/a
+ \li The directory where the file containing the top-level \c Project item is located.
+ This property is read-only.
+ \row
+ \li minimumQbsVersion
+ \li string
+ \li "1.3.0"
+ \li The minimum version of qbs that is needed to build this project.
+ \endtable
+*/
diff --git a/doc/reference/items/language/properties.qdoc b/doc/reference/items/language/properties.qdoc
new file mode 100644
index 000000000..4e2cb345f
--- /dev/null
+++ b/doc/reference/items/language/properties.qdoc
@@ -0,0 +1,115 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 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 project-item.html
+ \page properties-item.html
+ \nextpage propertyoptions-item.html
+ \ingroup list-of-language-items
+ \ingroup list-of-items
+
+ \title Properties Item
+ \brief Provides conditional setting of properties.
+
+ \note This documents the \c Properties item in the context of products. Usage within
+ a \c SubProject item is described \l{SubProject Item}{here}.
+
+ The \c Properties item is an auxiliary item for setting multiple property values conditionally.
+
+ In the following example, two properties are set if the project is built for Windows:
+ \code
+ Product {
+ Properties {
+ condition: qbs.targetOS.contains("windows")
+ cpp.defines: ["ON_WINDOWS"]
+ cpp.includePaths: ["extraWindowsIncludes"]
+ }
+ }
+ \endcode
+
+ Multiple \c Properties items can be specified to set properties dependent on different
+ conditions. The order of appearance is important. Semantics are similar to if-else-chains.
+ The following example
+ \code
+ Product {
+ Properties {
+ condition: qbs.targetOS.contains("windows")
+ cpp.defines: ["ON_WINDOWS"]
+ cpp.includePaths: ["myWindowsIncludes"]
+ }
+ Properties {
+ condition: qbs.targetOS.contains("linux")
+ cpp.defines: ["ON_LINUX"]
+ cpp.includePaths: ["myLinuxIncludes"]
+ }
+ cpp.defines: ["ON_UNKNOWN_PLATFORM"]
+ }
+ \endcode
+ is equivalent to
+ \code
+ Product {
+ cpp.defines: {
+ if (qbs.targetOS.contains("windows"))
+ return ["ON_WINDOWS"];
+ if (qbs.targetOS.contains("linux"))
+ return ["ON_LINUX"];
+ return ["ON_UNKNOWN_PLATFORM"];
+ }
+ cpp.includePaths: {
+ if (qbs.targetOS.contains("windows"))
+ return ["myWindowsIncludes"];
+ if (qbs.targetOS.contains("linux"))
+ return ["myLinuxIncludes"];
+ return base;
+ }
+ }
+ \endcode
+
+ We suggest to use the \c Properties item for mutually exclusive conditions only. It is
+ especially useful if there are several properties to set, based on the same condition.
+
+ \table
+ \header
+ \li Property
+ \li Type
+ \li Default
+ \li Description
+ \row
+ \li condition
+ \li bool
+ \li none - must be specified
+ \li The condition to be used for the other bindings in this item.
+ \row
+ \li overrideListProperties
+ \li bool
+ \li \c false
+ \li List properties set within this item will override the values coming from
+ modules, rather than getting merged with them, which is the default behavior.
+ Use this in the rare case that a module you depend on inserts a value into
+ a list property that is problematic for some product.
+ \endtable
+*/
diff --git a/doc/reference/items/language/propertyoptions.qdoc b/doc/reference/items/language/propertyoptions.qdoc
new file mode 100644
index 000000000..701f5ab43
--- /dev/null
+++ b/doc/reference/items/language/propertyoptions.qdoc
@@ -0,0 +1,67 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 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 properties-item.html
+ \page propertyoptions-item.html
+ \nextpage rule-item.html
+ \ingroup list-of-language-items
+ \ingroup list-of-items
+
+ \title PropertyOptions Item
+ \brief Provides inline documentation for properties within product and module items.
+
+ A \c PropertyOptions item can appear inside a \l{Product Item} or \l{Module Item} to provide
+ inline documentation for properties.
+
+ \section1 PropertyOptions Properties
+
+ \table
+ \header
+ \li Property
+ \li Type
+ \li Default
+ \li Description
+ \row
+ \li allowedValues
+ \li stringList
+ \li undefined
+ \li A list of the values permitted by the property. \c{undefined} indicates that any value
+ is permitted.
+ \row
+ \li description
+ \li string
+ \li undefined
+ \li A brief description of the property.
+ \row
+ \li name
+ \li string
+ \li undefined
+ \li The name of the property to document.
+ \endtable
+
+*/
diff --git a/doc/reference/items/language/rule.qdoc b/doc/reference/items/language/rule.qdoc
new file mode 100644
index 000000000..8d53e3845
--- /dev/null
+++ b/doc/reference/items/language/rule.qdoc
@@ -0,0 +1,294 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 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 propertyoptions-item.html
+ \page rule-item.html
+ \nextpage scanner-item.html
+ \ingroup list-of-language-items
+ \ingroup list-of-items
+
+ \title Rule Item
+ \brief Creates transformers for input tags.
+
+ In \QBS, rules create \e transformers that produce output files from input files.
+ The term \e transformer refers to a list of \l{Command and JavaScriptCommand}{commands}.
+ These commands are created in a rule's \e {prepare script}. They do the actual work, either
+ directly or by executing external commands.
+
+ \section1 A Simple Example
+
+ The following rule takes text files and replaces Windows-style line endings with their
+ Unix-style counterparts. We will look at it one piece at a time.
+
+ \code
+ Rule {
+ multiplex: false
+ \endcode
+ A \e {multiplex rule} creates one transformer that takes all input artifacts with the
+ matching input file tag and creates one or more output artifacts. We are setting the
+ respective property to \c false here, indicating that we want to create one transformer
+ per input file.
+ \note This is actually the default, so the above assignment is not required.
+ \code
+ inputs: ["txt_input"]
+ \endcode
+ Here we are specifying that our rule is interested in input files that have the tag
+ "txt_input". Such files could be source files, in which case you would tag them
+ using a \l{Group Item}{Group}. Or they could in turn get generated by a different rule,
+ in which case that rule would assign the file tag.
+ The files matching the tag will be available in the prepare script under the name
+ \c inputs (see \l{inputs and outputs}{The inputs and outputs Variables}).
+ \code
+ Artifact {
+ filePath: input.fileName + ".out"
+ fileTags: ["txt_output"]
+ }
+ \endcode
+ Here we are specifying that for every input file, we want to create one output file
+ whose name is the same as the input file, but with an additional extension. Because we are
+ giving a relative path, \QBS will prepend that path by the product's build directory.
+
+ In addition, we tell \QBS that the output files should get the file tag "txt_output". This
+ enables other rules to use these files as inputs. You must always assign suitable file tags
+ to your output artifacts, or the rule will not be run.
+ See \l{Rules and Product Types} for details.
+
+ If you want to create more than one output file per input file, you simply provide multiple
+ \c Artifact items. The set of output artifacts will be available in the prepare script
+ under the name \c outputs (see \l{inputs and outputs}{The inputs and outputs Variables}).
+
+ \code
+ prepare: {
+ var cmd = new JavaScriptCommand();
+ cmd.description = input.fileName + "->" + output.fileName;
+ cmd.highlight = "codegen";
+ cmd.sourceCode = function() {
+ var file = new TextFile(input.filePath);
+ var content = file.readAll();
+ file.close()
+ content = content.replace(/\r\n/g, "\n");
+ file = new TextFile(output.filePath, TextFile.WriteOnly);
+ file.write(content);
+ file.close();
+ }
+ return [cmd];
+ }
+ }
+ \endcode
+ The prepare script shown above puts everything together by creating the command that does
+ the actual transformation of the file contents, employing the help of the
+ \l{TextFile Service}{TextFile} class.
+
+ As you can see, the return value is an array, meaning you can provide several commands to
+ implement the rule's functionality. For instance, if we had provided two \c Artifact items,
+ we might have also provided two commands, each of them creating one output file.
+
+ For the \c input and \c output variables used in the code, see the next section.
+
+ \target inputs and outputs
+ \section1 The \c inputs and \c outputs Variables
+
+ We already mentioned that the input and output artifacts are available in the prepare script
+ via the variables \c inputs and \c outputs, respectively. These variables are JavaScript
+ objects whose property keys are file tags and whose property values are lists of objects
+ representing the artifacts matching these tags. In our example, the \c inputs variable
+ has a single property \c txt_input, whose value is a list with one element. Similarly, the
+ \c outputs variable also has one single property \c txt_output, again with a list containing
+ one element.
+
+ The actual artifact objects have the following properties:
+ \table
+ \header
+ \li Property
+ \li Description
+ \row
+ \li \c baseName
+ \li The file name without any extension.
+ \row
+ \li \c completeBaseName
+ \li The file name without the last extension.
+ \row
+ \li \c fileName
+ \li The name of the file (that is, \c filePath without any directory components).
+ \row
+ \li \c filePath
+ \li The full file path.
+ \row
+ \li \c fileTags
+ \li The list of the artifact's file tags.
+ \row
+ \li \c moduleProperty
+ \li A function taking two parameters. The first one is the name of a module,
+ the second one is the name of a property in that module. For instance, for an
+ artifact in a C++ product, a call to \c{moduleProperty("cpp", "defines")} returns the
+ list of defines that will be passed when compiling the respective file.
+ \endtable
+
+ But what about the variables \c input and \c output that appeared in our example? These
+ are simply convenience variables which are available in the case that the \c inputs
+ and \c outputs variables contain only one artifact, respectively. So in our example, instead
+ of \c input we also could have written \c {inputs.txt_input[0]}, which is considerably
+ more verbose.
+
+ \section1 Rules and Product Types
+
+ It is important to know that when figuring out which rules to execute, \QBS starts at the
+ product type and then looks for a way to produce artifacts with matching file tags from
+ source files, using a chain of rules that are connected by their respective input and output
+ tags. For instance, consider this simple C++ project:
+ \code
+ Product {
+ type: ["application"]
+ Depends { name: "cpp" }
+ files: ["main.cpp"]
+ }
+ \endcode
+ Here's how this product is built:
+ \list 1
+ \li \QBS looks for a rule that can produce artifacts with the file tag
+ \c{"application"}. Such a rule is found in the \c cpp module (namely, the rule that
+ invokes the linker).
+ \li Since the rule found in the previous step takes inputs of type \c{"obj"}, \QBS now
+ looks for a rule that produces artifacts of that type. Again, such a rule is found in
+ the \c cpp module (the rule that runs the compiler).
+ \li The rule found in the previous step takes inputs of type \c{"cpp"}. No rule is found
+ that creates such artifacts, but we do have a source file with a matching type (because
+ the \c cpp module contains a \l{FileTagger item}{FileTagger} which attached that type
+ to \c{"main.cpp"} due to its file extension).
+ \li Now that there is a chain of rules leading from a source file tag to the product type,
+ the commands of these rules are executed one after the other until we end up with
+ our executable.
+ \endlist
+
+ \section1 Rule Properties
+
+ \table
+ \header
+ \li Property
+ \li Type
+ \li Default
+ \li Description
+ \row
+ \li multiplex
+ \li bool
+ \li false
+ \li Determines whether this is a multiplex rule.
+ \row
+ \li inputs
+ \li string list
+ \li undefined
+ \li File tags the input artifacts must match.
+ All output artifacts will depend on all artifacts in the product with
+ the given input file tags. Also these artifacts are available in the
+ inputs variable of the prepare script.
+ \row
+ \li auxiliaryInputs
+ \li string list
+ \li undefined
+ \li A list of file tags. This rule will be dependent on every other rule
+ that produces artifacts that are compatible with \a{auxiliaryInputs}.
+ Unlike \a{inputs}, the property \a{auxiliaryInputs} has no effect on the content of the
+ \a{inputs} variable in the \a{prepare} script.
+ \row
+ \li excludedAuxiliaryInputs
+ \li string list
+ \li undefined
+ \li A list of file tags. Connections to rules that produce these file tags are prevented.
+ This property has no effect on the content of the \a{inputs} variable in the \a{prepare}
+ script.
+ \row
+ \li inputsFromDependencies
+ \li string list
+ \li undefined
+ \li File tags the artifacts of product dependencies must match.
+ For example, the product \a foo might appear as follows in the current product:
+ \code
+ Depends {
+ name: "foo"
+ }
+ \endcode
+ All artifacts of \a foo that match the given
+ file tags will appear in the \a inputs variable of the prepare
+ script. Also, each output artifact of this rule will be dependent on
+ those artifacts.
+ \row
+ \li outputArtifacts
+ \li array of objects
+ \li undefined
+ \li An array of output artifacts, specified as JavaScript objects.
+ Example:
+ \code
+ outputArtifacts: [{
+ filePath: "myfile.cpp",
+ fileTags: ["cpp"],
+ cpp: { cxxLanguageVersion: "c++11" }
+ }]
+ \endcode
+ For a description of the possible properties, see the documentation of the
+ \l{Artifact item}.
+ Output artifacts can be specified either by \c{Rule.outputArtifacts} or by \c{Artifact}
+ items. Use \c{Rule.outputArtifacts} if the set of outputs is not fixed but dependent on
+ the input's content. If no file tags are provided, \QBS will apply all
+ \l{FileTagger Item}{file taggers} known in the current context to the output file name.
+ The user may set the property \c{explicitlyDependsOn} on artifact objects, which is
+ similar to \c{Rule.explicitlyDependsOn}.
+ \row
+ \li outputFileTags
+ \li string list
+ \li undefined
+ \li If output artifacts are specified by \c{Rule.outputArtifacts}, then
+ \c{Rule.outputFileTags} must be a list of file tags the rule potentially produces.
+ \row
+ \li condition
+ \li bool
+ \li true
+ \li If true, the rule is enabled, otherwise it does nothing.
+ \row
+ \li explicitlyDependsOn
+ \li string list
+ \li undefined
+ \li Each artifact that matches the file tags in \a explicitlyDependsOn
+ is added to the dependencies of each output node.
+ \row
+ \li prepare
+ \li script
+ \li undefined
+ \li Script that prepares the commands to transform the inputs to outputs.
+ The code in this script is treated as a function with the signature
+ \c{function(project, product, inputs, outputs, input, output)}.
+ The argument \c{input} is \c{undefined} if there's more than one input artifact for this
+ rule. Similarly, \c{output} is only defined if there's exactly one output artifact.
+ \row
+ \li alwaysRun
+ \li bool
+ \li false
+ \li If true, the rule's commands are always executed, even if all output artifacts
+ are up to date.
+ \endtable
+
+*/
diff --git a/doc/reference/items/language/scanner.qdoc b/doc/reference/items/language/scanner.qdoc
new file mode 100644
index 000000000..44c93d168
--- /dev/null
+++ b/doc/reference/items/language/scanner.qdoc
@@ -0,0 +1,95 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 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 rule-item.html
+ \page scanner-item.html
+ \nextpage subproject-item.html
+ \ingroup list-of-language-items
+ \ingroup list-of-items
+
+ \title Scanner Item
+ \brief Creates custom dependency scanners in modules.
+
+ An \c Scanner item can appear inside a \l{Module Item}, and allows to define
+ artifacts dependency, according to the artifacts contents.
+ For example scanner for "qrc" files:
+ \code
+ import qbs.Xml
+
+ Module {
+ Scanner {
+ condition: true
+ inputs: 'qrc'
+ scan: {
+ var xml = new XmlDomDocument(input.filePath);
+ dependencies = [];
+ // do something with the xml
+ return dependencies;
+ }
+ }
+ }
+ \endcode
+
+ \section1 Scanner Properties
+ \table
+ \header
+ \li Property
+ \li Type
+ \li Default
+ \li Description
+ \row
+ \li condition
+ \li bool
+ \li true
+ \li If true, the scanner is enabled, otherwise it does nothing.
+ \row
+ \li inputs
+ \li string list
+ \li undefined
+ \li File tags the input artifacts must match.
+ \row
+ \li recursive
+ \li bool
+ \li false
+ \li Determines whether to scan dependencies recursively.
+ \row
+ \li searchPaths
+ \li script
+ \li undefined
+ \li Script that returns paths to look for dependencies.
+ The code in this script is treated as a function with the signature
+ \c{function(project, product, input)}.
+ \row
+ \li scan
+ \li script
+ \li undefined
+ \li Script that reads the input artifact and returns string list with dependencies.
+ The code in this script is treated as a function with the signature
+ \c{function(project, product, input)}.
+ \endtable
+*/
diff --git a/doc/reference/items/language/subproject.qdoc b/doc/reference/items/language/subproject.qdoc
new file mode 100644
index 000000000..644b600aa
--- /dev/null
+++ b/doc/reference/items/language/subproject.qdoc
@@ -0,0 +1,75 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 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 scanner-item.html
+ \page subproject-item.html
+ \ingroup list-of-language-items
+ \ingroup list-of-items
+
+ \title SubProject Item
+ \brief Adds a project from a different file.
+
+ A \c SubProject item is used to add a project defined in another file as a sub-project to
+ the surrounding project:
+ \code
+ SubProject {
+ filePath: "subdir/project.qbs"
+ Properties {
+ name: "A sub-project"
+ }
+ }
+ \endcode
+
+ If you don't need to set any properties on the sub-project, you can also use the \c references
+ property, the same way you would do for a product:
+ \code
+ references: "subdir/project.qbs"
+ \endcode
+
+ It is also possible to nest \c Project items directly in the same file.
+
+ \table
+ \header
+ \li Property
+ \li Type
+ \li Default
+ \li Description
+ \row
+ \li filePath
+ \li path
+ \li empty
+ \li The file path of the project to add as a sub-project. If the top-level item in this
+ file is a \c Product, it gets wrapped automatically in a new project.
+ \row
+ \li inheritProperties
+ \li bool
+ \li true
+ \li Whether the sub-project should inherit the properties of the surrounding project.
+ You can use this feature to share "global" settings between (sub-)projects.
+ \endtable
+*/
generated by cgit v1.2.3 (git 2.25.1) at 2024-06-25 05:17:52 +0000