[#98] add iox2 services cli

[orecham]

Notes for Reviewer

• enables commands iox2 services list and iox2 services details
• the default output is RON but can be switched to JSON or YAML using a CLI option
  • this is to enable programatic parsing of the cli output
  • additional formats can be added via serde
• usage:

iox2-services

$ iox2 services --help
Query information about iceoryx2 services

Usage: iox2-services [OPTIONS] [COMMAND]

Options:
  -f, --format <FORMAT>  [possible values: RON, JSON, YAML]
  -h, --help             Print help
  -V, --version          Print version

Commands:
  list     List all existing services
  details  Show details of an existing service

iox2-services list

$ iox2 services list --help
List all existing services

Usage: iox2-services list [OPTIONS]

Options:
  -f, --format <FORMAT>  [possible values: RON, JSON, YAML]
  -h, --help             Print help

$ iox2 services list
[
    PublishSubscribe("Behavior Planner"),
    Event("Behavior Planner"),
    PublishSubscribe("Euclidean Cluster Detector"),
    Event("Euclidean Cluster Detector"),
    PublishSubscribe("Euclidean Cluster Settings"),
    Event("Euclidean Cluster Settings"),
    PublishSubscribe("Front Lidar Driver"),
    Event("Front Lidar Driver"),
    PublishSubscribe("Front Points Transformer"),
    Event("Front Points Transformer"),
    PublishSubscribe("Lane Planner"),
    Event("Lane Planner"),
    PublishSubscribe("Lanelet2Global Planner"),
    Event("Lanelet2Global Planner"),
    PublishSubscribe("Lanelet2Map"),
    Event("Lanelet2Map"),
    PublishSubscribe("Lanelet2Map Loader"),
    Event("Lanelet2Map Loader"),
    PublishSubscribe("MPC Controller"),
    Event("MPC Controller"),
    PublishSubscribe("NDT Localizer"),
    Event("NDT Localizer"),
    PublishSubscribe("Object Collision Estimator"),
    Event("Object Collision Estimator"),
    PublishSubscribe("Parking Planner"),
    Event("Parking Planner"),
    PublishSubscribe("Point Cloud Fusion"),
    Event("Point Cloud Fusion"),
    PublishSubscribe("Point Cloud Map"),
    Event("Point Cloud Map"),
    PublishSubscribe("Point Cloud Map Loader"),
    Event("Point Cloud Map Loader"),
    PublishSubscribe("Ray Ground Filter"),
    Event("Ray Ground Filter"),
    PublishSubscribe("Rear Lidar Driver"),
    Event("Rear Lidar Driver"),
    PublishSubscribe("Rear Points Transformer"),
    Event("Rear Points Transformer"),
    PublishSubscribe("Vehicle Interface"),
    Event("Vehicle Interface"),
    PublishSubscribe("Visualizer"),
    Event("Visualizer"),
    PublishSubscribe("Voxel Grid Downsampler"),
    Event("Voxel Grid Downsampler"),
]

$ iox2 services list -f JSON
[
  {
    "PublishSubscribe": "Behavior Planner"
  },
  {
    "Event": "Behavior Planner"
  },
  {
    "PublishSubscribe": "Euclidean Cluster Detector"
  },
  {
    "Event": "Euclidean Cluster Detector"
  },
  {
    "PublishSubscribe": "Euclidean Cluster Settings"
  },
  {
    "Event": "Euclidean Cluster Settings"
  },
  {
    "PublishSubscribe": "Front Lidar Driver"
  },
  {
    "Event": "Front Lidar Driver"
  },
  {
    "PublishSubscribe": "Front Points Transformer"
  },
  {
    "Event": "Front Points Transformer"
  },
  {
    "PublishSubscribe": "Lane Planner"
  },
  {
    "Event": "Lane Planner"
  },
  {
    "PublishSubscribe": "Lanelet2Global Planner"
  },
  {
    "Event": "Lanelet2Global Planner"
  },
  {
    "PublishSubscribe": "Lanelet2Map"
  },
  {
    "Event": "Lanelet2Map"
  },
  {
    "PublishSubscribe": "Lanelet2Map Loader"
  },
  {
    "Event": "Lanelet2Map Loader"
  },
  {
    "PublishSubscribe": "MPC Controller"
  },
  {
    "Event": "MPC Controller"
  },
  {
    "PublishSubscribe": "NDT Localizer"
  },
  {
    "Event": "NDT Localizer"
  },
  {
    "PublishSubscribe": "Object Collision Estimator"
  },
  {
    "Event": "Object Collision Estimator"
  },
  {
    "PublishSubscribe": "Parking Planner"
  },
  {
    "Event": "Parking Planner"
  },
  {
    "PublishSubscribe": "Point Cloud Fusion"
  },
  {
    "Event": "Point Cloud Fusion"
  },
  {
    "PublishSubscribe": "Point Cloud Map"
  },
  {
    "Event": "Point Cloud Map"
  },
  {
    "PublishSubscribe": "Point Cloud Map Loader"
  },
  {
    "Event": "Point Cloud Map Loader"
  },
  {
    "PublishSubscribe": "Ray Ground Filter"
  },
  {
    "Event": "Ray Ground Filter"
  },
  {
    "PublishSubscribe": "Rear Lidar Driver"
  },
  {
    "Event": "Rear Lidar Driver"
  },
  {
    "PublishSubscribe": "Rear Points Transformer"
  },
  {
    "Event": "Rear Points Transformer"
  },
  {
    "PublishSubscribe": "Vehicle Interface"
  },
  {
    "Event": "Vehicle Interface"
  },
  {
    "PublishSubscribe": "Visualizer"
  },
  {
    "Event": "Visualizer"
  },
  {
    "PublishSubscribe": "Voxel Grid Downsampler"
  },
  {
    "Event": "Voxel Grid Downsampler"
  }
]

iox2-services details

$ iox2 services details --help
Show details of an existing service

Usage: iox2-services details [OPTIONS] <SERVICE>

Arguments:
  <SERVICE>  Name of the service e.g. "My Service"

Options:
  -p, --pattern <PATTERN>  [default: All] [possible values: PublishSubscribe, Event, All]
  -f, --format <FORMAT>    [possible values: RON, JSON, YAML]
  -h, --help               Print help

$ iox2 services details "Behavior Planner"
(
    service_id: "1791b25d71a9a751adf98957c52377982fee223b",
    service_name: "Behavior Planner",
    attributes: ([]),
    pattern: (
        messaging_pattern: "PublishSubscribe",
        max_subscribers: 8,
        max_publishers: 2,
        max_nodes: 20,
        history_size: 1,
        subscriber_max_buffer_size: 2,
        subscriber_max_borrowed_samples: 2,
        enable_safe_overflow: true,
        message_type_details: (
            header: (
                variant: FixedSize,
                type_name: "iceoryx2::service::header::publish_subscribe::Header",
                size: 32,
                alignment: 8,
            ),
            user_header: (
                variant: FixedSize,
                type_name: "()",
                size: 0,
                alignment: 1,
            ),
            payload: (
                variant: FixedSize,
                type_name: "iceoryx2_reference_system::Data<128>",
                size: 128,
                alignment: 1,
            ),
        ),
    ),
    nodes: Some((
        num: 3,
        details: [
            (
                state: Alive,
                id: ((
                    pid: 156364,
                    seconds: 1726404926,
                    nanoseconds: 114450167,
                    counter: 0,
                )),
                name: Some(""),
                executable: Some("iceoryx2-reference-system"),
            ),
            (
                state: Alive,
                id: ((
                    pid: 156378,
                    seconds: 1726404926,
                    nanoseconds: 115884241,
                    counter: 0,
                )),
                name: Some(""),
                executable: Some("iceoryx2-reference-system"),
            ),
            (
                state: Alive,
                id: ((
                    pid: 156382,
                    seconds: 1726404926,
                    nanoseconds: 116264541,
                    counter: 0,
                )),
                name: Some(""),
                executable: Some("iceoryx2-reference-system"),
            ),
        ],
    )),
)(
    service_id: "06dca27efd01e543477845338295f9280369e03b",
    service_name: "Behavior Planner",
    attributes: ([]),
    pattern: (
        messaging_pattern: "Event",
        max_notifiers: 16,
        max_listeners: 16,
        max_nodes: 36,
        event_id_max_value: 32,
    ),
    nodes: Some((
        num: 3,
        details: [
            (
                state: Alive,
                id: ((
                    pid: 156364,
                    seconds: 1726404926,
                    nanoseconds: 114450167,
                    counter: 0,
                )),
                name: Some(""),
                executable: Some("iceoryx2-reference-system"),
            ),
            (
                state: Alive,
                id: ((
                    pid: 156378,
                    seconds: 1726404926,
                    nanoseconds: 115884241,
                    counter: 0,
                )),
                name: Some(""),
                executable: Some("iceoryx2-reference-system"),
            ),
            (
                state: Alive,
                id: ((
                    pid: 156382,
                    seconds: 1726404926,
                    nanoseconds: 116264541,
                    counter: 0,
                )),
                name: Some(""),
                executable: Some("iceoryx2-reference-system"),
            ),
        ],
    )),
)

$ iox2 services details "Behavior Planner" -p Event
(
    service_id: "06dca27efd01e543477845338295f9280369e03b",
    service_name: "Behavior Planner",
    attributes: ([]),
    pattern: (
        messaging_pattern: "Event",
        max_notifiers: 16,
        max_listeners: 16,
        max_nodes: 36,
        event_id_max_value: 32,
    ),
    nodes: Some((
        num: 3,
        details: [
            (
                state: Alive,
                id: ((
                    pid: 156364,
                    seconds: 1726404926,
                    nanoseconds: 114450167,
                    counter: 0,
                )),
                name: Some(""),
                executable: Some("iceoryx2-reference-system"),
            ),
            (
                state: Alive,
                id: ((
                    pid: 156378,
                    seconds: 1726404926,
                    nanoseconds: 115884241,
                    counter: 0,
                )),
                name: Some(""),
                executable: Some("iceoryx2-reference-system"),
            ),
            (
                state: Alive,
                id: ((
                    pid: 156382,
                    seconds: 1726404926,
                    nanoseconds: 116264541,
                    counter: 0,
                )),
                name: Some(""),
                executable: Some("iceoryx2-reference-system"),
            ),
        ],
    )),
)

Pre-Review Checklist for the PR Author

1. Add sensible notes for the reviewer
2. PR title is short, expressive and meaningful
3. Relevant issues are linked in the References section
4. Every source code file has a copyright header with SPDX-License-Identifier: Apache-2.0 OR MIT
5. Branch follows the naming format (iox2-123-introduce-posix-ipc-example)
6. Commits messages are according to this guideline
   • Commit messages have the issue ID ([#123] Add posix ipc example)
   • Commit author matches Eclipse Contributor Agreement (and ECA is signed)
7. Tests follow the best practice for testing
8. Changelog updated in the unreleased section including API breaking changes
9. Assign PR to reviewer
10. All checks have passed (except task-list-completed)

Checklist for the PR Reviewer

• Commits are properly organized and messages are according to the guideline
• Unit tests have been written for new behavior
• Public API is documented
• PR title describes the changes

Post-review Checklist for the PR Author

1. All open points are addressed and tracked via issues

References

Relates #98

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 79.43%. Comparing base (2d1f01d) to head (02fee0d).
Report is 24 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #371      +/-   ##
==========================================
- Coverage   79.54%   79.43%   -0.12%     
==========================================
  Files         193      193              
  Lines       22716    22716              
==========================================
- Hits        18070    18045      -25     
- Misses       4646     4671      +25     

see 6 files with indirect coverage changes

[elfenpiff]

@orecham nice work! Could you add please the following features:

• iox2 service list:

  • output is sorted by service name
  • you add the the messaging pattern in front of the service like [event] MyServiceName or [publish-subscribe] MyServiceName. Maybe with spaces in between [event] and the service name so that every name aligns in the same column.

• iox2 service details MyServiceName

  • if there are two services running with the same name but different messaging pattern then it shows only the publish-subscribe version of it

• Can you please add readme into iceoryx2-cli/README.md and describe there quickly how to use the cli. I tried cargo run --bin iox2 -- services list and it failed by stating that services was unknown. I could use it with cargo run --bin iox2-services -- list but I think this is not the intended use.

[orecham]

@orecham nice work! Could you add please the following features:

• iox2 service list:

  • output is sorted by service name
  • you add the the messaging pattern in front of the service like [event] MyServiceName or [publish-subscribe] MyServiceName. Maybe with spaces in between [event] and the service name so that every name aligns in the same column.

• iox2 service details MyServiceName

  • if there are two services running with the same name but different messaging pattern then it shows only the publish-subscribe version of it

• Can you please add readme into iceoryx2-cli/README.md and describe there quickly how to use the cli. I tried cargo run --bin iox2 -- services list and it failed by stating that services was unknown. I could use it with cargo run --bin iox2-services -- list but I think this is not the intended use.

@elfenpiff I have overhauled the implementation to address the findings:

1. structs to represent the CLI output are now defined in the associated CLI crate
   1. all modifications and additions to structs in the iceoryx2 crate have been reverted
   2. the cli output does not exactly match the content of the iceoryx2 structs but instead extracts only the relevant details that make sense for the cli command
2. list output is now ordered by service name
   1. services with the same name but different messaging pattern are adjacent
   2. an enum is used for the short description of the service so the messaging pattern is included in the list output
      1. see the description for an example
3. iox2-services details now prints details for all services matching the name
   1. an option to filter this output by messaging pattern is included
      1. see the description for an example
4. regarding the readme, it would be nice to avoid needing to manually maintain the documentation separate from the CLI help
   1. the issue you faced is probably because you were using the iox2 entrypoint
   2. when using the entrypoint, development builds have a suffix appended to them depending on the target configuration (e.g. services -> services-debug
   3. you can see the names that iox2 maps to these using iox2 --list
   4. to be honest I think this approach is not as nice as it could be, but there needs to be a way to distinguish debug and release builds with the same name and my time box to work on this has run out
      1. can be revisited later

[orecham]

@elfenpiff Note there are some tweaks to the implementation here: 0e109d3

Mainly:

1. Better documentation
2. Better structuring
3. Ability to filter iox2 services list by messaging pattern

[orecham]

@elfenpiff Release notes added here: 1512f6f