规则

为输入标签创建转换器。 更多信息...

• 所有成员的列表，包括继承成员
• 规则是所有项目列表的一部分。所有项目列表.

属性

• alwaysRun : bool
• auxiliaryInputs : stringList
• condition : bool
• excludedInputs : stringList
• explicitlyDependsOn : stringList
• explicitlyDependsOnFromDependencies : stringList
• inputs : stringList
• inputsFromDependencies : stringList
• multiplex : bool
• outputArtifacts : var
• outputFileTags : stringList
• prepare : script
• requiresInputs : bool

详细描述

在 Qbs 中，规则创建用于从输入文件生成输出文件的 转换器。术语 转换器 指的是一系列 命令。这些命令在一个规则的 准备 脚本中创建。它们执行实际工作，或者直接执行，或者通过执行外部命令。

简单示例

以下规则将文本文件从以 Windows 风格的行结束符更改为 Unix 风格的对应项。我们将逐一查看它。

    Rule {
        multiplex: false

一个 复用规则 创建一个转换器，它从所有匹配的输入文件标签的输入项目生成一个或多个输出项目。我们在这里将各自的属性设置为 false，表示我们想要为每个输入文件创建一个转换器。

        inputs: ["txt_input"]

这里我们指定我们的规则对具有标签 "txt_input" 的输入文件感兴趣。这样的文件可以是源文件；在这种情况下，您将使用 组 标记它们。或者它们可以由不同的规则生成，在这种情况下，该规则将分配文件标签。匹配该标签的文件将在 准备 脚本中以 inputs 的名称提供（请参阅 输入和输出变量）。

        Artifact {
            filePath: input.fileName + ".out"
            fileTags: ["txt_output"]
        }

在此，我们指定对于每个输入文件，我们要创建一个输出文件，其名称与输入文件相同，但需要添加一个扩展名。因为我们提供了一个相对路径，Qbs 将在这个路径之前添加产品的构建目录。

此外，我们通知 Qbs，输出文件应获取文件标记 "txt_output"。这使其他规则可以使用这些文件作为输入。您必须始终为您的输出工件分配合适的文件标记，否则规则将不会运行。有关详细信息，请参阅 规则和产品类型。

如果您想为每个输入文件创建多个输出文件，您只需提供多个 工件 项。输出工件集将在准备脚本中命名为 outputs（参见 输入和输出变量）。

        prepare: {
            var cmd = new JavaScriptCommand();
            cmd.description = "generating" + output.fileName + " from " + input.fileName;
            cmd.highlight = "codegen";
            cmd.sourceCode = function() {
                var file = new TextFile(input.filePath);
                var content = file.readAll();
                file.close()
                content = content.toUpperCase();
                file = new TextFile(output.filePath, TextFile.WriteOnly);
                file.write(content);
                file.close();
            }
            return [cmd];
        }
    }

上面的准备脚本通过创建实际转换文件内容的命令将一切组合起来，利用了 TextFile 类的帮助。

如您所见，返回值是一个数组，这意味着您可以提供多个命令以实现规则的实用性。例如，如果我们提供了两个 Artifact 项，我们也可能提供两个命令，每个命令创建一个输出文件。

有关代码中使用的 input 和 output 变量，请参阅下一节。

输入和输出变量

我们已提到输入和输出工件可以通过 inputs 和 outputs 变量分别在准备脚本中获取。这些变量是 JavaScript 对象，其属性键是文件标记，其属性值是表示匹配这些标记的工件的对象的列表。在我们的示例中，inputs 变量有一个单一的属性 txt_input，其值是一个只有一个元素的列表。同样，outputs 变量也有一个单一的属性 txt_output，同样是一个只包含一个元素的列表。

实际的工件对象具有以下属性

工件对象包含每个在产品中使用的模块的属性。这可以用来访问模块的属性。例如，对于 C++ 产品中的工件，artifact.cpp.defines 是在编译相应文件时传递的 define 列表。

但我们的例子中出现的变量 input 和 output 怎么样？这些变量仅仅是提供便利的变量，在 inputs 和 outputs 变量只包含一个工件时可用。因此，在我们的例子中，我们也可以用 inputs.txt_input[0] 替代 input，这会更冗长。

规则和产品类型

了解Qbs在选择要执行的规则时的处理过程非常重要。Qbs从产品类型开始，然后寻找从源文件生成具有匹配文件标签的工件的方法。它是通过各自的输入和输出标签相互连接的规则链来实现的。例如，考虑以下简单的C++项目

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

以下是构建此产品的方式

1. Qbs寻找一个可以生成具有文件标签"application"的规则。此类规则在cpp模块中找到（即调用链接器的规则）。
2. 由于前一步中找到的规则接受"obj"类型的输入，因此Qbs现在寻找生成该类型工件的规则。同样，此类规则也位于cpp模块中（运行编译器的规则）。
3. 前一步中找到的规则接受"cpp"类型的输入。没有找到创建此类工件的规则，但我们有一个具有匹配类型的源文件（因为cpp模块包含一个FileTagger，它将此类型附加到"main.cpp"上，因为其文件扩展名）。
4. 现在有一系列规则链接从源文件标签到产品类型，这些规则的命令随后依次执行，直到我们得到可执行文件。

完整示例

以下代码片段展示了Product内部的单个Rule，并总结了前面的部分。

import qbs.TextFile

Product {
    type: "txt_output"

    Group {
        name: "lorem_ipsum"
        files: "lorem_ipsum.txt"
        fileTags: "txt_input"
    }

    Rule {
        multiplex: false
        inputs: ["txt_input"]
        Artifact {
            filePath: input.fileName + ".out"
            fileTags: ["txt_output"]
        }
        prepare: {
            var cmd = new JavaScriptCommand();
            cmd.description = "generating" + output.fileName + " from " + input.fileName;
            cmd.highlight = "codegen";
            cmd.sourceCode = function() {
                var file = new TextFile(input.filePath);
                var content = file.readAll();
                file.close()
                content = content.toUpperCase();
                file = new TextFile(output.filePath, TextFile.WriteOnly);
                file.write(content);
                file.close();
            }
            return [cmd];
        }
    }
}

属性文档

Depends {
    name: "foo"
}

outputArtifacts: [{
    filePath: "myfile.cpp",
    fileTags: ["cpp"],
    cpp: { cxxLanguageVersion: "c++11" }
}]

属性选项 扫描器