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 simplex rule creates one transformer per matching input file (e.g. C++ compiler). For instance, the following rule transforms text files:

Rule {
    inputs: ["txt_input"]
    Artifact {
        filePath: "output.txt"
        fileTags: "txt_output"
    }
    prepare: {
        var cmd = new JavaScriptCommand();
        cmd.description = "Processing '" + input.filePath + "'";
        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;
    }
}

This example exhibits some interesting features of rules:

  • If there is only one input file, the property input is available as syntactic sugar for inputs[0].
  • The filenames of the output artifacts are available as outputs. If there is only one of these, it can be referred to it as output.

As a real-world example of a simplex rule, here is a simplified version of Qbs' rule for transforming C++ sources into object files using gcc:

import qbs.ModUtils
import qbs.Utilities
Rule {
    id: compiler
    inputs: ['cpp']
    auxiliaryInputs: ['hpp']

    Artifact {
        fileTags: ['obj']
        filePath: '.obj/' + Utilities.getHash(input.baseDir) + '/' + input.fileName + '.o'
    }

    prepare: {
        var args = [];
        if (product.moduleProperty('cpp', 'debugInformation'))
            args.push('-g');
        var warnings = product.moduleProperty('cpp', 'warningLevel')
        if (warnings === 'none')
            args.push('-w');
        if (warnings === 'all') {
            args.push('-Wall');
            args.push('-Wextra');
        }
        if (product.moduleProperty('cpp', 'treatWarningsAsErrors'))
            args.push('-Werror');
        var includePaths = product.moduleProperties('cpp', 'includePaths');
        for (i in includePaths)
            args.push('-I' + includePaths[i]);
        var defines = product.moduleProperties('cpp', 'defines');
        for (i in defines)
            args.push('-D' + defines[i]);
        args.push('-c');
        args.push(input.filePath);
        args.push('-o');
        args.push(output.filePath);
        var compilerPath = ModUtils.moduleProperty(product, 'compilerPath');
        var cmd = new Command(compilerPath, args);
        cmd.description = 'compiling ' + input.fileName;
        cmd.highlight = 'compiler';
        return cmd;
    }
}

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:

Product {
    type: ["application"]
    Depends { name: "cpp" }
    files: ["main.cpp"]
}

Here's how this product is built:

  1. Qbs looks for a rule that can produce artifacts with the file tag "application". Such a rule is found in the cpp module (namely, the rule that invokes the linker).
  2. Since the rule found in the previous step takes inputs of type "obj", Qbs now looks for a rule that produces artifacts of that type. Again, such a rule is found in the cpp module (the rule that runs the compiler).
  3. The rule found in the previous step takes inputs of type "cpp". No rule is found that creates such artifacts, but we do have a source file with a matching type (because the cpp module contains a FileTagger which attached that type to "main.cpp" due to its file extension).
  4. 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.

Rule Properties

PropertyTypeDefaultDescription
multiplexboolfalseDetermines whether this is a multiplex rule.
inputsstring listundefinedFile 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.
auxiliaryInputsstring listundefinedA list of file tags. This rule will be dependent on every other rule that produces artifacts that are compatible with auxiliaryInputs. Unlike inputs, the property auxiliaryInputs has no effect on the content of the inputs variable in the prepare script.
excludedAuxiliaryInputsstring listundefinedA list of file tags. Connections to rules that produce these file tags are prevented. This property has no effect on the content of the inputs variable in the prepare script.
inputsFromDependenciesstring listundefinedFile tags the artifacts of product dependencies must match. For example, the product foo might appear as follows in the current product:
Depends {
    name: "foo"
}

All artifacts of foo that match the given file tags will appear in the inputs variable of the prepare script. Also, each output artifact of this rule will be dependent on those artifacts.

outputArtifactsarray of objectsundefinedAn array of output artifacts, specified as JavaScript objects. Example:
outputArtifacts: [{filePath: "myfile.txt", fileTags: ["foo", "bar"]}]

For a description of the possible properties, see the documentation of the Artifact item. Output artifacts can be specified either by Rule.outputArtifacts or by Artifact items. Use 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 file taggers known in the current context to the output file name. The user may set the property explicitlyDependsOn on artifact objects, which is similar to Rule.explicitlyDependsOn.

outputFileTagsstring listundefinedIf output artifacts are specified by Rule.outputArtifacts, then Rule.outputFileTags must be a list of file tags the rule potentially produces.
conditionbooltrueIf true, the rule is enabled, otherwise it does nothing.
explicitlyDependsOnstring listundefinedEach artifact that matches the file tags in explicitlyDependsOn is added to the dependencies of each output node.
preparescriptundefinedScript that prepares the commands to transform the inputs to outputs. The code in this script is treated as a function with the signature function(project, product, inputs, outputs, input, output). The argument input is undefined if there's more than one input artifact for this rule. Similarly, output is only defined if there's exactly one output artifact.
alwaysRunboolfalseIf true, the rule's commands are always executed, even if all output artifacts are up to date.

© 2016 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.