diff options
author | Christian Kandeler <christian.kandeler@qt.io> | 2019-03-18 15:02:53 +0100 |
---|---|---|
committer | Christian Kandeler <christian.kandeler@qt.io> | 2019-09-18 15:07:54 +0000 |
commit | 9f3a9830162f379d6f856c84668c3664df6d6477 (patch) | |
tree | b32a126840ca81a0881e71051f5c09443ede5a05 /doc | |
parent | 41d8b09239ce0ace2fd8674aaecae1528b1985e4 (diff) | |
download | qbs-9f3a9830162f379d6f856c84668c3664df6d6477.tar.gz |
Introduce the session command
Offers a JSON-based API for interaction with other tools via stdin/
stdout.
This allows for proper qbs support in IDEs that do not use Qt or even
C++.
Change-Id: Ib051a40b7ebe1c6e0c3147cca9bd96e7daec1fde
Reviewed-by: Jörg Bornemann <joerg.bornemann@qt.io>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/appendix/json-api.qdoc | 817 | ||||
-rw-r--r-- | doc/appendix/qbs-porting.qdoc | 2 | ||||
-rw-r--r-- | doc/config/style/qt5-sidebar.html | 3 | ||||
-rw-r--r-- | doc/doc.qbs | 1 | ||||
-rw-r--r-- | doc/qbs.qdoc | 7 | ||||
-rw-r--r-- | doc/reference/cli/builtin/cli-session.qdoc | 54 | ||||
-rw-r--r-- | doc/reference/cli/cli-options.qdocinc | 1 |
7 files changed, 880 insertions, 5 deletions
diff --git a/doc/appendix/json-api.qdoc b/doc/appendix/json-api.qdoc new file mode 100644 index 000000000..f8840de37 --- /dev/null +++ b/doc/appendix/json-api.qdoc @@ -0,0 +1,817 @@ +/**************************************************************************** +** +** Copyright (C) 2019 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 index.html + \previouspage porting-to-qbs.html + \nextpage attributions.html + \page json-api.html + + \title Appendix C: The JSON API + + This API is the recommended way to provide \QBS support to an IDE. + It is accessible via the \l{session} command. + + \section1 Packet Format + + All information is exchanged via \e packets, which have the following + structure: + \code + packet = "qbsmsg:" <payload length> [<meta data>] <line feed> <payload> + \endcode + 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 \e message. + + \section1 Messages + + The message data is UTF8-encoded. + + Most messages are either \e requests or \e 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 \l{quit-message}{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 \c 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 + \l{cancel-message}{cancel} request, wait for the current build job's reply, + and only then can it request another build. The only other message beside + \l{cancel-message}{cancel} that can legally be sent while a request + is currently being handled is the \l{quit-message}{quit} message. + + A reply object may carry an \c error property, indicating that the respective + operation has failed. If this property is not present, the request was successful. + The format of the \c error property is described \l{ErrorInfo}{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 \e 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. + + \section1 The \c 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 \c type property is \c "hello", the other properties are + as follows: + \table + \header \li Property \li Type + \row \li api-level \li int + \row \li api-compat-level \li int + \endtable + + The value of \c api-level is increased whenever the API is extended, for instance + by adding new messages or properties. + + The value of \c api-compat-level is increased whenever incompatible changes + are being done to this API. A tool written for API level \c n should refuse + to work with a \QBS version with an API compatibility level greater than \c n, + because it cannot guarantee proper behavior. This value will not change unless + it is absolutely necessary. + + The value of \c api-compat-level is always less than or equal to the + value of \c api-level. + + \section1 Resolving a Project + + To instruct \QBS to load a project from disk, a request of type + \c resolve-project is sent. The other properties are: + \table + \header \li Property \li Type \li Mandatory + \row \li build-root \li \l FilePath \li yes + \row \li configuration-name \li string \li no + \row \li data-mode \li \l DataMode \li no + \row \li dry-run \li bool \li no + \row \li environment \li \l Environment \li no + \row \li error-handling-mode \li string \li no + \row \li fallback-provider-enabled \li bool \li no + \row \li force-probe-execution \li bool \li no + \row \li log-time \li bool \li no + \row \li log-level \li \l LogLevel \li no + \row \li module-properties \li list of strings \li no + \row \li overridden-properties \li object \li no + \row \li project-file-path \li FilePath \li if resolving from scratch + \row \li restore-behavior \li string \li no + \row \li settings-directory \li string \li no + \row \li top-level-profile \li string \li no + \row \li wait-lock-build-graph \li bool \li no + \endtable + + The \c environment property defines the environment to be used for resolving + the project, as well as for all subsequent \QBS operations on this project. + + The \c error-handling-mode specifies how \QBS should deal with issues + in project files, such as assigning to an unknown property. The possible + values are \c "strict" and \c "relaxed". In strict mode, \QBS will + immediately abort and set the reply's \c error property accordingly. + In relaxed mode, \QBS will continue to resolve the project if possible. + A \l{warning-message}{warning message} will be emitted for every error that + was encountered, and the reply's \c error property will \e not be set. + The default error handling mode is \c "strict". + + If the \c log-time property is \c true, then \QBS will emit \l log-data messages + containing information about which part of the operation took how much time. + + The \c module-properties property lists the names of the module properties + which should be contained in the \l{ProductData}{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 \c module-properties would contain \c{"cpp.cxxLanguageVersion"}. + + The \c overridden-properties property is used to override the values of + module, product or project properties. The possible ways to specify + keys are described \l{Overriding Property Values from the Command Line}{here}. + + The \c restore-behavior property specifies if and how to make use of + an existing build graph. The value \c "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 \c "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 \c "project-file-path" property is not present. + The default value is \c "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 \c top-level-profile property specifies which \QBS profile to use + for resolving the project. It corresponds to the \c profile key when + using the \l resolve command. + + All other properties correspond to command line options of the \l resolve + command, and their semantics are described there. + + When the project has been resolved, \QBS will reply with a \c project-resolved + message. The possible properties are: + \table + \header \li Property \li Type \li Mandatory + \row \li error \li \l ErrorInfo \li no + \row \li project-data \li \l TopLevelProjectData \li no + \endtable + + The \c error-info property is present if and only if the operation + failed. The \c project-data property is present if and only if + the conditions stated by the request's \c 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. + + \section1 Building a Project + + To build a project, a request of type \c build-project is sent. The other properties, + none of which are mandatory, are listed below: + \table + \header \li Property \li Type + \row \li active-file-tags \li string list + \row \li changed-files \li \l FilePath list + \row \li check-outputs \li bool + \row \li check-timestamps \li bool + \row \li clean-install-root \li bool + \row \li data-mode \li \l DataMode + \row \li dry-run \li bool + \row \li command-echo-mode \li string + \row \li enforce-project-job-limits \li bool + \row \li files-to-consider \li \l FilePath list + \row \li install \li bool + \row \li job-limits \li list of objects + \row \li keep-going \li bool + \row \li log-level \li \l LogLevel + \row \li log-time \li bool + \row \li max-job-count \li int + \row \li module-properties \li list of strings + \row \li products \li list of strings or \c "all" + \endtable + + All boolean properties except \c install default to \c false. + + The \c active-file-tags and \c 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 + \c active-file-tags would be set to \c "obj". + + The objects in a \c job-limits array consist of a string property \c pool + and an int property \c limit. + + If the \c log-time property is \c true, then \QBS will emit \l log-data messages + containing information about which part of the operation took how much time. + + If \c products is an array, the elements must correspond to the + \c full-display-name property of previously retrieved \l ProductData, + and only these products will get built. + If \c products is the string \c "all", then all products in the project will + get built. + If \c products is not present, then products whose + \l{Product::builtByDefault}{builtByDefault} property is \c false will + be skipped. + + The \c module-properties property has the same meaning as in the + \l{Resolving a Project}{resolve-project} request. + + All other properties correspond to options of the \l build command. + + When the build has finished, \QBS will reply with a \c project-built + message. The possible properties are: + \table + \header \li Property \li Type \li Mandatory + \row \li error \li \l ErrorInfo \li no + \row \li project-data \li \l TopLevelProjectData \li no + \endtable + + The \c error-info property is present if and only if the operation + failed. The \c project-data property is present if and only if + the conditions stated by the request's \c data-mode property + are fulfilled. + + Unless the \c command-echo-mode value is \c "silent", a message of type + \c command-description is emitted for every command to be executed. + It consists of two string properties \c highlight and \c message, + where \c message is the message to present to the user and \c highlight + is a hint on how to display the message. It corresponds to the + \l{Command and JavaScriptCommand}{Command} property of the same name. + + For finished process commands, a message of type \c process-result + might be emitted. The other properties are: + \table + \header \li Property \li Type + \row \li arguments \li list of strings + \row \li error \li string + \row \li executable-file-path \li \l FilePath + \row \li exit-code \li int + \row \li stderr \li list of strings + \row \li stdout \li list of strings + \row \li success \li bool + \row \li working-directory \li \l FilePath + \endtable + + The \c error string is one of \c "failed-to-start", \c "crashed", \c "timed-out", + \c "write-error", \c "read-error" and \c "unknown-error". + Its value is not meaningful unless \c success is \c false. + + The \c stdout and \c stderr properties describe the process's standard + output and standard error output, respectively, split into lines. + + The \c success property is \c 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. + + \section1 Cleaning a Project + + To remove a project's build artifacts, a request of type \c clean-project + is sent. The other properties are: + \table + \header \li Property \li Type + \row \li dry-run \li bool + \row \li keep-going \li bool + \row \li log-level \li \l LogLevel + \row \li log-time \li bool + \row \li products \li list of strings + \endtable + + The elements of the \c products array correspond to a \c full-display-name + of a \l ProductData. If this property is present, only the respective + products' artifacts are removed. + + If the \c log-time property is \c true, then \QBS will emit \l log-data messages + containing information about which part of the operation took how much time. + + All other properties correspond to options of the \l clean command. + + None of these properties are mandatory. + + After all artifacts have been removed, \QBS replies with a + \c project-cleaned message. If the operation was successful, this message + has no properties. Otherwise, a property \c error of type \l ErrorInfo + indicates what went wrong. + + \section1 Installing a Project + + Installing is normally part of the \l{Building a Project}{build} + process. To do it in a separate step, the \c install property + is set to \c false when building and a dedicated \c install-project + message is sent. The other properties are: + \table + \header \li Property \li Type + \row \li clean-install-root \li bool + \row \li dry-run \li bool + \row \li install-root \li \l FilePath + \row \li keep-going \li bool + \row \li log-level \li \l LogLevel + \row \li log-time \li bool + \row \li products \li list of strings + \row \li use-sysroot \li bool + \endtable + + The elements of the \c products array correspond to a \c full-display-name + of a \l ProductData. If this property is present, only the respective + products' artifacts are installed. + + If the \c log-time property is \c true, then \QBS will emit \l log-data messages + containing information about which part of the operation took how much time. + + If the \c use-sysroot property is \c true and \c install-root is not present, + then the install root will be \l{qbs::sysroot}{qbs.sysroot}. + + All other properties correspond to options of the \l install command. + + None of these properties are mandatory. + + \target cancel-message + \section1 Canceling an Operation + + Potentially long-running operations can be aborted using the \c 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 \c 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. + + \section1 Adding and Removing Source Files + + Source files can be added to and removed from \QBS project files with + the \c add-files and \c remove-files messages, respectively. These two + requests have the same set of properties: + \table + \header \li Property \li Type + \row \li files \li \l FilePath list + \row \li group \li string + \row \li product \li string + \endtable + + The \c files property specifies which files should be added or removed. + + The \c product property corresponds to the \c full-display-name of + a \l ProductData and specifies to which product to apply the operation. + + The \c group property corresponds to the \c name of a \l GroupData + and specifies to which group in the product to apply the operation. + + After the operation has finished, \QBS replies with a \c files-added + and \c files-removed message, respectively. Again, the properties are + the same: + \table + \header \li Property \li Type \li Mandatory + \row \li error \li \l ErrorInfo \li no + \row \li failed-files \li \l FilePath list \li no + \row \li project-data \li \l TopLevelProjectData \li no + \endtable + + If the \c error property is present, the operation has at least + partially failed and \c failed-files will list the files + that could not be added or removed. + + If the project data has changed as a result of the operation + (which it should unless the operation failed completely), then + the \c project-data property will contain the updated project data. + + \section1 The \c get-run-environment Message + + This request retrieves the full run environment for a specific + executable product, taking into account the + \l{Module::setupRunEnvironment}{setupRunEnvironment} scripts + of all modules pulled in by the product. The properties are as follows: + \table + \header \li Property \li Type \li Mandatory + \row \li base-environment \li \l Environment \li no + \row \li config \li list of strings \li no + \row \li product \li string \li yes + \endtable + + The \c base-environment property defines the environment into which + the \QBS-specific values should be merged. + + The \c config property corresponds to the \l{--setup-run-env-config} + option of the \l run command. + + The \c product property specifies the product whose environment to + retrieve. The value must correspond to the \c full-display-name + of some \l ProductData in the project. + + \QBS will reply with a \c run-environment message. In case of failure, + it will contain a property \c error of type \l ErrorInfo, otherwise + it will contain a property \c full-environment of type \l Environment. + + \section1 The \c 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 \c products, whose elements are objects + with the two properties \c full-display-name and \c requests. + The first identifies the product to which the requests apply, and + it must match the property of the same name in a \l ProductData + in the project. + The latter is a list of objects with the following properties: + \table + \header \li Property \li Type \li Mandatory + \row \li source-file \li \l FilePath \li yes + \row \li tags \li list of strings \li no + \row \li recursive \li bool \li no + \endtable + + The \c source-file property specifies a source file in the respective + product. + + The \c 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 \c recursive property is \c true, files indirectly generated + from the source file will also be returned. The default is \c 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 \c generated-files-for-sources message, whose + structure is similar to the request. It also has a single object list + property \c products, whose elements consist of a string property + \c full-display-name and an object list property \c results. + The properties of these objects are: + \table + \header \li Property \li Type + \row \li source-file \li \l FilePath + \row \li generated-files \li \l FilePath list + \endtable + + The \c source-file property corresponds to an entry of the same name + in the request, and the \c 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 \c results list would be empty + are also omitted. + + \note The results may be incomplete if the project has not been fully built. + + \section1 Closing a Project + + A project is closed with a \c release-project message. This request has + no properties. + + \QBS will reply with a \c project-released message. If no project was open, + the reply will contain an \c error property of type \l ErrorInfo. + + \target quit-message + \section1 Closing the Session + + To close the session, a \c 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. + + \section1 Progress Messages + + While a request is being handled, \QBS may emit progress information in order + to enable client code to display a progress bar. + + \target task-started + \section2 The \c 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 \c description, whose value can be displayed + to users, and an integer property \c max-progress that indicates which + progress value corresponds to 100 per cent. + + \target task-progress + \section2 The \c task-progress Message + + This message updates the progress via an integer property \c progress. + + \target new-max-progress + \section2 The \c new-max-progress Message + + This message is emitted if the original estimated maximum progress has + to be corrected. Its integer property \c max-progress updates the + value from a preceding \l task-started message. + + \section1 Messages for Users + + There are two types of messages that purely contain information to be + presented to users. + + \target log-data + \section2 The \c log-data Message + + This object has a string property \c message, which is the text to be + shown to the user. + + \target warning-message + \section2 The \c warning Message + + This message has a single property \c warning of type \l ErrorInfo. + + \section1 The \c protocol-error Message + + \QBS sends this message as a reply to a request with an unknown \c type. + It contains an \c error property of type \l ErrorInfo. + + \section1 Project Data + + If a request can alter the build graph data, the associated reply may contain + a \c project-data property whose value is of type \l TopLevelProjectData. + + \section2 TopLevelProjectData + + This data type represents the entire project. It has the same properties + as \l PlainProjectData. If it is part of a \c project-resolved message, + these additional properties are also present: + \table + \header \li Property \li Type + \row \li build-directory \li \l FilePath + \row \li build-graph-file-path \li \l FilePath + \row \li build-system-files \li \l FilePath list + \row \li overridden-properties \li object + \row \li profile-data \li object + \endtable + + The value of \c build-directory is the top-level build directory. + + The \c build-graph-file-path value is the path to the build graph file. + + The \c build-system-files value contains all \QBS project files, including + modules and JavaScript helper files. + + The value of \c overridden-properties is the one that was passed in when + the project was last \l{Resolving a Project}{resolved}. + + The \c 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. + + \section2 PlainProjectData + + This data type describes a \l Project item. The properties are as follows: + \table + \header \li Property \li Type + \row \li is-enabled \li bool + \row \li location \li \l FilePath + \row \li name \li string + \row \li products \li \l ProductData list + \row \li sub-projects \li \l PlainProjectData list + \endtable + + The \c is-enabled property corresponds to the project's + \l{Project::condition}{condition}. + + The \c location property is the exact position in a \QBS project file + where the corresponding \l Project item was defined. + + The \c products and \c sub-projects are what the project has pulled in via + its \l{Project::references}{references} property. + + \section2 ProductData + + This data type describes a \l Product item. The properties are as follows: + \table + \header \li Property \li Type + \row \li build-directory \li \l FilePath + \row \li dependencies \li list of strings + \row \li full-display-name \li string + \row \li generated-artifacts \li \l ArtifactData list + \row \li groups \li \l GroupData list + \row \li is-enabled \li bool + \row \li is-multiplexed \li bool + \row \li is-runnable \li bool + \row \li location \li \l Location + \row \li module-properties \li \l ModulePropertiesData + \row \li multiplex-configuration-id \li string + \row \li name \li string + \row \li properties \li object + \row \li target-executable \li \l FilePath + \row \li target-name \li string + \row \li type \li list of strings + \row \li version \li string + \endtable + + The \c dependencies are the names of products that occur in the (enabled) + \l Depends items of this product. + + The \c generated-artifacts are files that are created by the \l{Rule}{rules} + in this product. + + The \c groups list corresponds to the \l Group items in this product. + In addition, a "pseudo-group" is created for the \l{Product::files}{files} + property of the product itself. Its name is the same as the product's. + + The \c is-enabled property corresponds to the product's + \l{Product::condition}{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 \l{Resolving a Project}{resolved}. + + The \c is-multiplexed property is true if and only if the product is + \l{Multiplexing}{multiplexed} over one ore more properties. + + The \c 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 \c target-executable property. + + The \c location property is the exact position in a \QBS project file + where the corresponding \l Product item was defined. + + The \c module-properties object provides the values of the module properties + that were requested when the project was \l{Resolving a Project}{resolved}. + + The \c name property is the value given in the \l{Product::name}{Product item}, + whereas \c 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 \c name. In either case, + it is suitable for being presented to users. + + See the \l Product item documentation for a description of the other + properties. + + \section2 GroupData + + This data type describes a \l Group item. The properties are: + \table + \header \li Property \li Type + \row \li is-enabled \li bool + \row \li location \li \l Location + \row \li module-properties \li \l ModulePropertiesData + \row \li name \li string + \row \li prefix \li string + \row \li source-artifacts \li \l ArtifactData list + \row \li source-artifacts-from-wildcards \li \l ArtifactData list + \endtable + + The \c is-enabled property corresponds to the groups's + \l{Group::condition}{condition}. However, if the group's product + is disabled, this property will always be \c false. + + The \c location property is the exact position in a \QBS project file + where the corresponding \l Group item occurs. + + The \c module-properties object provides the values of the module properties + that were requested when the project was \l{Resolving a Project}{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 \c source-artifacts list corresponds the the files listed verbatim + in the group's \l{Group::files}{files} property. + + The \c source-artifacts-from-wildcards list represents the the files + expanded from wildcard entries in the group's \l{Group::files}{files} property. + + See the \l Group item documentation for a description of the other + properties. + + \section2 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: + \table + \header \li Property \li Type + \row \li file-path \li \l FilePath + \row \li file-tags \li list of strings + \row \li install-data \li object + \row \li is-executable \li bool + \row \li is-generated \li bool + \row \li is-target \li bool + \row \li module-properties \li \l ModulePropertiesData + \endtable + + The \c install-data property is an object whose \c is-installable property + indicates whether the artifact gets installed. If so, then the \l FilePath + properties \c install-file-path and \c install-root provide further + information. + + The \c is-target property is true if the artifact is a target artifact + of its product, that is, \c is-generated is true and \c file-tags + intersects with the \l{Product::type}{product type}. + + The \c module-properties object provides the values of the module properties + that were requested when the project was \l{Resolving a Project}{resolved}. + This property is only present for generated artifacts. For source artifacts, + the value can be retrieved from their \l{GroupData}{group}. + + The other properties should be self-explanatory. + + \section2 ModulePropertiesData + + This data type maps fully qualified module property names to their + respective values. + + \section1 Other Custom Data Types + + There are a number of custom data types that serve as building blocks in + various messages. They are described below. + + \section2 FilePath + + A \e 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. + + \section2 Location + + A \e Location is an object representing a file path and possibly also a position + within the respective file. It consists of the following properties: + \table + \header \li Property \li Type \li Mandatory + \row \li file-path \li \l FilePath \li yes + \row \li line \li int \li no + \row \li column \li int \li no + \endtable + + \section2 ErrorInfo + + An \e ErrorInfo is an object representing error information. Its sole property + \c items is an array of objects with the following structure: + \table + \header \li Property \li Type \li Mandatory + \row \li \c message \li string \li yes + \row \li location \li \l Location \li no + \endtable + + \section2 DataMode + + This is the type of the \c data-mode property in a + \l{Resolving a project}{resolve} or \l{Building a project}{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: + \list + \li \c "never": Do not attach project data to the reply. + \li \c "always": Do attach project data to the reply. + \li \c "only-if-changed": Attach project data to the reply only + if it is different from the current + project data. + \endlist + The default value is \c "never". + + \section2 LogLevel + + This is the type of the \c log-level property that can occur + in various requests. It is used to indicate whether the client would like + to receive \l log-data and/or \l{warning-message}{warning} messages. + The possible values have string type and are as follows: + \list + \li "error": Do not log anything. + \li "warning": \QBS may emit \l{warning-message}{warnings}, but no + \l log-data messages. + \li "info": In addition to warnings, \QBS may emit informational + \l log-data messages. + \li "debug": \QBS may emit debug output. No messages will be generated; + instead, the standard error output channel will be used. + \endlist + The default value is \c "info". + + \section2 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. + +*/ diff --git a/doc/appendix/qbs-porting.qdoc b/doc/appendix/qbs-porting.qdoc index e17d7b0ac..ba697d7be 100644 --- a/doc/appendix/qbs-porting.qdoc +++ b/doc/appendix/qbs-porting.qdoc @@ -29,7 +29,7 @@ \contentspage index.html \previouspage building-qbs.html \page porting-to-qbs.html - \nextpage attributions.html + \nextpage json-api.html \title Appendix B: Migrating from Other Build Systems diff --git a/doc/config/style/qt5-sidebar.html b/doc/config/style/qt5-sidebar.html index 99690bd01..3df5d1bbf 100644 --- a/doc/config/style/qt5-sidebar.html +++ b/doc/config/style/qt5-sidebar.html @@ -12,6 +12,7 @@ <li><a href="reference.html">Reference</a></li> <li><a href="building-qbs.html">Appendix A: Building Qbs</a></li> <li><a href="porting-to-qbs.html">Appendix B: Migrating from Other Build Systems</a></li> - <li><a href="attributions.html">Appendix C: Code Attributions</a></li> + <li><a href="json-api.html">Appendix C: The JSON API</a></li> + <li><a href="attributions.html">Appendix D: Code Attributions</a></li> </ul> </div> diff --git a/doc/doc.qbs b/doc/doc.qbs index 194d8e157..dd8377c6c 100644 --- a/doc/doc.qbs +++ b/doc/doc.qbs @@ -26,6 +26,7 @@ Project { "qbs-online.qdocconf", "config/*.qdocconf", "config/style/qt5-sidebar.html", + "appendix/**/*", "reference/**/*", "templates/**/*", "images/**", diff --git a/doc/qbs.qdoc b/doc/qbs.qdoc index 897f1a41b..08a901365 100644 --- a/doc/qbs.qdoc +++ b/doc/qbs.qdoc @@ -87,7 +87,8 @@ \li \l{Appendix A: Building Qbs} \li \l{Appendix B: Migrating from Other Build Systems} - \li \l{Appendix C: Licenses and Code Attributions} + \li \l{Appendix C: The JSON API} + \li \l{Appendix D: Licenses and Code Attributions} \endlist */ @@ -1966,10 +1967,10 @@ /*! \contentspage index.html - \previouspage porting-to-qbs.html + \previouspage json-api.html \page attributions.html - \title Appendix C: Licenses and Code Attributions + \title Appendix D: Licenses and Code Attributions \section1 Licenses diff --git a/doc/reference/cli/builtin/cli-session.qdoc b/doc/reference/cli/builtin/cli-session.qdoc new file mode 100644 index 000000000..62999a82e --- /dev/null +++ b/doc/reference/cli/builtin/cli-session.qdoc @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** Copyright (C) 2019 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 cli.html + \page cli-session.html + \ingroup cli + + \title session + \brief Starts a session for interacting with an IDE + + \section1 Synopsis + + \code + qbs session + \endcode + + \section1 Description + + Starts a session, communicating via standard input and standard output. + + In this mode, \QBS takes commands from standard input and sends replies + to standard output, using a \l{Appendix C: The JSON API}{JSON-based API}. + + This is the recommended \QBS interface for IDEs. It can be used to retrieve + information about a project and interact with it in various ways, such + as building it, collecting the list of executables, adding new source files + and so on. + +*/ diff --git a/doc/reference/cli/cli-options.qdocinc b/doc/reference/cli/cli-options.qdocinc index f609b1964..b02ce68ea 100644 --- a/doc/reference/cli/cli-options.qdocinc +++ b/doc/reference/cli/cli-options.qdocinc @@ -442,6 +442,7 @@ //! [setup-run-env-config] + \target --setup-run-env-config \section2 \c --setup-run-env-config A comma-separated list of strings. They will show up in the \c config |