Appendix C: The JSON API

This API is the recommended way to provide Qbs support to an IDE. It is accessible via the session command.

Packet Format

All information is exchanged via packets, which have the following structure:

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

First comes a fixed string indentifying the start of a packet, followed by the size of the actual data in bytes. After that, further meta data might follow. There is none currently, but future extensions might add some. A line feed character marks the end of the meta data section and is followed immediately by the payload, which is a single JSON object encoded in Base64 format. We call this object a message.

Messages

The message data is UTF8-encoded.

Most messages are either requests or replies. Requests are messages sent to Qbs via the session's standard input channel. Replies are messages sent by Qbs via the session's standard output channel. A reply always corresponds to one specific request. Every request (with the exception of the quit request) expects exactly one reply. A reply implies that the requested operation has finished. At the very least, it carries information about whether the operation succeeded, and often contains additional data specific to the respective request.

Every message object has a type property, which is a string that uniquely identifies the message type.

All requests block the session for other requests, including those of the same type. For instance, if client code wishes to restart building the project with different parameters, it first has to send a cancel request, wait for the current build job's reply, and only then can it request another build. The only other message beside cancel that can legally be sent while a request is currently being handled is the quit message.

A reply object may carry an error property, indicating that the respective operation has failed. If this property is not present, the request was successful. The format of the error property is described here.

In the remainder of this page, we describe the structure of all messages that can be sent to and received from Qbs, respectively. The property tables may have a column titled Mandatory, whose values indicate whether the respective message property is always present. If this column is missing, all properties of the respective message are mandatory, unless otherwise noted.

The hello Message

This message is sent by Qbs exactly once, right after the session was started. It is the only message from Qbs that is not a response to a request. The value of the type property is "hello", the other properties are as follows:

The value of api-level is increased whenever the API is extended, for instance by adding new messages or properties.

The value of api-compat-level is increased whenever incompatible changes are being done to this API. A tool written for API level n should refuse to work with a Qbs version with an API compatibility level greater than n, because it cannot guarantee proper behavior. This value will not change unless it is absolutely necessary.

The value of api-compat-level is always less than or equal to the value of api-level.

Resolving a Project

To instruct Qbs to load a project from disk, a request of type resolve-project is sent. The other properties are:

The environment property defines the environment to be used for resolving the project, as well as for all subsequent Qbs operations on this project.

The error-handling-mode specifies how Qbs should deal with issues in project files, such as assigning to an unknown property. The possible values are "strict" and "relaxed". In strict mode, Qbs will immediately abort and set the reply's error property accordingly. In relaxed mode, Qbs will continue to resolve the project if possible. A warning message will be emitted for every error that was encountered, and the reply's error property will not be set. The default error handling mode is "strict".

If the log-time property is true, then Qbs will emit log-data messages containing information about which part of the operation took how much time.

The module-properties property lists the names of the module properties which should be contained in the product data that will be sent in the reply message. For instance, if the project to be resolved is C++-based and the client code is interested in which C++ version the code uses, then module-properties would contain "cpp.cxxLanguageVersion".

The overridden-properties property is used to override the values of module, product or project properties. The possible ways to specify keys are described here.

The restore-behavior property specifies if and how to make use of an existing build graph. The value "restore-only" indicates that a build graph should be loaded from disk and used as-is. In this mode, it is an error if the build graph file does not exist. The value "resolve-only" indicates that the project should be resolved from scratch and that an existing build graph should be ignored. In this mode, it is an error if the "project-file-path" property is not present. The default value is "restore-and-track-changes", which uses an existing build graph if possible and re-resolves the project if no build graph was found or if the parameters are different from the ones used when the project was last resolved.

The top-level-profile property specifies which Qbs profile to use for resolving the project. It corresponds to the profile key when using the resolve command.

All other properties correspond to command line options of the resolve command, and their semantics are described there.

When the project has been resolved, Qbs will reply with a project-resolved message. The possible properties are:

The error-info property is present if and only if the operation failed. The project-data property is present if and only if the conditions stated by the request's data-mode property are fulfilled.

All other project-related requests need a resolved project to operate on. If there is none, they will fail.

There is at most one resolved project per session. If client code wants to open several projects or one project in different configurations, it needs to start additional sessions.

Building a Project

To build a project, a request of type build-project is sent. The other properties, none of which are mandatory, are listed below:

All boolean properties except install default to false.

The active-file-tags and files-to-consider are used to limit the build to certain output tags and/or source files. For instance, if only C/C++ object files should get built, then active-file-tags would be set to "obj".

The objects in a job-limits array consist of a string property pool and an int property limit.

If the log-time property is true, then Qbs will emit log-data messages containing information about which part of the operation took how much time.

If products is an array, the elements must correspond to the full-display-name property of previously retrieved ProductData, and only these products will get built. If products is the string "all", then all products in the project will get built. If products is not present, then products whose builtByDefault property is false will be skipped.

The module-properties property has the same meaning as in the resolve-project request.

All other properties correspond to options of the build command.

When the build has finished, Qbs will reply with a project-built message. The possible properties are:

The error-info property is present if and only if the operation failed. The project-data property is present if and only if the conditions stated by the request's data-mode property are fulfilled.

Unless the command-echo-mode value is "silent", a message of type command-description is emitted for every command to be executed. It consists of two string properties highlight and message, where message is the message to present to the user and highlight is a hint on how to display the message. It corresponds to the Command property of the same name.

For finished process commands, a message of type process-result might be emitted. The other properties are:

The error string is one of "failed-to-start", "crashed", "timed-out", "write-error", "read-error" and "unknown-error". Its value is not meaningful unless success is false.

The stdout and stderr properties describe the process's standard output and standard error output, respectively, split into lines.

The success property is true if the process finished without errors and an exit code of zero.

The other properties describe the exact command that was executed.

This message is only emitted if the process failed or it has printed data to one of the output channels.

Cleaning a Project

To remove a project's build artifacts, a request of type clean-project is sent. The other properties are:

The elements of the products array correspond to a full-display-name of a ProductData. If this property is present, only the respective products' artifacts are removed.

If the log-time property is true, then Qbs will emit log-data messages containing information about which part of the operation took how much time.

All other properties correspond to options of the clean command.

None of these properties are mandatory.

After all artifacts have been removed, Qbs replies with a project-cleaned message. If the operation was successful, this message has no properties. Otherwise, a property error of type ErrorInfo indicates what went wrong.

Installing a Project

Installing is normally part of the build process. To do it in a separate step, the install property is set to false when building and a dedicated install-project message is sent. The other properties are:

The elements of the products array correspond to a full-display-name of a ProductData. If this property is present, only the respective products' artifacts are installed.

If the log-time property is true, then Qbs will emit log-data messages containing information about which part of the operation took how much time.

If the use-sysroot property is true and install-root is not present, then the install root will be qbs.sysroot.

All other properties correspond to options of the install command.

None of these properties are mandatory.

Canceling an Operation

Potentially long-running operations can be aborted using the cancel-job request. This message does not have any properties. There is no dedicated reply message; instead, the usual reply for the request associated with the currently running operation will be sent, with the error property set to indicate that it was canceled.

If there is no operation in progress, this request will have no effect. In particular, if it arrives after the operation that it was supposed to cancel has already finished (i.e. there is a race condition), the reply received by client code will not contain a cancellation-related error.

Adding and Removing Source Files

Source files can be added to and removed from Qbs project files with the add-files and remove-files messages, respectively. These two requests have the same set of properties:

The files property specifies which files should be added or removed.

The product property corresponds to the full-display-name of a ProductData and specifies to which product to apply the operation.

The group property corresponds to the name of a GroupData and specifies to which group in the product to apply the operation.

After the operation has finished, Qbs replies with a files-added and files-removed message, respectively. Again, the properties are the same:

If the error property is present, the operation has at least partially failed and failed-files will list the files that could not be added or removed.

The get-run-environment Message

This request retrieves the full run environment for a specific executable product, taking into account the setupRunEnvironment scripts of all modules pulled in by the product. The properties are as follows:

The base-environment property defines the environment into which the Qbs-specific values should be merged.

The config property corresponds to the --setup-run-env-config option of the run command.

The product property specifies the product whose environment to retrieve. The value must correspond to the full-display-name of some ProductData in the project.

Qbs will reply with a run-environment message. In case of failure, it will contain a property error of type ErrorInfo, otherwise it will contain a property full-environment of type Environment.

The get-generated-files-for-sources Message

This request allows client code to retrieve information about which artifacts are generated from a given source file. Its sole property is a list products, whose elements are objects with the two properties full-display-name and requests. The first identifies the product to which the requests apply, and it must match the property of the same name in a ProductData in the project. The latter is a list of objects with the following properties:

The source-file property specifies a source file in the respective product.

The tags property constrains the possible file tags of the generated files to be matched. This is relevant if a source files serves as input to more than one rule or the rule generates more than one type of output.

If the recursive property is true, files indirectly generated from the source file will also be returned. The default is false. For instance, íf this property is enabled for a C++ source file, the final link target (e.g. a library or an application executable) will be returned in addition to the object file.

Qbs will reply with a generated-files-for-sources message, whose structure is similar to the request. It also has a single object list property products, whose elements consist of a string property full-display-name and an object list property results. The properties of these objects are:

The source-file property corresponds to an entry of the same name in the request, and the generated-files are the files which are generated by Qbs rules that take the source file as an input, taking the constraints specified in the request into account.

Source files for which the list would be empty are not listed. Similarly, products for which the results list would be empty are also omitted.

Closing a Project

A project is closed with a release-project message. This request has no properties.

Qbs will reply with a project-released message. If no project was open, the reply will contain an error property of type ErrorInfo.

Closing the Session

To close the session, a quit message is sent. This request has no properties.

Qbs will cancel all currently running operations and then close itself. No reply will be sent.

Progress Messages

While a request is being handled, Qbs may emit progress information in order to enable client code to display a progress bar.

The task-started Message

This is always the first progress-related message for a specific request. It appears at most once per request. It consists of a string property description, whose value can be displayed to users, and an integer property max-progress that indicates which progress value corresponds to 100 per cent.

The task-progress Message

This message updates the progress via an integer property progress.

The new-max-progress Message

This message is emitted if the original estimated maximum progress has to be corrected. Its integer property max-progress updates the value from a preceding task-started message.

Messages for Users

There are two types of messages that purely contain information to be presented to users.

The log-data Message

This object has a string property message, which is the text to be shown to the user.

The warning Message

This message has a single property warning of type ErrorInfo.

The protocol-error Message

Qbs sends this message as a reply to a request with an unknown type. It contains an error property of type ErrorInfo.

Project Data

If a request can alter the build graph data, the associated reply may contain a project-data property whose value is of type TopLevelProjectData.

TopLevelProjectData

This data type represents the entire project. It has the same properties as PlainProjectData. If it is part of a project-resolved message, these additional properties are also present:

The value of build-directory is the top-level build directory.

The build-graph-file-path value is the path to the build graph file.

The build-system-files value contains all Qbs project files, including modules and JavaScript helper files.

The value of overridden-properties is the one that was passed in when the project was last resolved.

The profile-data property maps the names of the profiles used in the project to the respective property maps. Unless profile multiplexing is used, this object will contain exactly one property.

PlainProjectData

This data type describes a Project item. The properties are as follows:

The is-enabled property corresponds to the project's condition.

The location property is the exact position in a Qbs project file where the corresponding Project item was defined.

The products and sub-projects are what the project has pulled in via its references property.

ProductData

This data type describes a Product item. The properties are as follows:

The elements of the dependencies array correspond to the full-display-name properties of the products that this product has pulled in via Depends items.

The generated-artifacts are files that are created by the rules in this product.

The groups list corresponds to the Group items in this product. In addition, a "pseudo-group" is created for the files property of the product itself. Its name is the same as the product's.

The is-enabled property corresponds to the product's condition. A product may also get disabled if it contains errors and Qbs was was instructed to operate in relaxed mode when the project was resolved.

The is-multiplexed property is true if and only if the product is multiplexed over one ore more properties.

The is-runnable property indicates whether one of the product's target artifacts is an executable file. In that case, the file is available via the target-executable property.

The location property is the exact position in a Qbs project file where the corresponding Product item was defined.

The module-properties object provides the values of the module properties that were requested when the project was resolved.

The name property is the value given in the Product item, whereas full-display-name is a name that uniquely identifies the product in the entire project, even in the presence of multiplexing. In the absence of multiplexing, it is the same as name. In either case, it is suitable for being presented to users.

See the Product item documentation for a description of the other properties.

GroupData

This data type describes a Group item. The properties are:

The is-enabled property corresponds to the groups's condition. However, if the group's product is disabled, this property will always be false.

The location property is the exact position in a Qbs project file where the corresponding Group item occurs.

The module-properties object provides the values of the module properties that were requested when the project was resolved. If no module properties are set on the Group level and the value would therefore be the same as in the group's product, then this property is omitted.

The source-artifacts list corresponds the the files listed verbatim in the group's files property.

The source-artifacts-from-wildcards list represents the the files expanded from wildcard entries in the group's files property.

See the Group item documentation for a description of the other properties.

ArtifactData

This data type represents files that occur in the project, either as sources or as outputs of a rules. Qbs project files, on the other hand, are not artifacts. The properties are:

The install-data property is an object whose is-installable property indicates whether the artifact gets installed. If so, then the FilePath properties install-file-path and install-root provide further information.

The is-target property is true if the artifact is a target artifact of its product, that is, is-generated is true and file-tags intersects with the product type.

The module-properties object provides the values of the module properties that were requested when the project was resolved. This property is only present for generated artifacts. For source artifacts, the value can be retrieved from their group.

The other properties should be self-explanatory.

ModulePropertiesData

This data type maps fully qualified module property names to their respective values.

Other Custom Data Types

There are a number of custom data types that serve as building blocks in various messages. They are described below.

FilePath

A FilePath is a string that describes a file or directory. FilePaths are always absolute and use forward slashes for separators, regardless of the host operating system.

Location

A Location is an object representing a file path and possibly also a position within the respective file. It consists of the following properties:

ErrorInfo

An ErrorInfo is an object representing error information. Its sole property items is an array of objects with the following structure:

DataMode

This is the type of the data-mode property in a resolve or build request. It is used to indicate under which circumstances the reply message should include the project data. The possible values have string type and are as follows:

• "never": Do not attach project data to the reply.
• "always": Do attach project data to the reply.
• "only-if-changed": Attach project data to the reply only if it is different from the current project data.

The default value is "never".

LogLevel

This is the type of the log-level property that can occur in various requests. It is used to indicate whether the client would like to receive log-data and/or warning messages. The possible values have string type and are as follows:

• "error": Do not log anything.
• "warning": Qbs may emit warnings, but no log-data messages.
• "info": In addition to warnings, Qbs may emit informational log-data messages.
• "debug": Qbs may emit debug output. No messages will be generated; instead, the standard error output channel will be used.

The default value is "info".

Environment

This data type describes a set of environment variables. It is an object whose keys are names of environment variables and whose values are the values of these environment variables.