# ros2/launch architecture

> Architecture diagram of the GitHub repository ros2/launch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ros2/launch
- Repository: https://github.com/ros2/launch

## Overview

##### Project type and purpose
- This is a multi-package Python library ecosystem, part of ROS 2, providing a core “launch” framework for spawning and coordinating processes (nodes) and writing multi-process tests.
- It consists of:
– launch: the core API (descriptions, actions, conditions, substitutions, event system, service loop)
– launch_xml and launch_yaml: file-format extensions implementing the common LaunchDescriptionSource interface
– launch_pytest: a pytest plugin exposing fixtures to drive launches in pytest tests
– launch_testing: higher-level testing utilities that build on launch_pytest for integration testing
– launch_testing_ament_cmake: CMake helper to integrate launch tests into a ROS 2 CMake build
– test_launch_testing: example/dummy tests demonstrating launch_testing usage

##### File structure
- launch/… subdivides into:
– frontend (parsing and substitution resolution)
– actions (atomic building blocks: execute_process, group_action, timer_action, etc.)
– conditions (if/unless, equals/not_equals)
– events and event_handlers (on_process_start, on_shutdown, etc.)
– substitutions (environment vars, command outputs, file contents, Python expressions)
– utilities (type checking, signal management, entity visiting)
– top-level orchestration: LaunchDescription, LaunchService, LaunchContext
- launch_xml/ and launch_yaml/ each implement a parser + entity definitions + “launch_description_source” plugin
- launch_pytest/ defines hooks, fixtures, and tooling to integrate LaunchService into pytest’s lifecycle
- launch_testing/ layers custom “ready” actions, assertions, and decorators on top of launch_pytest fixtures
- launch_testing_ament_cmake provides CMake scripts to invoke launch_testing tests in a ROS 2 build
- test_*/ directories contain unit tests for each module and example usages

##### README for additional insights
- Confirms the mission: tools for launching multiple processes + writing multi-process tests
- Points to conceptual docs (architecture.rst in launch/doc/source) describing event loops, actions, and the LaunchDescriptionSource plugin model

##### Diagramming recommendations
- Use clear labels (e.g., “Core LaunchService”, “Action: ExecuteProcess”, “Plugin: XML Loader”)
– from LaunchDescriptionSource → Core Engine (to show registration)
– from Actions → EventQueue → EventHandlers
– from pytest fixtures → Core Engine (start/stop)
– Core framework (e.g., blue)
– Parsers/plugins (green)
– Testing integrations (orange)
– Build-system/CMake (gray)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Framework
    subgraph "Core Framework"
        direction TB
        CoreEngine["Core LaunchService & API"]:::core
        Frontend["Frontend Parsing & Substitution Resolution"]:::core
        Actions["Actions Module"]:::core
        Conditions["Conditions Module"]:::core
        Substitutions["Substitutions Module"]:::core
        Utilities["Utilities"]:::core
        Events["Event Dispatch & Handlers"]:::core
        LDSInterface["LaunchDescriptionSource Interface"]:::core
    end

    %% Parsers and Plugins
    subgraph "Parsers / Plugins"
        direction TB
        XMLPlugin["Plugin: XML Loader"]:::parser
        XMLParser["XML Parser"]:::parser
        XMLEntities["XML Entities"]:::parser
        YAMLPlugin["Plugin: YAML Loader"]:::parser
        YAMLParser["YAML Parser"]:::parser
        YAMLEntities["YAML Entities"]:::parser
    end

    %% Testing Integration
    subgraph "Testing Integration"
        direction TB
        PytestPlugin["pytest Plugin Integration"]:::test
        PytestFixtures["pytest Fixtures"]:::test
        PytestTools["launch_pytest Tools"]:::test
        LT_Actions["launch_testing Actions & Decorators"]:::test
        LT_Asserts["launch_testing Asserts"]:::test
        LT_Decorator["launch_testing Decorators"]:::test
        LT_Hooks["launch_testing pytest Hooks"]:::test
        LT_Runner["launch_testing Test Runner"]:::test
        ExampleTests["Example / Dummy Tests"]:::test
    end

    %% Build Integration
    subgraph "Build-System Integration"
        direction TB
        CMakeHelperAdd["add_launch_test.cmake"]:::build
        CMakeLists["CMakeLists.txt"]:::build
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        Python["Python Runtime"]:::external
        Pytest["pytest"]:::external
        Lark["lark"]:::external
        PyYAML["pyyaml"]:::external
        ROS2["ROS 2 Middleware"]:::external
    end

    %% Relationships
    Frontend -->|provides LaunchDescription| CoreEngine
    LDSInterface -->|registers plugins| CoreEngine
    XMLPlugin --> LDSInterface
    YAMLPlugin --> LDSInterface
    XMLPlugin -->|uses| XMLParser
    XMLParser -->|defines| XMLEntities
    YAMLPlugin -->|uses| YAMLParser
    YAMLParser -->|defines| YAMLEntities

    CoreEngine --> Actions
    CoreEngine --> Conditions
    CoreEngine --> Substitutions
    CoreEngine --> Utilities
    Actions --> Events
    Events --> Utilities

    PytestFixtures -->|start/stop| CoreEngine
    PytestPlugin --> PytestFixtures
    PytestPlugin -->|provides| PytestTools
    LT_Actions --> PytestFixtures
    LT_Asserts --> PytestFixtures
    LT_Decorator --> PytestFixtures
    LT_Hooks --> PytestPlugin
    LT_Runner --> LT_Hooks
    ExampleTests --> LT_Actions

    CMakeHelperAdd -->|invokes pytest| PytestPlugin
    CMakeLists --> CMakeHelperAdd

    Python --> CoreEngine
    Pytest --> PytestPlugin
    Lark --> XMLParser
    PyYAML --> YAMLParser
    ROS2 --> CoreEngine

    %% Click Events
    click CoreEngine "https://github.com/ros2/launch/tree/rolling/launch/launch"
    click Frontend "https://github.com/ros2/launch/tree/rolling/launch/launch/frontend"
    click Actions "https://github.com/ros2/launch/tree/rolling/launch/launch/actions"
    click Conditions "https://github.com/ros2/launch/tree/rolling/launch/launch/conditions"
    click Events "https://github.com/ros2/launch/tree/rolling/launch/launch/events"
    click LDSInterface "https://github.com/ros2/launch/blob/rolling/launch/launch/launch_description_source.py"
    click XMLPlugin "https://github.com/ros2/launch/blob/rolling/launch_xml/launch_xml/launch_description_sources/xml_launch_description_source.py"
    click XMLParser "https://github.com/ros2/launch/blob/rolling/launch_xml/launch_xml/parser.py"
    click XMLEntities "https://github.com/ros2/launch/blob/rolling/launch_xml/launch_xml/entity.py"
    click YAMLPlugin "https://github.com/ros2/launch/blob/rolling/launch_yaml/launch_yaml/launch_description_sources/yaml_launch_description_source.py"
    click YAMLParser "https://github.com/ros2/launch/blob/rolling/launch_yaml/launch_yaml/parser.py"
    click YAMLEntities "https://github.com/ros2/launch/blob/rolling/launch_yaml/launch_yaml/entity.py"
    click PytestPlugin "https://github.com/ros2/launch/blob/rolling/launch_pytest/launch_pytest/plugin.py"
    click PytestFixtures "https://github.com/ros2/launch/blob/rolling/launch_pytest/launch_pytest/fixture.py"
    click PytestTools "https://github.com/ros2/launch/blob/rolling/launch_pytest/launch_pytest/tools/process.py"
    click LT_Actions "https://github.com/ros2/launch/tree/rolling/launch_testing/launch_testing/actions"
    click LT_Asserts "https://github.com/ros2/launch/tree/rolling/launch_testing/launch_testing/asserts"
    click LT_Decorator "https://github.com/ros2/launch/blob/rolling/launch_testing/launch_testing/decorator.py"
    click LT_Hooks "https://github.com/ros2/launch/blob/rolling/launch_testing/launch_testing/pytest/hooks.py"
    click LT_Runner "https://github.com/ros2/launch/blob/rolling/launch_testing/launch_testing/test_runner.py"
    click CMakeHelperAdd "https://github.com/ros2/launch/blob/rolling/launch_testing_ament_cmake/cmake/add_launch_test.cmake"
    click CMakeLists "https://github.com/ros2/launch/blob/rolling/launch_testing_ament_cmake/CMakeLists.txt"
    click ExampleTests "https://github.com/ros2/launch/tree/rolling/test_launch_testing/test/test_launch_testing/actions"

    %% Styles
    classDef core fill:#e0f3ff,stroke:#0066cc,color:#000
    classDef parser fill:#e6ffe6,stroke:#33aa33,color:#000
    classDef test fill:#fff0e0,stroke:#ff9900,color:#000
    classDef build fill:#f2f2f2,stroke:#666666,color:#000
    classDef external fill:#f7e6ff,stroke:#9933cc,color:#000
```
