Add VSCode Tasks and documentation

Author: opajonk

.devcontainer/prepare_workspace.sh

@@ -17,6 +17,6 @@ GITA_PROJECT_HOME=$(pwd)/.gita
 mkdir -p "$GITA_PROJECT_HOME"
 export GITA_PROJECT_HOME
 
-# Generate a few workspace metadata files from known_good.json:
+# Generate workspace metadata files from known_good.json:
 # - .gita-workspace.csv
 python3 tools/known_good_to_workspace_metadata.py --known-good known_good.json --gita-workspace .gita-workspace.csv

.vscode/tasks.json

@@ -0,0 +1,47 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Update workspace metadata from known good",
+      "type": "shell",
+      "command": "python3",
+      "args": [
+        "tools/known_good_to_workspace_metadata.py"
+      ],
+      "problemMatcher": []
+    },
+    {
+      "label": "Switch Bazel modules to local_path_overrides",
+      "type": "shell",
+      "command": "python3",
+      "args": [
+        "tools/update_module_from_known_good.py",
+        "--override-type",
+        "local_path"
+      ],
+      "problemMatcher": []
+    },
+    {
+      "label": "Switch Bazel modules to git_overrides",
+      "type": "shell",
+      "command": "python3",
+      "args": [
+        "tools/update_module_from_known_good.py",
+        "--override-type",
+        "git"
+      ]
+    },
+    {
+      "label": "Gita: Generate workspace",
+      "type": "shell",
+      "command": "gita",
+      "args": [
+        "clone",
+        "--preserve-path",
+        "--from-file",
+        ".gita-workspace.csv"
+      ],
+      "problemMatcher": []
+    }
+  ]
+}

README.md

@@ -57,6 +57,38 @@ Execute `bazel query //feature_showcase/...` to obtain list of targets that You
 bazel build --config bl-x86_64-linux @score_orchestrator//src/... --verbose_failures
 ```
 
+## Workspace support
+
+You can obtain a complete S-CORE workspace, i.e. a git checkout of all modules from `known_good.json`, on the specific branches / commits, integrated into one Bazel build.
+This helps with cross-module development, debugging, and generally "trying out things".
+The startup of the supplied devcontainer already generates the required metadata.
+
+The supported workspace managers are:
+
+| Name | Description |
+|------|-------------|
+| [Gita](https://github.com/nosarthur/gita) | "a command-line tool to manage multiple git repos" |
+
+A description of how to use these workspace managers, together with their advantages and drawbacks, is beyond the scope of this document.
+In case of doubt, choose the first.
+
+### Initialization of the workspace
+
+> [!WARNING]
+> This will change the file `score_modules.MODULE.bazel`.
+> Do **not** commit these changes!
+
+1. Switch to local path overrides, using the VSCode Task (`Terminal`->`Run Task...`) "Switch Bazel modules to `local_path_overrides`".
+   Note that you can switch back to `git_overrides` (the default) using the task "Switch Bazel modules to `git_overrides`"
+   
+2. Run VSCode Task "<Name>: Generate workspace", e.g. "Gita: Generate workspace".
+   This will clone all modules using the chosen workspace manager.
+   The modules will be in sub-directories starting with `score_`.
+   Note that the usage of different workspace managers is mutually exclusive.
+
+When you now run Bazel, it will use the local working copies of all modules and not download them from git remotes.
+You can make local changes to each module, which will be directly reflected in the next Bazel run.
+
 ## Known Issues ⚠️
 
 ### Orchestrator