Add additional build documentation

denis-shienkov · Oct 22, 2020 · 87e564a · 87e564a
1 parent b304856
commit 87e564a
Show file tree

Hide file tree

Showing 12 changed files with 81 additions and 2 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -22,6 +22,10 @@ QBS is an extension designed to make it easy to work with QBS-based projects.
 [Build](build.md)
 * [Select a project](build.md#select-a-project)
 * [Resolve a project](build.md#resolve-a-project)
+* [Configure a project](build.md#configure-a-project)
+* [Build a project](build.md#build-a-project)
+* [Clean a project](build.md#clean-a-project)
+* [Watch for output](build.md#watch-for-output)
 
 [Debug and run](debug-run.md)
 * [Configure debuggers](debug-run.md#configure-debuggers)

diff --git a/docs/build.md b/docs/build.md
@@ -44,7 +44,7 @@ or press the **Click to Select the Active Project** button in the status bar.
 When the project is selected, its name will be displayed in the
 corresponding button caption:
 
-![QBS active project](images/qbs-active-project-button.png)
+![QBS select active project button](images/qbs-select-active-project-button.png)
 
 ## Resolve a project
 
@@ -61,6 +61,81 @@ The user can start the resolving manually:
 
 * From the command palette in VS Code, run the **QBS: Resolve** command.
 
+## Configure a project
+
+The procedure for configuring a project is to select the desired
+`profile`, `configuration`, and `product` for building:
+
+* To select the build profile, from the VS Code command pallette
+run the **QBS: Select Build Profile** command, or press the
+**Click to Select the Build Profile** button in the status bar:
+
+![QBS select build profile button](images/qbs-select-profile-button.png)
+
+* To select the build configuration, from the VS Code command pallette
+run the **QBS: Select Build Configuration** command, or press the
+**Click to Select the Build Configuration** button in the status bar:
+
+![QBS select build configuration button](images/qbs-select-configuration-button.png)
+
+Currently only `release` and `debug` configurations are supported.
+
+* To select the build product, from the VS Code command pallette
+run the **QBS: Select Build Product** command, or press the
+**Click to Select the Product to Build** button in the status bar:
+
+![QBS select build product button](images/qbs-select-build-product-button.png)
+
+You can choose to build either one product or `[all]` products.
+
+When any of these properties change, QBS will automatically start
+auto-resolving the project again.
+
+The progress of this operation is displayed in the corresponding
+popup message:
+
+![QBS project resolving message](images/qbs-project-resolving-popup.png)
+
+## Build a project
+
+To build the project, from the VS Code command pallette run the
+**QBS: Build** command, or press the **Build** button in the status bar:
+
+![QBS build project button](images/qbs-build-project-button.png)
+
+The progress of this operation is displayed in the corresponding
+popup message:
+
+![QBS project building message](images/qbs-project-building-popup.png)
+
+## Clean a project
+
+To clean the build, from the VS Code command pallette run the
+**QBS: Clean** command.
+
+The progress of this operation is displayed in the corresponding
+popup message:
+
+![QBS project cleaning message](images/qbs-project-cleaning-popup.png)
+
+## Watch for output
+
+The progress of operations such as `resolving`, `building`, and
+`cleaning' is also displayed as text messages reported from QBS.
+
+The KBS extension provides two output panels for displaying
+these messages:
+
+* **QBS Compile Output** - displays the progress of the main build,
+cleanup and resolve processes:
+
+![QBS compile output pane](images/qbs-compile-output-pane.png)
+
+* **QBS Message Output** - displays the internal service QBS
+messages (e.g. comes from the JS engine of QBS):
+
+![QBS message output pane](images/qbs-message-output-pane.png)
+
 ## Next steps
 
 - Explore the [QBS documentation](README.md)
diff --git a/docs/images/qbs-build-project-button.png b/docs/images/qbs-build-project-button.png
diff --git a/docs/images/qbs-compile-output-pane.png b/docs/images/qbs-compile-output-pane.png
diff --git a/docs/images/qbs-message-output-pane.png b/docs/images/qbs-message-output-pane.png
diff --git a/docs/images/qbs-project-building-popup.png b/docs/images/qbs-project-building-popup.png
diff --git a/docs/images/qbs-project-cleaning-popup.png b/docs/images/qbs-project-cleaning-popup.png
diff --git a/docs/images/qbs-active-project-button.png → ...ages/qbs-select-active-project-button.png b/docs/images/qbs-active-project-button.png → ...ages/qbs-select-active-project-button.png
diff --git a/docs/images/qbs-select-build-product-button.png b/docs/images/qbs-select-build-product-button.png
diff --git a/docs/images/qbs-select-configuration-button.png b/docs/images/qbs-select-configuration-button.png
diff --git a/docs/images/qbs-select-profile-button.png b/docs/images/qbs-select-profile-button.png
diff --git a/package.nls.json b/package.nls.json
@@ -6,7 +6,7 @@
     "qbs-tools.command.qbs.stop.session.title": "Stop Session",
     "qbs-tools.command.qbs.select.project.title": "Select Project",
     "qbs-tools.command.qbs.select.profile.title": "Select Profile",
-    "qbs-tools.command.qbs.select.configuration.title": "Select Configuration",
+    "qbs-tools.command.qbs.select.configuration.title": "Select Build Configuration",
     "qbs-tools.command.qbs.select.build.title": "Select Build Product",
     "qbs-tools.command.qbs.select.run.title": "Select Run Product",
     "qbs-tools.command.qbs.select.debugger.title": "Select Debugger",