Add Go + Angular code debugging instructions.eel_5.0.1eel/5.0.15.0.1

Signed-off-by: Sebastien Douheret <sebastien.douheret@iot.bzh>

4 files changed, 159 insertions, 49 deletions

diff --git a/docs/part-2/1_xds-server/4_debug.md b/docs/part-2/1_xds-server/4_debug.md
index 2b36697..dbd6dfd 100644
--- a/docs/part-2/1_xds-server/4_debug.md
+++ b/docs/part-2/1_xds-server/4_debug.md
@@ -20,7 +20,7 @@ The server part is written in *Go* and web app (basic HTML) in *Angular4*.
 |
 +-- Makefile            # makefile including
 |
-+-- README.md           #
++-- README.md           # readme
 |
 +-- scripts/            # hold various scripts used for installation or startup
 |
@@ -33,4 +33,14 @@ The server part is written in *Go* and web app (basic HTML) in *Angular4*.
 +-- webapp/             # source client basic web application
 ```
 
+## Debug server part (Go code)
+
+Install first [Visual Studio Code](https://code.visualstudio.com/) and
+[Go plugin](https://marketplace.visualstudio.com/items?itemName=lukehoban.Go)
+(`ext install lukehoban.Go`)
+
 Visual Studio Code launcher settings can be found into `.vscode/launch.json`.
+
+Please follow instructions of xds-agent [debugging chapter](../2_xds-agent/4_debug.html#debug-xds-agent-go-code),
+knowing that you execute these same instructions in `xds-server` repo, in other words
+by replacing *xds-agent* references by *xds-server*.
diff --git a/docs/part-2/2_xds-agent/4_debug.md b/docs/part-2/2_xds-agent/4_debug.md
index 9490c4b..a84c0bc 100644
--- a/docs/part-2/2_xds-agent/4_debug.md
+++ b/docs/part-2/2_xds-agent/4_debug.md
@@ -18,7 +18,7 @@ The agent part is written in *Go* and the webapp / dashboard is in *typescript +
 |
 +-- Makefile            makefile including
 |
-+-- README.md           this readme
++-- README.md           readme
 |
 +-- scripts/            hold various scripts used for installation or startup
 |
@@ -29,41 +29,102 @@ The agent part is written in *Go* and the webapp / dashboard is in *typescript +
 +-- webapp/             source client basic webapp / dashboard
 ```
 
-## Debug
+## Debug xds-agent (Go code)
+
+Install first [Visual Studio Code](https://code.visualstudio.com/) and
+[Go plugin](https://marketplace.visualstudio.com/items?itemName=lukehoban.Go)
+(`ext install lukehoban.Go`)
 
 Visual Studio Code launcher settings can be found into `.vscode/launch.json`.
+The important think is to correctly set `GOPATH` in launch.json in order to
+build xds-agent and debug it within Visual Studio Code.
+
+Here is an example of launch.json:
+
+```json
+{
+    "version": "0.2.0",
+    "configurations": [{
+            "name": "XDS-Agent",
+            "type": "go",
+            "request": "launch",
+            "mode": "debug",
+            "remotePath": "",
+            "port": 2345,
+            "host": "127.0.0.1",
+            "program": "${workspaceRoot}",
+            "env": {
+                "GOPATH": "${workspaceRoot}/../../../../../..:${env:GOPATH}",
+            },
+            "args": ["-log", "debug", "-c", "__agent-config_local_dev.json"],
+            "showLog": false
+        }
+    ]
+}
+```
+
+And `__agent-config_local_dev.json` file content is as follow :
+
+```json
+{
+    "webAppDir": "./webapp/dist",
+    "logsDir": "${HOME}/tmp/xds-agent/logs",
+    "xdsServers": [
+        {
+          "url": "http://localhost:8000"
+        }
+    ],
+    "syncthing": {
+        "binDir": "./bin",
+        "home": "${HOME}/tmp/xds_local_dev/syncthing-config",
+        "gui-address": "http://localhost:8386",
+    }
+}
+```
+
+### Tricks to debug both xds-agent and xds-server
 
->**Tricks:**
->
->To debug both `xds-agent` and `xds-server` or common code
->`xds-common`, it may be useful use the same local sources.
->
->So you should replace `xds-server` + `xds-common` in `vendor` directory by a symlink.
->
->So clone first `xds-server` + `xds-common` sources next to `xds-agent` directory.
+To debug both `xds-agent` and `xds-server` or common code `xds-common`, it may
+be useful use the same local sources.
+
+A trick to do that is to replace `xds-server` + `xds-common` in `vendor`
+directory by a symlink that points to local sources.
+
+So clone first `xds-server` + `xds-common` sources next to `xds-agent` directory.
 
 You should have the following tree:
 
 ```bash
-tree -L 5 --charset=ascii src/
+tree -L 5 src/
 src/
 `-- gerrit.automotivelinux.org
     `-- gerrit
         `-- src
             `-- xds
-                |-- backup.sh
                 |-- xds-agent
-                |-- xds-cli
                 |-- xds-common
-                |-- xds-docs
-                |-- xds-gdb
                 `-- xds-server
 ```
 
-Then invoke `vendor/debug` Makefile rule to create a symlink inside vendor
+Then invoke `vendor/debug` Makefile rule to create symbolic links inside vendor
 directory :
 
 ```bash
 cd src/gerrit.automotivelinux.org/gerrit/src/xds/xds-agent
 make vendor/debug
 ```
+
+## Debug dashboard part (Typescript / angular code)
+
+Start `xds-agent` either from command line or in debug mode (see previous
+chapter) and in another terminal start a watcher daemon so that type typescript
+sources of webapp / dashboard are automatically "transpiled" using following
+command :
+
+```bash
+cd webapp
+npm run watch
+```
+
+Then open the XDS Dashboard page ([http://localhost:8800](http://localhost:8800))
+and open the developer tool of web browser (for example `Ctrl+Shift+I` in Chrome).
diff --git a/docs/part-2/3_xds-cli/4_debug.md b/docs/part-2/3_xds-cli/4_debug.md
index 38628db..e7d0775 100644
--- a/docs/part-2/3_xds-cli/4_debug.md
+++ b/docs/part-2/3_xds-cli/4_debug.md
@@ -1,38 +1,40 @@
-# Debug
+# Debugging
 
-Visual Studio Code launcher settings can be found into `.vscode/launch.json`.
-
->**Tricks:**
->
->To debug both `xds-cli` and `xds-agent` (REST API part) or common
-code `xds-common`, it may be useful use the same local sources.
->
->So you should replace `xds-agent` + `xds-common` in `vendor` directory by a symlink.
->
->So clone first `xds-agent` + `xds-common` sources next to `xds-cli` directory.
+## XDS cli architecture
 
-You should have the following tree:
+This tool is written in *Go*.
 
 ```bash
-tree -L 5 --charset=ascii src/
-src/
-`-- gerrit.automotivelinux.org
-    `-- gerrit
-        `-- src
-            `-- xds
-                |-- backup.sh
-                |-- xds-agent
-                |-- xds-cli
-                |-- xds-common
-                |-- xds-docs
-                |-- xds-gdb
-                `-- xds-server
+|
++-- bin/                # where xds-cli binary will be built
+|
++-- cmd-XXX.go          # GO sources of each sub-commands
+|
++-- conf.d/             # Linux configuration and startup files (systemd user service)
+|
++-- glide.yaml          # Go package dependency file
+|
++-- LICENSE             # XDS cli license
+|
++-- main.go             # main entry point (Go)
+|
++-- Makefile            # makefile including
+|
++-- README.md           # readme
+|
++-- scripts/            # hold various scripts used for installation
+|
++-- vendor/             # temporary directory to hold Go dependencies packages
 ```
 
-Then invoke `vendor/debug` Makefile rule to create a symlink inside vendor
-directory :
+## Debug
 
-```bash
-cd src/gerrit.automotivelinux.org/gerrit/src/xds/xds-cli
-make vendor/debug
-```
+Install first [Visual Studio Code](https://code.visualstudio.com/) and
+[Go plugin](https://marketplace.visualstudio.com/items?itemName=lukehoban.Go)
+(`ext install lukehoban.Go`)
+
+Visual Studio Code launcher settings can be found into `.vscode/launch.json`.
+
+Please follow instructions of xds-agent [debugging chapter](../2_xds-agent/4_debug.html#debug-xds-agent-go-code),
+knowing that you execute these same instructions in `xds-cli` repo, in other words
+by replacing *xds-agent* references by *xds-cli*.
diff --git a/docs/part-2/4_xds-gdb/3_debug.md b/docs/part-2/4_xds-gdb/3_debug.md
index 80554ec..c43e51e 100644
--- a/docs/part-2/4_xds-gdb/3_debug.md
+++ b/docs/part-2/4_xds-gdb/3_debug.md
@@ -1,3 +1,40 @@
-# Debug
+# Debugging
+
+## XDS gdb architecture
+
+This tool is written in *Go*.
+
+```bash
+|
++-- bin/                # where xds-gdb binary will be built
+|
++-- gdb-XXX.go          # xds-gdb Go sources
+|
++-- conf.d/             # Linux configuration and startup files (systemd user service)
+|
++-- glide.yaml          # Go package dependency file
+|
++-- LICENSE             # XDS gdb license
+|
++-- main.go             # main entry point (Go)
+|
++-- Makefile            # makefile including
+|
++-- README.md           # readme
+|
++-- scripts/            # hold various scripts used for installation
+|
++-- vendor/             # temporary directory to hold Go dependencies packages
+```
+
+## Debug
+
+Install first [Visual Studio Code](https://code.visualstudio.com/) and
+[Go plugin](https://marketplace.visualstudio.com/items?itemName=lukehoban.Go)
+(`ext install lukehoban.Go`)
 
 Visual Studio Code launcher settings can be found into `.vscode/launch.json`.
+
+Please follow instructions of xds-agent [debugging chapter](../2_xds-agent/4_debug.html#debug-xds-agent-go-code),
+knowing that you execute these same instructions in `xds-gdb` repo, in other words
+by replacing *xds-agent* references by *xds-gdb*.