Skip to content

Launch preferences update: XML-first, .launch extensions, Python launchfile declarative style #5143

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 14 commits into
base: rolling
Choose a base branch
from

Conversation

emersonknapp
Copy link
Contributor

Make a fairly opinionated pass on the Launch documentation and tutorials.

Main points:

  1. Reduce repetition, use literalinclude to include large blocks especially ones that are repeated in explanations
  2. Recommend and apply the .launch extension in all uses except references to actual existing demo files in other packages.
  3. Move multilingual launch demos to XML, where possible.
  4. By example, use AnyLaunchSubstitution in all Python cases to match XML/YAML usage and move toward a less opinionated default launch usage pattern.

I believe the potentially most contentious part will be the .launch extension, my justification is stated in Launch File Different Formats

While it is not required, we recommend that you name all launch files with the .launch extension, regardless of the language they are written in.

There is historical content that uses the _launch.py, _launch.xml, and _launch.yaml extensions, but this is no longer necessary or recommended as it obfuscates the usage.

Launch files should be considered part of the exposed interface of your package, and your users shouldn't have to know or care which language you used to implement a particular file, just like with your nodes.
Nor should you be tied to keeping it in that format forever!
As long as it has the .launch suffix with an informative name, the caller knows that it is a launch file, and the launch system will autodetect the format as needed.
You can mix and match formats without any issues.

@christophebedard
Copy link
Member

christophebedard commented Mar 21, 2025

Recommend and apply the .launch extension in all uses except references to actual existing demo files in other packages.

Small note:

Python launch files (paths) are only meant be to autocompleted by ros2 launch ... if they end with launch.py. However, it still (probably) gets autocompleted if at least one of the frontends is available, since both the YAML frontend and the XML frontend declare launch as a valid extension. Both frontends are available if the package depends on ros2launch, which is recommended in the "Creating a launch file" tutorial. Again, this is really about autocompletion and not about it working or not.

We could change that if we wanted to, of course.

…up style, dedifferentiate languages by using .launch extension for all

Signed-off-by: Emerson Knapp <[email protected]>
Signed-off-by: Emerson Knapp <[email protected]>
Signed-off-by: Emerson Knapp <[email protected]>
Signed-off-by: Emerson Knapp <[email protected]>
Signed-off-by: Emerson Knapp <[email protected]>
Signed-off-by: Emerson Knapp <[email protected]>
Signed-off-by: Emerson Knapp <[email protected]>
@emersonknapp emersonknapp force-pushed the emersonknapp/python-launchfile-styling branch from e58d418 to 1004303 Compare March 21, 2025 15:25
@emersonknapp emersonknapp marked this pull request as draft March 21, 2025 17:21
@emersonknapp
Copy link
Contributor Author

Converting to draft but leaving open for now. I am going to pull independent pieces out to make incremental progress on the less-dicey bits.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants