diff options
Diffstat (limited to 'doc/reference/items/language/rule.qdoc')
| -rw-r--r-- | doc/reference/items/language/rule.qdoc | 294 |
1 files changed, 294 insertions, 0 deletions
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 + +*/ |