Allow providing launch args to include using let in frontends (#848)

Signed-off-by: Christophe Bedard <[email protected]>

Author: christophebedard

launch/launch/actions/include_launch_description.py

@@ -68,6 +68,58 @@ class IncludeLaunchDescription(Action):
     Conditionally included launch arguments that do not have a default value
     will eventually raise an error if this best effort argument checking is
     unable to see an unsatisfied argument ahead of time.
+
+    For example, to include ``my_pkg``'s ``other_launch.py`` and set launch arguments for it:
+
+    .. code-block:: python
+
+        def generate_launch_description():
+            return ([
+                SetLaunchConfiguration('arg1', 'value1'),
+                IncludeLaunchDescription(
+                    AnyLaunchDescriptionSource([
+                        PathJoinSubstitution([
+                            FindPackageShare('my_pkg'),
+                            'launch',
+                            'other_launch.py',
+                        ]),
+                    ]),
+                    launch_arguments={
+                        'other_arg1': LaunchConfiguration('arg1'),
+                        'other_arg2': 'value2',
+                    }.items(),
+                ),
+            ])
+
+    .. code-block:: xml
+
+        <launch>
+            <let name="arg1" value="value1" />
+            <include file="$(find-pkg-share my_pkg)/launch/other_launch.py">
+                <let name="other_arg1" value="$(var arg1)" />
+                <let name="other_arg2" value="value2" />
+            </include>
+        </launch>
+
+    .. code-block:: yaml
+
+        launch:
+        - let:
+            name: 'arg1'
+            value: 'value1'
+        - include:
+            file: '$(find-pkg-share my_pkg)/launch/other_launch.py'
+            let:
+                - name: 'other_arg1'
+                  value: '$(var arg1)'
+                - name: 'other_arg2'
+                  value: 'value2'
+
+    .. note::
+
+        While frontends currently support both ``let`` and ``arg`` for launch arguments, they are
+        both converted into ``SetLaunchConfiguration`` actions (``let``). The same launch argument
+        should not be defined using both ``let`` and ``arg``.
     """
 
     def __init__(
@@ -94,8 +146,14 @@ def parse(cls, entity: Entity, parser: Parser
         _, kwargs = super().parse(entity, parser)
         file_path = parser.parse_substitution(entity.get_attr('file'))
         kwargs['launch_description_source'] = file_path
-        args = entity.get_attr('arg', data_type=List[Entity], optional=True)
-        if args is not None:
+        args = []
+        args_arg = entity.get_attr('arg', data_type=List[Entity], optional=True)
+        if args_arg is not None:
+            args.extend(args_arg)
+        args_let = entity.get_attr('let', data_type=List[Entity], optional=True)
+        if args_let is not None:
+            args.extend(args_let)
+        if args:
             kwargs['launch_arguments'] = [
                 (
                     parser.parse_substitution(e.get_attr('name')),

launch_xml/test/launch_xml/test_include.py

@@ -26,24 +26,32 @@
 
 
 def test_include():
-    """Parse node xml example."""
-    # Always use posix style paths in launch XML files.
+    """Parse include XML example."""
     path = (Path(__file__).parent / 'executable.xml').as_posix()
     xml_file = \
         """\
         <launch>
-            <include file="{}"/>
+            <let name="main_baz" value="BAZ" />
+            <include file="{}">
+                <arg name="foo" value="FOO" />
+                <arg name="baz" value="overwritten" />
+                <let name="bar" value="BAR" />
+                <let name="baz" value="$(var main_baz)" />
+            </include>
         </launch>
         """.format(path)  # noqa: E501
     xml_file = textwrap.dedent(xml_file)
     root_entity, parser = load_no_extensions(io.StringIO(xml_file))
     ld = parser.parse_description(root_entity)
-    include = ld.entities[0]
+    include = ld.entities[1]
     assert isinstance(include, IncludeLaunchDescription)
     assert isinstance(include.launch_description_source, AnyLaunchDescriptionSource)
     ls = LaunchService(debug=True)
     ls.include_launch_description(ld)
     assert 0 == ls.run()
+    assert ls.context.launch_configurations['foo'] == 'FOO'
+    assert ls.context.launch_configurations['bar'] == 'BAR'
+    assert ls.context.launch_configurations['baz'] == 'BAZ'
 
 
 if __name__ == '__main__':

launch_yaml/test/launch_yaml/executable.yaml

@@ -0,0 +1,14 @@
+launch:
+- executable:
+    cmd: 'ls -l -a -s'
+    cwd: '/'
+    name: 'my_ls'
+    shell: true
+    output: 'log'
+    emulate_tty: true
+    sigkill_timeout: 4.0
+    sigterm_timeout: 7.0
+    launch-prefix: "$(env LAUNCH_PREFIX '')"
+    env:
+        - name: 'var'
+          value: '1'

launch_yaml/test/launch_yaml/test_include.py

@@ -0,0 +1,65 @@
+# Copyright 2025 Open Source Robotics Foundation, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Test parsing an include action."""
+
+import io
+from pathlib import Path
+import textwrap
+
+from launch import LaunchService
+from launch.actions import IncludeLaunchDescription
+from launch.launch_description_sources import AnyLaunchDescriptionSource
+
+from parser_no_extensions import load_no_extensions
+
+
+def test_include():
+    """Parse include YAML example."""
+    path = (Path(__file__).parent / 'executable.yaml').as_posix()
+    yaml_file = \
+        """\
+        launch:
+        - let:
+            name: 'main_baz'
+            value: 'BAZ'
+        - include:
+            file: '{}'
+            arg:
+                - name: 'foo'
+                  value: 'FOO'
+                - name: 'baz'
+                  value: 'overwritten'
+            let:
+                - name: 'bar'
+                  value: 'BAR'
+                - name: 'baz'
+                  value: '$(var main_baz)'
+        """.format(path)  # noqa: E501
+    yaml_file = textwrap.dedent(yaml_file)
+    root_entity, parser = load_no_extensions(io.StringIO(yaml_file))
+    ld = parser.parse_description(root_entity)
+    include = ld.entities[1]
+    assert isinstance(include, IncludeLaunchDescription)
+    assert isinstance(include.launch_description_source, AnyLaunchDescriptionSource)
+    ls = LaunchService(debug=True)
+    ls.include_launch_description(ld)
+    assert 0 == ls.run()
+    assert ls.context.launch_configurations['foo'] == 'FOO'
+    assert ls.context.launch_configurations['bar'] == 'BAR'
+    assert ls.context.launch_configurations['baz'] == 'BAZ'
+
+
+if __name__ == '__main__':
+    test_include()