Update documentation (#828)

Summary Cleanup UserGuide New markdown file for the configurations with examples Run network-tests documentation Co-authored-by: fabiofcmonteiro <[email protected]>
COVESA · Dec 20, 2024 · 5b593b7 · 5b593b7
1 parent 6461369
commit 5b593b7
Show file tree

Hide file tree

Showing 5 changed files with 2,098 additions and 2,081 deletions.
diff --git a/README.md b/README.md
@@ -5,18 +5,17 @@ Copyright (C) 2015-2024, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
 
 ##### License
 
-This Source Code Form is subject to the terms of the Mozilla Public
-License, v. 2.0. If a copy of the MPL was not distributed with this
-file, You can obtain one at http://mozilla.org/MPL/2.0/.
+This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
+If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
 ##### Contributing Guidelines
 
 For comprehensive details on how to contribute effectively to the project, please refer to our [CONTRIBUTING.md](./CONTRIBUTING.md) file.
 
-##### vsomeip Overview
+##### vSomeIP Overview
 ----------------
-The vSomeIP stack implements the http://some-ip.com/ (Scalable service-Oriented
-MiddlewarE over IP (SOME/IP)) protocol. The stack consists out of:
+The vSomeIP stack implements the http://some-ip.com/ (Scalable service-Oriented MiddlewarE over IP (SOME/IP)) Protocol.
+The stack consists out of:
 
 * a shared library for SOME/IP (`libvsomeip3.so`)
 * a shared library for SOME/IP's configuration module (`libvsomeip3-cfg.so`)
@@ -76,14 +75,14 @@ To change the default configuration folder, call cmake like:
 ```bash
 cmake -DDEFAULT_CONFIGURATION_FOLDER=<DEFAULT CONFIGURATION FOLDER> ..
 ```
-The default configuration folder is /etc/vsomeip.
+The default configuration folder is `/etc/vsomeip`.
 
 ###### Compilation with custom default configuration file
 To change the default configuration file, call cmake like:
 ```bash
 cmake -DDEFAULT_CONFIGURATION_FILE=<DEFAULT CONFIGURATION FILE> ..
 ```
-The default configuration file is /etc/vsomeip.json.
+The default configuration file is `/etc/vsomeip.json`.
 
 ###### Compilation with signal handling
 

diff --git a/documentation/network-tests.md b/documentation/network-tests.md
@@ -3,67 +3,119 @@
 The network-tests can be run on your laptop using the Docker Compose setup designed for Zuul.
 This page will guide you to accomplish that goal.
 
+  * [Prerequisites](#prerequisites)
+  * [Main steps](#main-steps)
+  * [FAQ](#faq)
 
 ## Prerequisites
 
 1. Up-to-date clone of vsomeip, checked out on master or on a branch recently created from it.
 2. Recent Docker version with Compose plugin installed
 
-    a. Check Docker version with docker info, must be at least 23.x.y or 24.x.y, otherwise follow the official instructions to install a newer version: https://docs.docker.com/engine/install/ubuntu/
+    - Check Docker version with docker info, must be at least 23.x.y or 24.x.y, otherwise follow the official instructions to install a newer version: https://docs.docker.com/engine/install/ubuntu/
 
-        $ docker info
-        Client: Docker Engine - Community
-        Version:    24.0.2
-        (...)
-    b. Check if the Docker Compose plugin is installed with docker compose version. If the command fails, follow the official instructions to rectify your Docker installation: https://docs.docker.com/engine/install/ubuntu/
+    ```bash
+    $ docker info
+    Client: Docker Engine - Community
+    Version:    24.0.2
+    (...)
+    ```
 
-        $ docker compose version
-        Docker Compose version v2.18.1
+    - Check if the Docker Compose plugin is installed with docker compose version. If the command fails, follow the official instructions to rectify your Docker installation: https://docs.docker.com/engine/install/ubuntu/
+
+    ```bash
+    $ docker compose version
+    Docker Compose version v2.18.1
+    ```
 
 ## Main steps
 
 1. Clone dlt-daemon to the same Project folder as vsomeip.
 
-        git clone https://github.com/COVESA/dlt-daemon.git
-
-        $ ls
-        dlt-daemon    vsomeip
+    ```bash
+    git clone https://github.com/COVESA/dlt-daemon.git
 
-2. Set the sanitizer type you'd like to use (use LEAK if you don't know or care which one gets used)
+    $ ls
+    dlt-daemon    vsomeip
+    ```
 
-        export SANITIZER_TYPE=<ADDRESS | LEAK | THREAD | UNDEFINED>
+2. Set the sanitizer or valgrind type you'd like to use (use sanitizer LEAK if you don't know or care which one gets used)
+    - **Syntax sanitizers**
 
-    Example:
+            export SANITIZER_TYPE=<ADDRESS | LEAK | THREAD | UNDEFINED>
 
+        **Example**:
+        ```bash
         export SANITIZER_TYPE=LEAK
+        ```
 
+    - **Syntax valgrinds**
 
-3. Create the containers (you must be inside the vsomeip repo to run this step). This will first build the Docker image used by both that contains everything needed to build and run the network-tests (CMake, GCC, Boost, etc.)
+            export VALGRIND_TYPE=<HELGRIND | MASSIF | MEMCHECK>
 
-       docker compose --project-directory zuul/network-tests build
 
-4. Start the containers (same as above, you must be inside the repo directory). This will build vsomeip-lib and then run the network-tests
+        **Example**
+        ```bash
+        export VALGRIND_TYPE=HELGRIND
+        ```
+
+    - NOTE: **Sanitizers** and **Valgrinds** are not compatible with each other, so it's not possible to use them simultaneously.
+    To avoid running the tests with both tools set one of them as empty.
+        **Example**
+        ```bash
+        export SANITIZER_TYPE=''
+        export VALGRIND_TYPE=HELGRIND
+        ```
 
-        docker compose --project-directory zuul/network-tests up
+3. Create the containers (you must be inside the vsomeip repo to run this step). This will first build the Docker image used by both that contains everything needed to build and run the network-tests (CMake, GCC, Boost, etc.)
+    ```bash
+    docker compose --project-directory zuul/network-tests build
+    ```
 
+4. Start the containers (same as above, you must be inside the repo directory). This will build vsomeip-lib and then run the network-tests
+    ```bash
+    docker compose --project-directory zuul/network-tests up
+    ```
 
 ## FAQ
 
-**Question**: I get a strange CMake error when I start the containers
+- **Question**: I get a strange CMake error when I start the containers
+
+        This occurs if you have recently rebuilt vsomeip-lib outside the Docker Compose setup.
+        It can also occur when rebuilding vsomeip-lib after pulling new changes from upstream.
+
+        You can fix it by removing the build directory located inside the repo directory.
+
+
+- **Question**: I'd like to run only a subset of the network-tests
+
+        Locate the CMakePresets.json file and add a "filter" entry inside the preset named ci-network-tests below "execution", like so:
 
-    This occurs if you have recently rebuilt vsomeip-lib outside the Docker Compose setup.
-    It can also occur when rebuilding vsomeip-lib after pulling new changes from upstream.
+        "filter": {
+            "include": {
+                "name": "<regex filter>"
+        }
 
-    You can fix it by removing the build directory located inside the repo directory.
+- **Question**: I'd like to run the tests multiple times
 
+        Locate the CMakePresets.json file and adapt the "execution" entry inside the preset named ci-network-tests:
 
-**Question**: I'd like to run only a subset of the network-tests
+        "execution": {
+            "timeout": 150,
+            "repeat": {
+                "count": 5,
+                "mode": "until-fail",:
+            }
+        },
 
-    Locate the CMakePresets.json file and add a "filter" entry inside the preset named ci-network-tests below "execution", like so:
+- **Question**: The log output is not displaying all the tests logs
 
-    "filter": {
-        "include": {
-            "name": "<regex filter>"
-    }
-}
+        Locate the CMakePresets.json file and in the "output" entry inside the preset named ci-network-tests, add the verbosity option.
+        You might also need to adapt the tests json configuration files to increase the log level.
 
+        "output": {
+            "maxFailedTestOutputSize": 1e6,
+            "maxPassedTestOutputSize": 1e6,
+            "outputOnFailure": true,
+            "verbosity": "extra"
+        },