Various updates to reflect current XDS state.

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

8 files changed, 152 insertions, 86 deletions

diff --git a/docs/part-1/1_install-client.md b/docs/part-1/1_install-client.md
index 4a1d140..0d463d1 100644
--- a/docs/part-1/1_install-client.md
+++ b/docs/part-1/1_install-client.md
@@ -56,3 +56,23 @@ seb@laptop ~$  sudo zypper install agl-xds-gdb
 - repeat the previous steps to install other tools depending of your needs:
   - `xds-exec` : requested for command line and IDE integration. ([released tarball link](https://github.com/iotbzh/xds-exec/releases)).
   - `xds-gdb` : requested for debugging application. ([released tarball link](https://github.com/iotbzh/xds-gdb/releases)).
+
+## Start xds-agent
+
+XDS-agent is a client tool that must run on your local / user development
+machine when you use XDS.
+
+For Linux distro, a user systemd service is provided, so you just need to enable
+if you want to start it automatically at boot and you can also start it
+immediately using following commands:
+
+```bash
+# Enable xds-agent service at boot
+seb@laptop ~$  systemctl --user enable xds-agent.service
+
+# Manually start xds-agent service
+seb@laptop ~$  systemctl --user start xds-agent.service
+
+# Get status and log of xds-agent service
+seb@laptop ~$  systemctl --user status xds-agent.service
+```
diff --git a/docs/part-1/2_install-xds-server.md b/docs/part-1/2_install-xds-server.md
index 7a8ff23..5ac244c 100644
--- a/docs/part-1/2_install-xds-server.md
+++ b/docs/part-1/2_install-xds-server.md
@@ -57,6 +57,14 @@ seb@laptop ~$ docker ps | grep worker-xds
 b985d81af40c        docker.automotivelinux.org/agl/worker-xds:3.99.1       "/usr/bin/wait_for..."   6 days ago           Up 4 hours          0.0.0.0:8000->8000/tcp, 0.0.0.0:69->69/udp, 0.0.0.0:10809->10809/tcp, 0.0.0.0:2222->22/tcp    agl-xds-seb@laptop-0-seb
 ```
 
+Note that you can also add a new shared directory using `--volume` option in order
+to use for example with Path-Mapping folder type.
+
+```bash
+# Create new XDS worker container and share extra '$HOME/my-workspace' directory
+seb@laptop ~$ bash ./xds-docker-create-container.sh --volume /my-workspace:$HOME/my-workspace
+```
+
 ### Check if xds-server is running
 
 `xds-server` is automatically started as a service on container startup.
diff --git a/docs/part-1/3_install-sdks.md b/docs/part-1/3_install-sdks.md
index 6a747ac..9c8b245 100644
--- a/docs/part-1/3_install-sdks.md
+++ b/docs/part-1/3_install-sdks.md
@@ -35,3 +35,12 @@ seb@laptop ~$ ssh -p 2222 devel@localhost
 devel@docker ~$ sudo /opt/AGL/xds/server/xds-utils/install-agl-sdks.sh --arch corei7-64 --file /tmp/poky-agl-glibc-x86_64-agl-demo-platform-crosssdk-corei7-64-toolchain-
 4.0.1.sh
 ```
+
+<!-- warning -->
+>**Warning:** due to some limitation, you need for now to restart `xds-server` in
+order to make new installed SDK visible/available.
+> ```bash
+> seb@laptop ~$  ssh -p 2222 devel@localhost
+> devel@docker ~$  systemctl --user restart xds-server.service
+> ```
+<!-- endwarning -->
diff --git a/docs/part-1/4_build-first-app.md b/docs/part-1/4_build-first-app.md
index 880d7c8..2a1bb67 100644
--- a/docs/part-1/4_build-first-app.md
+++ b/docs/part-1/4_build-first-app.md
@@ -1,5 +1,15 @@
 # Create your first AGL application
 
+## Prerequisites
+
+- `xds-agent` is running on your machine
+  (see **Installing XDS client tools**  previous chapter)
+- `xds-server` is running locally in a docker container or is accessible on your
+  network (see **Installing XDS server** previous chapter)
+- one or more SDK have been installed (see **Installing AGL SDKs** previous chapter)
+- XDS configuration is correct: in other words, all table lines are blue in
+  configuration page of XDS Dashboard.
+
 ## Setup
 
 Let's use for example helloworld-native-application, so you need first to clone
@@ -41,6 +51,10 @@ Set `Sharing Type` and paths according to your setup.
 
 ![](./pictures/xds-dashboard-prj-1.png){:: style="width:90%;"}
 
+Note that XDS creates a file name `xds-project.conf` (if not already exists)
+when you declare a new project using XDS Dashboard. This file may be very useful
+when you will use XDS client tools such as `xds-exec` (see next chapter).
+
 <!-- note -->
 >**Note:** when you select `Path mapping`, you must clone your project into
 `$HOME/xds-workspace` directory (named "Local Path" in modal window) and
@@ -71,6 +85,10 @@ List of existing projects:
   CKI7R47-UWNDQC3_test3
 ```
 
+> **Note:** XDS tools, including `xds-exec` are installed by default in `/opt/AGL/bin`
+> directory and this path has been added into your PATH variable.
+> If it is not the case, just add it manually using `export PATH=${PATH}:/opt/AGL/bin` command line.
+
 Now to refer your project, just use --id option or use `XDS_PROJECT_ID`
 environment variable.
 
@@ -78,14 +96,9 @@ You are now ready to use XDS to for example cross build your project.
 Here is an example to build a project based on CMakefile:
 
 ```bash
-# Add xds-exec in the PATH
-export PATH=${PATH}:/opt/AGL/bin
-
-# Go into your project directory
+# Go into your project directory and create a build directory
 cd $MY_PROJECT_DIR
-
-# Create a build directory
-xds-exec --id=CKI7R47-UWNDQC3_myProject --sdkid=poky-agl_aarch64_4.0.1 --url=http://localhost:8000 -- mkdir build
+mkdir build
 
 # Generate build system using cmake
 xds-exec --id=CKI7R47-UWNDQC3_myProject --sdkid=poky-agl_aarch64_4.0.1 --url=http://localhost:8000 -- cd build && cmake ..
@@ -98,23 +111,31 @@ To avoid to set project id, xds server url, ... at each command line, you can
 define these settings as environment variable within an env file and just set
 `--config` option or source file before executing xds-exec.
 
+XDS creates a file name `xds-project.conf` (only if not already exists) when you
+declare a new project using XDS Dashboard. Use this file with `--config` option.
+
 For example, the equivalence of above command is:
 
 ```bash
 # MY_PROJECT_DIR=/home/seb/xds-workspace/helloworld-native-application
 cd $MY_PROJECT_DIR
-cat > xds-project.conf << EOF
- export XDS_SERVER_URL=localhost:8000
- export XDS_PROJECT_ID=CKI7R47-UWNDQC3_myProject
- export XDS_SDK_ID=poky-agl_corei7-64_4.0.1
-EOF
 
-xds-exec --config xds-project.conf -- mkdir build
+# Edit and potentially adapt xds-project.conf file that has been created
+# automatically on project declaration using XDS Dashboard
+vi xds-project.conf
+  # XDS project settings
+  export XDS_SERVER_URL=localhost:8000
+  export XDS_PROJECT_ID=cde3b382-9d3b-11e7_helloworld-native-application
+  export XDS_SDK_ID=poky-agl_aarch64_4.0.1
+
+# Create build directory and invoke cmake and then build project
+xds-exec --config xds-project.conf -- "mkdir -p build && cd build && cmake .."
+cd build && xds-exec -- make all
 
-# Or sourcing env file
+# Or equivalent by first sourcing conf file (avoid to set --config option)
 source xds-project.conf
-xds-exec -- mkdir -o build && cd build && cmake ..
-xds-exec -- cd build && make all
+xds-exec -- "mkdir -p build && cd build && cmake .."
+cd build && xds-exec -- make all
 ```
 
 <!-- note -->
@@ -124,23 +145,27 @@ to execute on xds-server.
 
 ## Build from IDE
 
-First create the XDS config file that will be used later by xds-exec commands.
-For example we use here aarch64 SDK to cross build application for a Renesas
-Gen3 board.
+First create an XDS config file or reuse the previous one, for example we use 
+here aarch64 SDK to cross build application for a Renesas Gen3 board.
 
 ```bash
 # create file at root directory of your project
 # for example:
 # MY_PROJECT_DIR=/home/seb/xds-workspace/helloworld-native-application
-cat > $MY_PROJECT_DIR/xds-gen3.conf << EOF
+cat > $MY_PROJECT_DIR/xds-project.conf << EOF
  export XDS_SERVER_URL=localhost:8000
  export XDS_PROJECT_ID=cde3b382-9d3b-11e7_helloworld-native-application
- export XDS_SDK_ID=poky-agl_aarch64_4.0.1
+ export XDS_SDK_ID=poky-agl_aarch64_3.99.3
 EOF
 ```
 
 ### NetBeans
 
+This chapter will show you how to create 2 configurations, one to compile your
+project natively (using native GNU gcc) and one to cross-compile your project
+using XDS. You can easily switch from one to other configuration using menu
+**Run -> Set Project Configuration**.
+
 __Netbeans 8.x :__
 
 - Open menu **Tools** -> **Options**
@@ -154,16 +179,23 @@ __Netbeans 8.x :__
 
   - Finally click on **OK** button.
 
-- Open menu **File** -> **New Project**
+- Now create we first declare project into NetBeans and create first a native
+  configuration. To do that, open menu **File** -> **New Project**
 
 - Select **C/C++ Project with Existing Sources** ;
   Click on **Next** button
 
-- Specify the directory where you cloned your project and click on **Finish** button to keep all default settings:
+- Specify the directory where you cloned your project and click on **Finish** button to keep all default settings in order to create a *native configuration*.
 
     ![Select Model panel](./pictures/nb_new-project-1.png)
 
-- Edit project properties (using menu **File** -> **Project Properties**) to add a new configuration that will use XDS to cross-compile your application for example for a Renesas Gen3 board)
+<!-- warning -->
+> **Warning:** Take care to set **Tool Collection** to **Default GNU** in order
+> to create a native configuration based on native GNU GCC.
+<!-- endwarning -->
+
+- Now we will create a **cross configuration** based on XDS tools.
+  Edit project properties (using menu **File** -> **Project Properties**) to add a new configuration that will use XDS to cross-compile your application for example for a Renesas Gen3 board.
 
   - in **Build** category, click on **Manage Configurations** button and then **New** button to add a new configuration named for example "Gen3 board"
 
@@ -173,13 +205,13 @@ __Netbeans 8.x :__
 
   - Select **Pre-Build** sub-category, and set:
     - Working Directory: `build_gen3`
-    - Command Line: `xds-exec -c ../xds-gen3.conf -- cmake -DRSYNC_TARGET=root@renesas-gen3 -DRSYNC_PREFIX=/opt ..`
+    - Command Line: `xds-exec -c ../xds-project.conf -- cmake -DRSYNC_TARGET=root@renesas-gen3 -DRSYNC_PREFIX=/opt ..`
     - Pre-build First: `ticked`
 
   - Select **Make** sub-category, and set:
     - Working Directory: `build_gen3`
-    - Build Command: `xds-exec -c ../xds-gen3.conf -- make remote-target-populate`
-    - Clean Command: `xds-exec -c ../xds-gen3.conf -- make clean`
+    - Build Command: `xds-exec -c ../xds-project.conf -- make remote-target-populate`
+    - Clean Command: `xds-exec -c ../xds-project.conf -- make clean`
 
     ![Select Make sub-category](./pictures/nb_new-project-3.png)
 
@@ -193,7 +225,8 @@ __Netbeans 8.x :__
 
 By changing configuration from **Default** to **Gen3 board**, you can now simply
 compile your helloworld application natively (**Default** configuration) or
-cross-compile your application through XDS for a Renesas Gen3 board (**Gen3 board** configuration).
+cross-compile your application through XDS for the Renesas Gen3 board
+(**Gen3 board** configuration).
 
 ### Visual Studio Code
 
@@ -204,65 +237,46 @@ cd $MY_PROJECT_DIR
 code . &
 ```
 
-Add new tasks : press `Ctrl+Shift+P` and select the `Tasks: Configure Task Runner` command and you will see a list of task runner templates.
+Add new tasks : press `Ctrl+Shift+P` and select the `Tasks: Configure Task`
+command and you will see a list of task runner templates.
 
-And define your own tasks, here is an example to build [unicens2-binding](https://github.com/iotbzh/unicens2-binding) AGL binding based on cmake (_options value of args array must be updated regarding your settings_):
+And define your own tasks, here is an example to build
+[helloworld-native-application](https://github.com/iotbzh/helloworld-native-application)
+AGL helloworld application based on cmake template.
 
 ```json
 {
-    "version": "0.1.0",
-    "linux": {
-        "command": "/opt/AGL/bin/xds-exec"
+    "version": "2.0.0",
+    "type": "shell",
+    "presentation": {
+        "reveal": "always"
     },
-    "isShellCommand": true,
-    "args": [
-        "-url", "localhost:8000",
-        "-id", "CKI7R47-UWNDQC3_myProject",
-        "-sdkid", "poky-agl_aarch64_4.0.1",
-        "--"
-    ],
-    "showOutput": "always",
-    "tasks": [{
+    "tasks": [
+        {
             "taskName": "clean",
-            "suppressTaskName": true,
-            "args": [
-                "rm -rf build/* && echo Cleanup done."
-            ]
+            "command": "/bin/rm -rf ${workspaceFolder}/build/* && mkdir -p build && echo Cleanup done.",
+            "problemMatcher": []
         },
         {
             "taskName": "pre-build",
-            "isBuildCommand": true,
-            "suppressTaskName": true,
-            "args": [
-                "mkdir -p build && cd build && cmake -DRSYNC_TARGET=root@renesas-gen3 -DRSYNC_PREFIX=/opt"
+            "group": "build",
+            "command": "/opt/AGL/bin/xds-exec --rpath build --config xds-project.conf -- cmake -DRSYNC_TARGET=root@renesas-gen3 -DRSYNC_PREFIX=/opt ../",
+            "problemMatcher": [
+                "$gcc"
             ]
         },
         {
             "taskName": "build",
-            "isBuildCommand": true,
-            "suppressTaskName": true,
-            "args": [
-                "cd build && make widget"
-            ],
-            "problemMatcher": {
-                "owner": "cpp",
-                "fileLocation": ["absolute"],
-                "pattern": {
-                    "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$",
-                    "file": 1,
-                    "line": 2,
-                    "column": 3,
-                    "severity": 4,
-                    "message": 5
-                }
-            }
+            "group": "build",
+            "command": "/opt/AGL/bin/xds-exec --rpath build --config xds-project.conf -- make widget",
+            "problemMatcher": [
+                "$gcc"
+            ]
         },
         {
             "taskName": "populate",
-            "suppressTaskName": true,
-            "args" : [
-                "cd build && make widget-target-install"
-            ]
+            "command": "/opt/AGL/bin/xds-exec --rpath build --config xds-project.conf -- make widget-target-install",
+            "problemMatcher": []
         }
     ]
 }
diff --git a/docs/part-1/pictures/nb_new-project-3.png b/docs/part-1/pictures/nb_new-project-3.png
index 051bfdd..ebd330a 100644
--- a/docs/part-1/pictures/nb_new-project-3.png
+++ b/docs/part-1/pictures/nb_new-project-3.png
diff --git a/docs/part-2/1_xds-server.md b/docs/part-2/1_xds-server.md
index c4f00b3..ee5df5e 100644
--- a/docs/part-2/1_xds-server.md
+++ b/docs/part-2/1_xds-server.md
@@ -65,6 +65,14 @@ seb@laptop ~$ docker ps | grep worker-xds
 b985d81af40c        docker.automotivelinux.org/agl/worker-xds:3.99.1       "/usr/bin/wait_for..."   6 days ago           Up 4 hours          0.0.0.0:8000->8000/tcp, 0.0.0.0:69->69/udp, 0.0.0.0:10809->10809/tcp, 0.0.0.0:2222->22/tcp    agl-xds-seb@laptop-0-seb
 ```
 
+Note that you can also add a new shared directory using `--volume` option in order
+to use for example with Path-Mapping folder type.
+
+```bash
+# Create new XDS worker container and share extra '$HOME/my-workspace' directory
+seb@laptop ~$ bash ./xds-docker-create-container.sh --volume /my-workspace:$HOME/my-workspace
+```
+
 This container (ID=0) exposes following ports:
 
 - 8000 : `xds-server` to serve XDS Dashboard
@@ -73,14 +81,19 @@ This container (ID=0) exposes following ports:
 
 #### Manually setup docker user id
 
+<!-- note -->
+>**Note:** if you used `xds-docker-create-container.sh` script to create XDS
+> docker container, user uid/gid inside docker has already been changed by this script.
+<!-- endnote -->
+
 If you plan to **use path-mapping sharing type for your projects**, you need to have the same user id and group id inside and outside docker. By default user and group name inside docker is set `devel` (id `1664`), use following commands to replace id `1664` with your user/group id:
 
 ```bash
 # Set docker container name to use (usually agl-xds-xxx where xxx is USERNAME@MACHINENAME-IDX-NAME)
 seb@laptop ~$ export CONTAINER_NAME=agl-xds-seb@laptop-0-seb
 
-# First stop xds-server
-seb@laptop ~$ docker exec ${CONTAINER_NAME} bash -c "systemctl stop xds-server"
+# First kill all processes of devel user (including running xds-server)
+seb@laptop ~$ docker exec ${CONTAINER_NAME} bash -c "/bin/loginctl kill-user devel"
 
 # Change user and group id inside docker to match your ids
 seb@laptop ~$ docker exec ${CONTAINER_NAME} bash -c "usermod -u $(id -u) devel"
@@ -89,8 +102,11 @@ seb@laptop ~$ docker exec ${CONTAINER_NAME} bash -c "groupmod -g $(id -g) devel"
 # Update some files ownership
 seb@laptop ~$ docker exec ${CONTAINER_NAME} bash -c "chown -R devel:devel /home/devel /tmp/xds*"
 
-# Restart xds-server
-seb@laptop ~$ docker exec ${CONTAINER_NAME} bash -c "systemctl start xds-server"
+# Restart devel autologin service
+seb@laptop ~$ docker exec ${CONTAINER_NAME} bash -c "systemctl start autologin"
+
+# Restart xds-server as a service (ssh port 2222 may depend on your container ID)
+seb@laptop ~$ ssh -p 2222 devel@localhost -- "systemctl --user start xds-server"
 ```
 
 ## Check if xds-server is running (open XDS Dashboard)
@@ -110,16 +126,16 @@ If needed you can status / stop / start  it manually using following commands:
 seb@laptop ~$ ssh -p 2222 devel@localhost
 
 # Status XDS server:
-devel@docker ~$ sudo systemctl status xds-server.service
+devel@docker ~$ systemctl --user status xds-server.service
 
 # Stop XDS server
-devel@docker ~$ sudo systemctl stop xds-server.service
+devel@docker ~$ systemctl --user stop xds-server.service
 
 # Start XDS server
-devel@docker ~$ sudo systemctl start xds-server.service
+devel@docker ~$ systemctl --user start xds-server.service
 
 # Get XDS server logs
-devel@docker ~$ sudo journalctl --unit=xds-server.service --output=cat
+devel@docker ~$ journalctl --user --unit=xds-server.service --output=cat
 ```
 
 ### Manually Start XDS server
@@ -140,7 +156,7 @@ supported *level* are: panic, fatal, error, warn, info, debug.
 ```bash
 seb@laptop ~$ ssh -p 2222 devel@localhost
 devel@docker ~$ echo 'LOG_LEVEL=debug' | sudo tee --append /etc/default/xds-server > /dev/null
-devel@docker ~$ sudo systemctl restart xds-server.service
+devel@docker ~$ systemctl --user restart xds-server.service
 devel@docker ~$ tail -f /tmp/xds-server/logs/xds-server.log
 ```
 
diff --git a/docs/part-2/2_xds-agent.md b/docs/part-2/2_xds-agent.md
index 55943fc..0ece136 100644
--- a/docs/part-2/2_xds-agent.md
+++ b/docs/part-2/2_xds-agent.md
@@ -11,15 +11,14 @@ used to remotely cross build applications.
 
 ## Configuration
 
-xds-agent configuration is driven by a JSON config file (named `agent-config.json`).
+xds-agent configuration is driven by a JSON config file.
 The tarball mentioned in previous section includes this file with default settings.
 
-Here is the logic to determine which `agent-config.json` file will be used:
+Here is the logic to determine which conf file will be used:
 
 1. from command line option: `--config myConfig.json`
 1. `$HOME/.xds/agent/agent-config.json` file
-1. `/etc/xds-agent/agent-config.json` file
-1. `<xds-agent executable dir>/agent-config.json` file
+1. `/etc/xds-agent/config.json` file
 
 Supported fields in configuration file are (all fields are optional and example
 below corresponds to the default values):
@@ -29,7 +28,7 @@ below corresponds to the default values):
 - **xds-apikey** : xds-agent api-key to use (always set value to "1234abcezam")
 - **syncthing.binDir** : syncthing binaries directory (default: executable directory)
 - **syncthing.home"** : syncthing home directory (usually .../syncthing-config)
-- **syncthing.gui-address** : syncthing gui url (default http://localhost:8386)
+- **syncthing.gui-address** : syncthing gui url (default <http://localhost:8386>)
 - **syncthing.gui-apikey** : syncthing api-key to use (default auto-generated)
 
 ```json
diff --git a/docs/part-2/3_xds-exec.md b/docs/part-2/3_xds-exec.md
index 504cf01..0c63ff3 100644
--- a/docs/part-2/3_xds-exec.md
+++ b/docs/part-2/3_xds-exec.md
@@ -19,7 +19,7 @@ will be sourced on `xds-exec` start-up. Use `--config|-c` option or set
 `XDS_CONFIG` environment variable to specify the config filename.
 
 So configuration is driven either by environment variables or by command line
-options or using a config file knowning that the following priority order is used:
+options or using a config file knowing that the following priority order is used:
 
 1. use option value (for example use project ID set by `--id` option),
 1. else use variable `XDS_xxx` (for example `XDS_PROJECT_ID` variable) when a config file is specified with `--config|-c` option,