diff options
author | Christian Kandeler <christian.kandeler@digia.com> | 2013-01-21 17:32:02 +0100 |
---|---|---|
committer | Christian Kandeler <christian.kandeler@digia.com> | 2013-01-22 12:31:38 +0100 |
commit | 4e466e782e05c170be9376d13a24982789a89012 (patch) | |
tree | 942cedb9f9285304c092c44fd1558fd22fab1ba2 /doc | |
parent | 5cdf94de300e72987dfbe5c0fec5b86317ad6280 (diff) |
Start modularizing the qdoc sources.
The documentation should not be in a single blob. Start the modularizing
effort by putting the item descriptions into dedicated files.
Change-Id: Ie96fc9397a1d32125ff774fe2ed6dde06cb457d6
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@digia.com>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/config/qbs-project.qdocconf | 2 | ||||
-rw-r--r-- | doc/items/filetagger.qdoc | 82 | ||||
-rw-r--r-- | doc/items/group.qdoc | 151 | ||||
-rw-r--r-- | doc/items/product.qdoc | 100 | ||||
-rw-r--r-- | doc/items/rule.qdoc | 98 | ||||
-rw-r--r-- | doc/qbs.qdoc | 324 |
6 files changed, 433 insertions, 324 deletions
diff --git a/doc/config/qbs-project.qdocconf b/doc/config/qbs-project.qdocconf index b9a6746a3..eaa636823 100644 --- a/doc/config/qbs-project.qdocconf +++ b/doc/config/qbs-project.qdocconf @@ -12,7 +12,7 @@ include(macros.qdocconf) include(qt-cpp-ignore.qdocconf) include(qt-defines.qdocconf) -sources.fileextensions = "qbs.qdoc" +sources.fileextensions = "*.qdoc" qhp.projects = Qbs diff --git a/doc/items/filetagger.qdoc b/doc/items/filetagger.qdoc new file mode 100644 index 000000000..e4f2c1cb5 --- /dev/null +++ b/doc/items/filetagger.qdoc @@ -0,0 +1,82 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** 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 Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/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 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Digia gives you certain additional +** rights. These rights are described in the Digia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +****************************************************************************/ +/*! + \contentspage index.html + \previouspage qbs-group-item.html + \page qbs-filetagger-item.html + \nextpage qbs-product-item.html + + \title FileTagger Item + + 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, qbs' cpp module has, among others, + the following file tagger: + \code + FileTagger { + pattern: "*.cpp" + fileTags: ["cpp"] + } + \endcode + As a result, all files ending with ".cpp" in products depending on the cpp module automatically + get the "cpp" tag, which will cause 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, cpp files in the following product will not get the "cpp" tag: + \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 pattern + \li string + \li none + \li The pattern to match against. Supports the usual wildcards '*', '?' and '[]'. + \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/items/group.qdoc b/doc/items/group.qdoc new file mode 100644 index 000000000..230944627 --- /dev/null +++ b/doc/items/group.qdoc @@ -0,0 +1,151 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** 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 Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/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 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Digia gives you certain additional +** rights. These rights are described in the Digia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +****************************************************************************/ + +/*! + \contentspage index.html + \previouspage qbs-rule-item.html + \page qbs-group-item.html + \nextpage qbs-filetagger-item.html + + \title Group Item + + This item is attached to a product and is used to group files that have something in common. For instance: + \code + Application { + Group { + name: "common files" + files: ["myclass.h", "myclass_common_impl.cpp"] + } + Group { + name: "Windows files" + condition: targetOs === "windows" + files: "myclass_win_impl.cpp" + } + Group { + name: "Linux files" + condition: targetOs === "linux" + files: "myclass_linux_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. + Here's an example: + \code + Group { + name: "Word processing documents" + files: ["*.doc", "*.rtf"] + recursive: true + qbs.install: true + qbs.installDir: "share" + excludeFiles: "do_not_install_this_file.*" + } + \endcode + \note Wildcards can match only regular files, not directories. + + 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 + + \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 prefix to append 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 generated 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 If the same file appears in the files list of both the top level of a product and + a group and this property is true, then the file tags set via the group + replace the ones set via the product. If it is false, the "group tags" are are added to + the "product tags". + \row + \li recursive + \li bool + \li false + \li For use with wildcards; determines whether to descend into subdirectories. + \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/items/product.qdoc b/doc/items/product.qdoc new file mode 100644 index 000000000..3633275a0 --- /dev/null +++ b/doc/items/product.qdoc @@ -0,0 +1,100 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** 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 Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/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 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Digia gives you certain additional +** rights. These rights are described in the Digia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +****************************************************************************/ +/*! + \contentspage index.html + \previouspage qbs-filetagger-item.html + \page qbs-product-item.html + + \title Product Item + + \table + \header + \li Product Item + \li Description + \li Property + \li Property Description + \row + \li Product + \li Generic product. + \li + \li + \row + \li + \li + \li condition + \li Boolean value. If false, the product is excluded from build. Default is true. + \row + \li + \li + \li name + \li The name of the product for referencing it in Depends items. + \row + \li + \li + \li type + \li A list of file tags the product is going to create. + \row + \li + \li + \li targetName + \li The base file name of the generated file. If not set, \a name is used. + \row + \li + \li + \li destination + \li The destination directory of the produced file. Relative to the build dir. + \row + \li + \li + \li files + \li List of source files. + \row + \li + \li + \li consoleApplication + \li Boolean value. If set to true, a console application is generated. + If false, a GUI application is generated. Default is undefined / not set, + which means the linker decides. This only has an effect on Windows. + \row + \li Application + \li Product with type "application" or "applicationbundle" on Mac. + \li + \li + \row + \li DynamicLibrary + \li Product with type "dynamiclibrary". Produces a DLL or shared object. + \li + \li + \row + \li StaticLibrary + \li Product with type "staticlibrary". Produces a static library. + \li + \li + \endtable +*/ diff --git a/doc/items/rule.qdoc b/doc/items/rule.qdoc new file mode 100644 index 000000000..8fc375c8d --- /dev/null +++ b/doc/items/rule.qdoc @@ -0,0 +1,98 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** 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 Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/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 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Digia gives you certain additional +** rights. These rights are described in the Digia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +****************************************************************************/ +/*! + \contentspage index.html + \previouspage qbs-functions.html + \page qbs-rule-item.html + \nextpage qbs-group-item.html + + \title Rule Item + + A "multiplex rule" creates one transformer that takes all + input artifacts with the matching input file tag and creates + one or more artifacts (e.g. C++ linker). + A "non-multiplex rule" creates one transformer per matching input file (e.g. C++ + compiler). + + \section1 Rule properties + + \table + \header + \li Property + \li Type + \li Default + \li Description + \row + \li multiplex + \li bool + \li false + \li Determines if 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 usings + \li string list + \li undefined + \li File tags the artifacts of product dependencies must match. + Let there be a product \a foo which appears as + \code + Depends { + name: "foo" + } + \endcode + in the current product. All artifacts of \a foo that match the given + file tags will appear in the \a inputs variable of the prepare + script. Also, every output artifact of this rule will be dependent on + those artifacts. + \row + \li explicitlyDependsOn + \li string list + \li undefined + \li Every artifact that matches the file tags in \a explicitlyDependsOn + is added to the dependencies of every output node. + \row + \li scanners + \li string list + \li undefined + \li List of dependency scanner ids for this rule. The scanners are + running just before the prepare script is executed. + \row + \li prepare + \li script + \li undefined + \li Script that prepares the commands to transform the inputs to outputs. + \endtable + +*/ diff --git a/doc/qbs.qdoc b/doc/qbs.qdoc index 775533063..39d05d013 100644 --- a/doc/qbs.qdoc +++ b/doc/qbs.qdoc @@ -699,7 +699,7 @@ \contentspage index.html \previouspage qbs-building-applications.html \page qbs-installing-files.html - \nextpage qbs-running.html + \nextpage qbs-running-applications.html \title Installing Files @@ -791,255 +791,6 @@ /*! \contentspage index.html - \previouspage qbs-functions.html - \page qbs-rule-item.html - \nextpage qbs-group-item.html - - \title Rule Item - - A "multiplex rule" creates one transformer that takes all - input artifacts with the matching input file tag and creates - one or more artifacts (e.g. C++ linker). - A "non-multiplex rule" creates one transformer per matching input file (e.g. C++ - compiler). - - \section1 Rule properties - - \table - \header - \li Property - \li Type - \li Default - \li Description - \row - \li multiplex - \li bool - \li false - \li Determines if 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 usings - \li string list - \li undefined - \li File tags the artifacts of product dependencies must match. - Let there be a product \a foo which appears as - \code - Depends { - name: "foo" - } - \endcode - in the current product. All artifacts of \a foo that match the given - file tags will appear in the \a inputs variable of the prepare - script. Also, every output artifact of this rule will be dependent on - those artifacts. - \row - \li explicitlyDependsOn - \li string list - \li undefined - \li Every artifact that matches the file tags in \a explicitlyDependsOn - is added to the dependencies of every output node. - \row - \li scanners - \li string list - \li undefined - \li List of dependency scanner ids for this rule. The scanners are - running just before the prepare script is executed. - \row - \li prepare - \li script - \li undefined - \li Script that prepares the commands to transform the inputs to outputs. - \endtable - -*/ - -/*! - \contentspage index.html - \previouspage qbs-rule-item.html - \page qbs-group-item.html - \nextpage qbs-filetagger-item.html - - \title Group Item - - This item is attached to a product and is used to group files that have something in common. For instance: - \code - Application { - Group { - name: "common files" - files: ["myclass.h", "myclass_common_impl.cpp"] - } - Group { - name: "Windows files" - condition: targetOs === "windows" - files: "myclass_win_impl.cpp" - } - Group { - name: "Linux files" - condition: targetOs === "linux" - files: "myclass_linux_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. - Here's an example: - \code - Group { - name: "Word processing documents" - files: ["*.doc", "*.rtf"] - recursive: true - qbs.install: true - qbs.installDir: "share" - excludeFiles: "do_not_install_this_file.*" - } - \endcode - \note Wildcards can match only regular files, not directories. - - 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 - - \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 prefix to append 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 generated 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 If the same file appears in the files list of both the top level of a product and - a group and this property is true, then the file tags set via the group - replace the ones set via the product. If it is false, the "group tags" are are added to - the "product tags". - \row - \li recursive - \li bool - \li false - \li For use with wildcards; determines whether to descend into subdirectories. - \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 -*/ - -/*! - \contentspage index.html - \previouspage qbs-group-item.html - \page qbs-filetagger-item.html - \nextpage qbs-product-item.html - - \title FileTagger Item - - 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, qbs' cpp module has, among others, - the following file tagger: - \code - FileTagger { - pattern: "*.cpp" - fileTags: ["cpp"] - } - \endcode - As a result, all files ending with ".cpp" in products depending on the cpp module automatically - get the "cpp" tag, which will cause 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, cpp files in the following product will not get the "cpp" tag: - \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 pattern - \li string - \li none - \li The pattern to match against. Supports the usual wildcards '*', '?' and '[]'. - \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 -*/ - -/*! - \contentspage index.html \previouspage qbs-reference.html \page qbs-functions.html \nextpage qbs-rule-item.html @@ -1047,76 +798,3 @@ \title Qbs Functions */ - -/*! - \contentspage index.html - \previouspage qbs-filetagger-item.html - \page qbs-product-item.html - - \title Product Item - - \table - \header - \li Product Item - \li Description - \li Property - \li Property Description - \row - \li Product - \li Generic product. - \li - \li - \row - \li - \li - \li condition - \li Boolean value. If false, the product is excluded from build. Default is true. - \row - \li - \li - \li name - \li The name of the product for referencing it in Depends items. - \row - \li - \li - \li type - \li A list of file tags the product is going to create. - \row - \li - \li - \li targetName - \li The base file name of the generated file. If not set, \a name is used. - \row - \li - \li - \li destination - \li The destination directory of the produced file. Relative to the build dir. - \row - \li - \li - \li files - \li List of source files. - \row - \li - \li - \li consoleApplication - \li Boolean value. If set to true, a console application is generated. - If false, a GUI application is generated. Default is undefined / not set, - which means the linker decides. This only has an effect on Windows. - \row - \li Application - \li Product with type "application" or "applicationbundle" on Mac. - \li - \li - \row - \li DynamicLibrary - \li Product with type "dynamiclibrary". Produces a DLL or shared object. - \li - \li - \row - \li StaticLibrary - \li Product with type "staticlibrary". Produces a static library. - \li - \li - \endtable -*/ |