附录C：JSON API

此API是向IDE提供Qbs支持的推荐方式。它可以通过会话命令访问。

数据包格式

所有信息都是通过数据包交换的，这些数据包具有以下结构

packet = "qbsmsg:" <payload length> [<meta data>] <line feed> <payload>

首先是一个固定的字符串，用于标识数据包的开始，后面跟实际数据的字节数。之后，可能还有其他元数据。目前没有，但未来的扩展可能会添加一些。换行字符标记元数据部分的结尾，紧接着是负载，这是一个单个Base64编码的JSON对象。我们称此对象为消息。

消息

消息数据是UTF8编码的。

大多数消息要么是请求要么是响应。请求是通过会话的标准输入通道发送给Qbs的消息。响应是通过Qbs通过会话的标准输出通道发送的消息。每个响应始终对应一个特定的请求。每个请求（除退出请求外）都期望得到一个精确相应的响应。响应意味着请求的操作已经完成。至少，它包含有关操作是否成功的信息，并且通常包含针对相应请求的特定数据。

每个消息对象都有一个type属性，它是一个唯一的字符串，用于标识消息类型。

所有请求都会阻塞会话，包括同类型的其他请求。例如，如果客户端代码希望使用不同的参数重新启动项目的构建，它首先必须发送一个取消请求，等待当前构建任务的响应，然后才能请求另一个构建。唯一可以在处理请求的同时合法发送的消息是退出消息。

响应对象可能携带一个error属性，表示相应的操作已失败。如果没有此属性，则表示请求成功。error属性的格式在此处描述。

在本页的剩余部分，我们将描述所有可以发送到和从Qbs接收的消息的结构。属性表可能有一个标题为强制的列，其值表明相应的消息属性是否始终存在。如果缺少此列，则相应消息的所有属性都是强制性的，除非另有说明。

hello消息

此消息由Qbs在会话启动后精确发送一次。这是Qbs发出的唯一一个不是对请求的响应的消息。type属性的值是"hello"，其他属性如下

当API扩展时，例如通过添加新的消息或属性，api-level 的值会增加。

在进行与当前API不兼容的更改时，会增加 api-compat-level 的值。一个为 API 级别 n 编写的工具应该拒绝与 API 兼容级别大于 n 的 Qbs 版本一起工作，因为它无法保证正确的行为。除非绝对必要，这个值不会改变。

api-compat-level 的值总是小于或等于 api-level 的值。

解析项目

要指示 Qbs 从磁盘加载项目，发送类型为 resolve-project 的请求。其他属性包括：

environment 属性定义了解析项目时以及随后的 Qbs 操作所需使用的环境。

error-handling-mode 指定了 Qbs 如何处理项目文件中存在的问题，例如分配未知属性。可能的值是 "strict" 和 "relaxed"。在严格模式下，Qbs 将立即中止，并根据各种错误设置回复的 error 属性。在宽松模式下，如果可能的话，Qbs 将继续解析项目。对于遇到的每个错误都会发出一个警告消息，并且不会设置回复的 error 属性。默认错误处理模式是 "strict"。

如果 log-time 属性为 true，则 Qbs 将发出包含有关操作哪个部分花费了多长时间的信息的 日志数据 消息。

module-properties 属性列出了应包含在回复消息中发送的 产品数据 中的模块属性名称。例如，如果要解析的项目是基于 C++ 的，并且客户端代码对代码使用的 C++ 版本感兴趣，则 module-properties 将包含 "cpp.cxxLanguageVersion"。

overridden-properties 属性用于覆盖模块、产品或项目属性的值。指定键的可能方法在此处描述。

《restore-behavior》属性指定是否以及如何使用现有的构建图。值 "restore-only" 表示应从磁盘加载构建图并直接使用。在此模式下，如果构建图文件不存在，则为错误。值 "resolve-only" 表示应从头开始解析项目，并忽略现有的构建图。在此模式下，如果不存在 "project-file-path" 属性，则为错误。默认值是 "restore-and-track-changes"，如果可能，则使用现有的构建图，并且如果没有找到构建图或参数与项目上次解析时使用的参数不同，则重新解析项目。

《top-level-profile》属性指定用于解析项目的 Qbs 配置文件。它对应于使用 resolve 命令时的 profile 键。

所有其他属性对应于 resolve 命令的命令行选项，它们的语义在文档中已描述。

当项目被解析后，Qbs 将回复一个 project-resolved 消息。可能的属性包括：

当操作失败时，存在 error-info 属性。当请求的 data-mode 属性所述的条件得到满足时，存在 project-data 属性。

所有其他与项目相关的请求都需要一个已解析的项目来操作。如果没有，它们将失败。

每个会话最多只有一个解析过的项目。如果客户端代码想要打开多个项目或以不同的配置打开一个项目，它需要启动额外的会话。

构建项目

要构建项目，发送一个类型为 build-project 的请求。以下列出其他属性，它们都不是必需的：

除了 install 以外的所有布尔属性默认为 false。

《active-file-tags》和《files-to-consider》用于将构建限制在某些输出标签和/或源文件。例如，如果只构建 C/C++ 对象文件，则《active-file-tags》应设为 "obj"。

《job-limits》数组中的对象包含一个字符串属性 pool 和一个整型属性 limit。

如果 log-time 属性为 true，则 Qbs 将发出包含有关操作哪个部分花费了多长时间的信息的 日志数据 消息。

如果《products》是一个数组，则它的元素必须对应于先前检索到的 ProductData 的 full-display-name 属性，并且只会构建这些产品。如果《products》是字符串 "all"，则构建项目中的所有产品。如果《products》不存在，则跳过其《builtByDefault》属性为 false 的产品。

《module-properties》属性的含义与 resolve-project 请求中相同。

所有其他属性对应于 build 命令的选项。

构建完成后，Qbs 将回复一个 project-built 消息。可能的属性包括：

当操作失败时，存在 error-info 属性。当请求的 data-mode 属性所述的条件得到满足时，存在 project-data 属性。

除非 command-echo-mode 值为 "silent"，否则将为要执行的每个命令发出类型为 command-description 的消息。它包含两个字符串属性 highlight 和 message，其中 message 是要向用户展示的消息，而 highlight 是关于如何显示消息的提示。它与同名属性 Command 相对应。

对于已完成的进程命令，可能会发出类型为 process-result 的消息。其他属性包括

error 字符串是以下之一："failed-to-start"、"crashed"、"timed-out"、"write-error"、"read-error" 和 "unknown-error"。除非 success 为 false，否则其值没有意义。

stdout 和 stderr 属性分别描述进程的标准输出和标准错误输出，分割成行。

如果进程在无错误且退出代码为零的情况下完成，则 success 属性为 true。

其他属性描述了实际执行的精确命令。

只有在进程失败或向其中一个输出通道打印数据的情况下，才会发出此消息。

清理项目

要删除项目的构建工件，发送类型为 clean-project 的请求。其他属性包括

products 数组的元素对应于 ProductData 的 full-display-name。如果此属性存在，则仅删除相应产品的工件。

如果 log-time 属性为 true，则 Qbs 将发出包含有关操作哪个部分花费了多长时间的信息的 日志数据 消息。

所有其他属性对应于 clean 命令的选项。

这些属性中没有任何一个是强制性的。

删除所有工件后，Qbs 返回一个 project-cleaned 消息。如果操作成功，则此消息没有任何属性。否则，类型为 ErrorInfo 的属性 error 指示出了什么问题。

安装项目

安装通常是 build 过程的一部分。要在单独的步骤中进行，在构建时将 install 属性设置为 false，并发送专用 install-project 消息。其他属性包括

products 数组的元素对应于 ProductData 的 full-display-name。如果此属性存在，则仅安装相应产品的工件。

如果 log-time 属性为 true，则 Qbs 将发出包含有关操作哪个部分花费了多长时间的信息的 日志数据 消息。

如果 use-sysroot 属性为 true 且 install-root 不存在，则安装根将为 qbs.sysroot。

所有其他属性对应于 install 命令的选项。

这些属性中没有任何一个是强制性的。

取消操作

可以使用 cancel-job 请求中止可能运行时间较长的操作。此消息没有任何属性。没有专用的回复消息；相反，将发送与当前运行的操作关联的通常回复，并将 error 属性设置为指示已取消。

如果没有正在进行中的操作，此请求将没有任何效果。特别是，如果它在其应该取消的操作已经完成后到达（即存在竞争条件），客户端代码收到的回复将不包含与取消相关的错误。

添加和删除源文件

可以使用add-files和remove-files消息分别将源文件添加到和从Qbs项目文件中删除。这两个请求具有相同的属性集

files属性指定应添加或删除哪些文件。

product属性对应于ProductData的full-display-name，并指定将操作应用于哪个产品。

group属性对应于GroupData的name，并指定将操作应用于产品中的哪个组。

操作完成后，Qbs将分别回复files-added和files-removed消息。同样，属性是相同的

如果存在error属性，则操作至少部分失败，并且failed-files将列出无法添加或删除的文件。

get-run-environment消息

此请求检索特定可执行产品的完整运行环境，同时考虑产品引入的所有模块的setupRunEnvironment脚本。属性如下

base-environment属性定义了应将Qbs特定值合并的环境中。

config属性对应于run命令的--setup-run-env-config选项。

product属性指定要检索环境的产物。值必须与项目中的某个ProductData的full-display-name相对应。

Qbs将回复run-environment消息。在失败的情况下，它将包含一个类型为ErrorInfo的属性error，否则它将包含类型为Environment的属性full-environment。

get-generated-files-for-sources消息

此请求允许客户端代码检索有关从给定源文件生成哪些工件的信息。它的唯一属性是一个列表products，其元素是具有以下两个属性的表示对象

full-display-name

requests

source-file属性指定产品中的源文件。

tags属性限制了要匹配的生成文件的潜在文件标签。这在源文件作为多个规则或规则生成多种类型输出之一输入时相关。

如果 recursive 属性设置为 true，则也将返回从源文件间接生成的文件。默认值为 false。例如，如果此属性用于 C++ 源文件，除了对象文件，最终的链接目标（例如库或可执行应用程序）也将返回。

Qbs 会回复一个 generated-files-for-sources 消息，其结构与请求类似。它还有一个名为 products 的对象列表属性，其元素由一个 full-display-name 字符串属性和一个 results 对象列表属性组成。这些对象的属性是

source-file 属性对应于请求中同名的条目，而 generated-files 是由 Qbs 规则生成的文件，这些规则以源文件为输入，并考虑了请求中指定的约束。

如果列表为空则不会列出。类似地，若 results 列表为空的产品也将被省略。

关闭项目

项目通过 release-project 消息关闭。此请求没有属性。

Qbs 会回复一个 project-released 消息。如果未打开任何项目，则回复将包含一个类型为 ErrorInfo 的 error 属性。

关闭会话

要关闭会话，请发送一个 quit 消息。此请求没有属性。

Qbs 会取消所有当前正在进行的操作，然后关闭自己。不会发送回复。

进度消息

当处理请求时，Qbs 可能会发出进度信息，以便客户端代码可以显示进度条。

task-started 消息

这是特定请求的第一个进度消息。它最多出现一次。它包含一个字符串属性 description，其值可以显示给用户，还有一个整数属性 max-progress，用于指示哪个进度值对应于 100%。

task-progress 消息

此消息通过一个整数属性 progress 更新进度。

new-max-progress 消息

如果需要更正原始估计的最大进度，则会发出此消息。其整数属性 max-progress 更新先前 task-started 消息中的值。

用户信息消息

有两种类型的消息纯粹包含要呈现给用户的信息。

log-data 消息

此对象有一个字符串属性 message，它是要向用户显示的文本。

warning 消息

此消息有一个类型为 ErrorInfo 的 warning 属性。

协议错误消息protocol-error

Qbs会将该消息作为对未知type请求的响应。它包含一个类型为ErrorInfo的error属性。

项目数据

如果请求可以更改构建图数据，相关响应可能包含一个值类型为TopLevelProjectData的project-data属性。

TopLevelProjectData

此数据类型表示整个项目。它具有与PlainProjectData相同的属性。如果它是project-resolved消息的一部分，也包含这些附加属性。

build-directory的值是顶级构建目录。

build-graph-file-path的值是构建图文件的路径。

build-system-files的值包含所有Qbs项目文件，包括模块和JavaScript助手文件。

overridden-properties的值是在项目上一次解析时传递的。

profile-data属性将项目中使用的配置文件名称映射到相应的属性映射。除非使用配置文件多路复用，否则此对象将正好包含一个属性。

PlainProjectData

此数据类型描述了一个项目项。属性如下

is-enabled属性对应于项目的条件。

location属性是相应的项目项在Qbs项目文件中的确切位置。

products和sub-projects是项目通过其引用属性拉取的内容。

ProductData

此数据类型描述了一个产品项。属性如下

dependencies数组元素对应于通过Depends项拉入的产品product-data的完整显示名称属性。

generated-artifacts是由该产品中的rules创建的文件。

groups列表对应于该产品中的group项。此外，为产品本身的files属性创建一个“伪组”。其名称与产品相同。

is-enabled属性对应于产品的条件。如果产品包含错误，并且Qbs在项目解析时被告知要以宽松模式运行，则产品也可能被禁用。

is-multiplexed 属性为 true，当且仅当产品在一个或多个属性上 复用。

is-runnable 属性指示产品的一个目标工件是否是可执行文件。在这种情况下，文件可通过 target-executable 属性访问。

location 属性是 Qbs 项目文件中对应 Product 项定义的确切位置。

module-properties 对象提供了当项目 解析 时请求的模块属性值。

name 属性是在 Product 项 中给出的值，而 full-display-name 是在整个项目（即使在复用的情况下）中唯一标识产品的名称。在没有复用的情况下，它与 name 相同。在两种情况下，它都适用于向用户展示。

请参阅 Product 项文档以获取其他属性的描述。

GroupData

此数据类型描述了一个 Group 项。属性包括

is-enabled 属性对应于组的 条件。然而，如果组的 产品被禁用，则此属性始终为 false。

location 属性是 Qbs 项目文件中对应的 Group 项出现的确切位置。

module-properties 对象提供了当项目 解析 时请求的模块属性值。如果没有在组级设置模块属性且其值与组的产品的值相同，则此属性被省略。

source-artifacts 列表对应于组 files 属性中列出的文件。

source-artifacts-from-wildcards 列表表示从组 files 属性中的通配符条目扩展的文件。

请参阅 Group 项文档以获取其他属性的描述。

ArtifactData

此数据类型代表项目中的文件，无论作为源还是作为规则的输出。另一方面，Qbs 项目文件不是工件。属性包括

install-data 属性是一个对象，其 is-installable 属性指示工件是否可安装。如果是这样，那么 FilePath 属性 install-file-path 和 install-root 提供进一步信息。

is-target 属性为 true，如果工件是该产品的目标工件，即 is-generated 为 true 且 file-tags 与 产品类型 相交。

module-properties 对象提供了当项目 解析 时请求的模块属性值。此属性仅对生成的工件存在。对于源工件，可以从它们的 group 中检索值。

其他属性应该很容易理解。

模块属性数据

此数据类型将完全限定的模块属性名称映射到它们相应的值。

其他自定义数据类型

存在多种自定义数据类型，这些类型是各种消息的构建块。以下是它们的描述。

FilePath

FilePath 是描述文件或目录的字符串。FilePath 总是绝对路径，并在路径分隔符中使用正斜杠，无论目标操作系统如何。

Location

Location 是一个表示文件路径以及在相应文件中的位置的（可选）位置的对象。它由以下属性组成

ErrorInfo

ErrorInfo 是一个表示错误信息的对象。它的唯一属性 items 是具有以下结构的对象数组

DataMode

这是 resolve 或 build 请求中 data-mode 属性的类型。它用于指示在哪些情况下回复消息应包括项目数据。可能值具有字符串类型，如下所示

• "never"：不要将项目数据附加到回复。
• "always"：应将项目数据附加到回复。
• "only-if-changed"：只有在与当前项目数据不同时才将项目数据附加到回复。

默认值是 "never"。

LogLevel

这是各种请求中可能出现的 log-level 属性类型。它用于指示客户端是否希望接收到 log-data 和/或 warning 消息。可能值具有字符串类型，如下所示

• "error"：不要记录任何内容。
• "warning"：Qbs 可能会发出 警告，但不会发出 log-data 消息。
• "info"：除了警告外，Qbs 还可能发出信息 log-data 消息。
• "debug"：Qbs 可能会发出调试输出。不会生成消息；相反，将使用标准错误输出通道。

默认值是 "info"。

Environment

此数据类型描述一组环境变量。它是一个对象，其键是环境变量的名称，其值是这些环境变量的值。