How ros2/launch works
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)