Schema documentation

src/launch_manager_daemon/config/config_schema/README.rst

@@ -16,71 +16,90 @@
 Launch Manager Configuration Schema
 ###################################
 
-This folder contains the Launch Manager configuration JSON Schema. The schema defines and validates the structure of Launch Manager configuration files.
+This folder contains the **Launch Manager** configuration JSON Schema. The schema defines and validates the structure of **Launch Manager** configuration files, ensuring consistency and correctness across different deployments.
 
 Overview
 ********
 
-This project manages the Launch Manager configuration schema as a single, self-contained file. When you need to modify or extend the schema, you should directly edit `s-core_launch_manager.schema.json`.
+This project manages the **Launch Manager** configuration schema as a single, self-contained file. When you need to modify or extend the schema, you should directly edit ``s-core_launch_manager.schema.json``.
 
 **Project Structure:**
 
+The project is structured to provide a clear organization for the schema, default values, examples, and documentation.
+
 ::
 
-    +-- s-core_launch_manager.schema.json # The Launch Manager schema.
-    +-- examples/                         # Illustrative example configuration files for the schema.
-    +-- scripts/                          # Utility scripts, including a validation tool.
+    .
+    |-- default_values/                   # Default values for various configuration aspects.
+    |-- docs/                             # Comprehensive documentation for Launch Manager configuration.
+    |-- examples/                         # Illustrative example configuration files for the schema.
+    |-- s-core_launch_manager.schema.json # The Launch Manager schema definition.
+    `-- scripts/                          # Utility scripts, including a validation tool.
 
 Quick Start
 ***********
 
-For Users & Developers
-======================
+For Users and Developers
+========================
 
-Whether you're validating a Launch Manager configuration against the schema, or actively developing and modifying the schema itself, here's how to interact with this project:
+Whether you are validating a **Launch Manager** configuration against the schema or actively developing and modifying the schema itself, here is how to interact with this project:
 
-1.  **Locate the Schema:** The complete schema definition resides in ``s-core_launch_manager.schema.json``.
-2.  **Explore Examples:** The ``examples/`` folder provides various sample Launch Manager configuration files. These are invaluable for understanding how the schema applies in practice and how to structure your own configurations.
-3.  **Validate Your Configuration:** Use the provided validation script to check if your configuration file conforms to the schema:
+1. **Locate the Schema:** The complete schema definition resides in ``s-core_launch_manager.schema.json``. This file is the authoritative source for defining the structure of **Launch Manager** configurations.
+2. **Explore Examples:** The ``examples/`` folder provides various sample **Launch Manager** configuration files. These examples are invaluable for understanding how the schema applies in practice and how to structure your own configurations.
+3. **Validate Your Configuration:** Use the provided validation script to check if your configuration file conforms to the schema:
 
     .. code-block:: bash
 
        scripts/validate.py --schema s-core_launch_manager.schema.json --instance your_config.json
 
+Documentation
+*************
+
+The ``docs`` folder contains comprehensive documentation related to the **Launch Manager** configuration. It is highly recommended to consult these resources for detailed explanations and advanced usage patterns.
+
+* `launch_manager_configuration.rst <docs/launch_manager_configuration.rst>`_: Provides in-depth information about configuring the **Launch Manager**.
+* `examples.rst <docs/examples.rst>`_: Offers further explanations and context for the examples provided in the ``examples/`` directory.
+
+Default Values
+**************
+
+The ``default_values`` folder contains JSON files specifying default settings for various components of the **Launch Manager**. These defaults are crucial for understanding the baseline behavior of the system and for configuring specific aspects like **Run Target** settings.
+
 Examples
 ********
 
-The ``examples`` folder contains a set of sample Launch Manager configuration files. Each example demonstrates valid configurations according to the ``s-core_launch_manager.schema.json``.
+The ``examples`` folder contains a set of sample **Launch Manager** configuration files. Each example demonstrates valid configurations according to the ``s-core_launch_manager.schema.json``.
 
-**Recommendation:** If you are new to Launch Manager configurations, **start by reviewing these examples**. They offer practical insight into the expected structure, available properties, and common use cases defined by the schema.
+**Recommendation:** If you are new to **Launch Manager** configurations, **start by reviewing these examples**. They offer practical insight into the expected structure, available properties, and common use cases defined by the schema.
 
 Scripts
 *******
 
-The ``scripts`` folder houses utility scripts designed to assist with schema development.
+The ``scripts`` folder houses utility scripts designed to assist with schema development and validation.
 
 validate.py
 ===========
 
-The ``validate.py`` script is a crucial tool for verifying that any given Launch Manager configuration instance adheres to the rules defined in `s-core_launch_manager.schema.json`.
+The ``validate.py`` script is a crucial tool for verifying that any given **Launch Manager** configuration instance adheres to the rules defined in ``s-core_launch_manager.schema.json``.
 
 **Usage:**
 
-To validate a configuration file (e.g., `example_conf.json` from the `examples` folder) against the schema:
+To validate a configuration file (e.g., ``example_conf.json`` from the ``examples`` folder) against the schema:
 
 .. code-block:: bash
 
    scripts/validate.py --schema s-core_launch_manager.schema.json --instance examples/example_conf.json
    Success --> examples/example_conf.json: valid
 
-**When to use:**
-*   **During Development:** Run this script frequently whenever you're creating or modifying a Launch Manager configuration file. It provides immediate feedback on whether your changes are valid according to the schema.
-*   **Schema Development:** If you are making changes to `s-core_launch_manager.schema.json` itself, always run `validate.py` against the examples to ensure your schema changes haven't inadvertently broken existing, valid configurations.
+**When to Use:**
+
+* **During Development:** Run this script frequently whenever you are creating or modifying a **Launch Manager** configuration file. It provides immediate feedback on whether your changes are valid according to the schema.
+* **Schema Development:** If you are making changes to ``s-core_launch_manager.schema.json`` itself, always run ``validate.py`` against the examples to ensure your schema changes have not inadvertently broken existing, valid configurations. This step is vital for maintaining backward compatibility and preventing regressions.
 
 Typical Workflow
 ****************
 
 For schema developers or those creating new configurations:
 
-1.  **Modify** the ``s-core_launch_manager.schema.json`` file (if you're updating the schema definition) or your Launch Manager configuration file.
-2.  **Validate** your changes using the `scripts/validate.py` script against relevant example files or your new configuration. This iterative process helps ensure compliance and catch errors early.
+1. **Modify** the ``s-core_launch_manager.schema.json`` file (if you are updating the schema definition) or your **Launch Manager** configuration file.
+2. **Validate** your changes using the ``scripts/validate.py`` script against relevant example files or your new configuration. This iterative process helps ensure compliance and catch errors early, contributing to a robust configuration system.

src/launch_manager_daemon/config/config_schema/default_values/alive_supervision_defaults.json

@@ -0,0 +1,5 @@
+{
+    "alive_supervision" : {
+        "evaluation_cycle": 0.5
+    }
+}

src/launch_manager_daemon/config/config_schema/default_values/component_properties_defaults.json

@@ -0,0 +1,20 @@
+{
+    "component_properties": {
+        "binary_name": "",
+        "application_profile": {
+            "application_type": "REPORTING_AND_SUPERVISED",
+            "is_self_terminating": false,
+            "alive_supervision": {
+                "reporting_cycle": 0.5,
+                "failed_cycles_tolerance": 2,
+                "min_indications": 1,
+                "max_indications": 3
+            }
+        },
+        "depends_on": [],
+        "process_arguments": [],
+        "ready_condition": {
+            "process_state": "Running"
+        }
+    }
+}

src/launch_manager_daemon/config/config_schema/default_values/deployment_config_defaults.json

@@ -0,0 +1,28 @@
+{
+    "deployment_config": {
+        "ready_timeout": 0.5,
+        "shutdown_timeout": 0.5,
+        "environmental_variables": {},
+        "bin_dir": "/opt",
+        "working_dir": "/tmp",
+        "ready_recovery_action": {
+            "restart": {
+                "number_of_attempts": 0,
+                "delay_before_restart": 0
+            }
+        },
+        "recovery_action": {
+            "switch_run_target": {
+                "run_target": "Off"
+            }
+        },
+        "sandbox": {
+            "uid": 1000,
+            "gid": 1000,
+            "supplementary_group_ids": [],
+            "security_policy": "",
+            "scheduling_policy": "SCHED_OTHER",
+            "scheduling_priority": 0
+        }
+    }
+}

src/launch_manager_daemon/config/config_schema/default_values/run_target_defaults.json

@@ -0,0 +1,12 @@
+{
+    "run_target": {
+        "description": "",
+        "depends_on": [],
+        "transition_timeout": 3,
+        "recovery_action": {
+            "switch_run_target": {
+                "run_target": "Off"
+            }
+        }
+    }
+}

src/launch_manager_daemon/config/config_schema/default_values/watchdog_defaults.json

@@ -0,0 +1,8 @@
+{
+    "watchdog": {
+        "device_file_path": "/dev/watchdog",
+        "max_timeout": 2.0,
+        "deactivate_on_shutdown": true,
+        "require_magic_close": false
+    }
+}

src/launch_manager_daemon/config/config_schema/docs/examples.rst

@@ -0,0 +1,34 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2026 Contributors to the Eclipse Foundation
+   #
+   # See the NOTICE file(s) distributed with this work for additional
+   # information regarding copyright ownership.
+   #
+   # This program and the accompanying materials are made available under the
+   # terms of the Apache License Version 2.0 which is available at
+   # https://www.apache.org/licenses/LICENSE-2.0
+   #
+   # SPDX-License-Identifier: Apache-2.0
+   # *******************************************************************************
+
+Configuration Examples
+######################
+
+This document provides a set of configuration examples that come with the **Launch Manager** schema. These examples are designed to show common ways to use **Launch Manager** and to demonstrate how configurations should be structured. They serve as practical guides, helping users understand how to apply various features effectively.
+
+`example_conf.json`
+*******************
+
+The `example_conf.json` file is a fundamental example within the **Launch Manager** system. While it presents a relatively simple setup, its main goal is to clearly show the key ideas behind defining a **Run Target**, specifying its individual **Components**, and setting up how they depend on each other.
+
+Users can examine this basic example to understand the core principles. These principles can then be scaled and applied to build much more elaborate **Launch Manager** configurations, effectively managing even the most complex application setups.
+
+A high-level overview of this configuration, which highlights its dependencies, is shown below:
+
+.. figure:: images/example_conf_graph.svg
+   :alt: Graphical representation of example configuration
+   :width: 70%
+   :align: center
+
+   Dependency graph for example_conf.json

src/launch_manager_daemon/config/config_schema/docs/images/example_conf_graph.drawio

@@ -0,0 +1,81 @@
+<mxfile>
+  <diagram name="Seite-1" id="8TxOx58P-o2VodMCP5Yr">
+    <mxGraphModel dx="1366" dy="796" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" background="#ffffff" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="1qNC7CyFBQH27r0SmDnI-17" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="1qNC7CyFBQH27r0SmDnI-9" target="1qNC7CyFBQH27r0SmDnI-16">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="1qNC7CyFBQH27r0SmDnI-19" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="1qNC7CyFBQH27r0SmDnI-9" target="1qNC7CyFBQH27r0SmDnI-10">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="1qNC7CyFBQH27r0SmDnI-9" value="Full" style="ellipse;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
+          <mxGeometry x="250" y="1050" width="120" height="80" as="geometry" />
+        </mxCell>
+        <mxCell id="1qNC7CyFBQH27r0SmDnI-13" style="rounded=0;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="1qNC7CyFBQH27r0SmDnI-10" target="1qNC7CyFBQH27r0SmDnI-11">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="1qNC7CyFBQH27r0SmDnI-14" value="Running" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="1qNC7CyFBQH27r0SmDnI-13">
+          <mxGeometry x="-0.3481" y="3" relative="1" as="geometry">
+            <mxPoint x="-3" y="7" as="offset" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="1qNC7CyFBQH27r0SmDnI-31" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="1qNC7CyFBQH27r0SmDnI-10" target="1qNC7CyFBQH27r0SmDnI-27">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="1qNC7CyFBQH27r0SmDnI-32" value="Running" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="1qNC7CyFBQH27r0SmDnI-31">
+          <mxGeometry x="0.5161" y="3" relative="1" as="geometry">
+            <mxPoint as="offset" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="1qNC7CyFBQH27r0SmDnI-10" value="test_app1" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="250" y="1190" width="120" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="1qNC7CyFBQH27r0SmDnI-11" value="dlt-daemon" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="250" y="1320" width="120" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="1qNC7CyFBQH27r0SmDnI-12" value="setup_filesystem_sh" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="250" y="1450" width="120" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="1qNC7CyFBQH27r0SmDnI-28" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;exitX=0.5;exitY=1;exitDx=0;exitDy=0;" edge="1" parent="1" source="1qNC7CyFBQH27r0SmDnI-15" target="1qNC7CyFBQH27r0SmDnI-12">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="1qNC7CyFBQH27r0SmDnI-29" value="Terminated" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="1qNC7CyFBQH27r0SmDnI-28">
+          <mxGeometry x="0.1789" y="-1" relative="1" as="geometry">
+            <mxPoint x="22" y="-1" as="offset" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="1qNC7CyFBQH27r0SmDnI-15" value="state_manager" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="60" y="1320" width="120" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="1qNC7CyFBQH27r0SmDnI-18" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="1qNC7CyFBQH27r0SmDnI-16" target="1qNC7CyFBQH27r0SmDnI-15">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="1qNC7CyFBQH27r0SmDnI-16" value="Minimal" style="ellipse;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
+          <mxGeometry x="60" y="1150" width="120" height="80" as="geometry" />
+        </mxCell>
+        <mxCell id="1qNC7CyFBQH27r0SmDnI-20" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;" edge="1" parent="1" source="1qNC7CyFBQH27r0SmDnI-11" target="1qNC7CyFBQH27r0SmDnI-12">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="1qNC7CyFBQH27r0SmDnI-22" value="Terminated" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="1qNC7CyFBQH27r0SmDnI-20">
+          <mxGeometry x="-0.7005" relative="1" as="geometry">
+            <mxPoint y="20" as="offset" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="1qNC7CyFBQH27r0SmDnI-27" value="someip-daemon" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="420" y="1320" width="120" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="1qNC7CyFBQH27r0SmDnI-34" value="RunTarget" style="ellipse;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
+          <mxGeometry x="20" y="1600" width="120" height="80" as="geometry" />
+        </mxCell>
+        <mxCell id="1qNC7CyFBQH27r0SmDnI-35" value="Component" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="150" y="1610" width="120" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="1qNC7CyFBQH27r0SmDnI-36" value="Legend" style="text;html=1;align=center;verticalAlign=middle;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;fontStyle=1;fontSize=15;" vertex="1" parent="1">
+          <mxGeometry x="15" y="1560" width="80" height="30" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>