From aeec9814967931ba06478e59efb20748aa32e7d6 Mon Sep 17 00:00:00 2001 From: Eric Cousineau Date: Fri, 18 Nov 2022 11:41:11 -0500 Subject: [PATCH 1/5] [doc] Update README to have some internal links Add note about ament index propagation Demote sections under ./ros2 Bazel details --- README.md | 11 +++++++---- bazel_ros2_rules/README.md | 11 +++++++++-- bazel_ros2_rules/ros2/README.md | 12 ++++++------ 3 files changed, 22 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 90c9f794..d2120918 100644 --- a/README.md +++ b/README.md @@ -7,10 +7,13 @@ The intended function of this repository is to provide the following ROS 2 capability: - - API for integration between Drake and ROS 2 components - - Bazel Starlark macros and tooling to enable ingesting (already built) ROS 2 - workspaces from either installed locations or tarballs. - - Examples for using these APIs and Bazel macros. +- API for integration between Drake and ROS 2 components. See the + `drake_ros_*` packages. +- Bazel Starlark macros and tooling to enable ingesting (already built) ROS 2 + workspaces from either installed locations or tarballs in + [`bazel_ros2_rules`](./bazel_ros2_rules). +- Examples for using these APIs and Bazel macros in + [`ros2_example_bazel_installed`](./ros2_example_bazel_installed). In addition to ROS 2, this repository also provides some tools for interacting with the Gazebo and broader ROS ecosystem: diff --git a/bazel_ros2_rules/README.md b/bazel_ros2_rules/README.md index 7f5c3757..1bc5a36f 100644 --- a/bazel_ros2_rules/README.md +++ b/bazel_ros2_rules/README.md @@ -5,8 +5,15 @@ This project provides rules to build and run against a ROS 2 distribution from B ## Features - Automatic ROS 2 overlay scraping, `symlink` or `merge`-installed -- ROS 2 aware C++/Python binaries (e.g. `dload` capable) -- ROS 2 interface generation within Bazel +- ROS 2 aware C++/Python binaries (e.g. `dload` capable via shims) +- ROS 2 interface generation within Bazel. Ament index manifests are + also generated against any ROS 2 dependencies (`data` or `deps` for `cc` and + `py` rules). + - For example, you can generate custom message types, and them as + dependencies, run `ros2 interface list` under Bazel and see your custom + generated types. + +More detail about these features are listed in [`./ros2`](./ros2). ## Platform support diff --git a/bazel_ros2_rules/ros2/README.md b/bazel_ros2_rules/ros2/README.md index 1eea4f28..87100a76 100644 --- a/bazel_ros2_rules/ros2/README.md +++ b/bazel_ros2_rules/ros2/README.md @@ -1,4 +1,4 @@ -## Infrastructure to use ROS 2 from a Bazel workspace +# Infrastructure to use ROS 2 from a Bazel Workspace This package encapsulates all the machinery to pull a ROS 2 workspace install space or a subset thereof as a Bazel repository. Both system-installed binary @@ -25,7 +25,7 @@ This rule heavily relies on two Python packages: build configuration of pre-installed CMake projects for Bazel packages to depend on. -### Repository layout +## Repository Layout A ROS 2 local repository has the following layout: @@ -44,7 +44,7 @@ A ROS 2 local repository has the following layout: Note that all files and subdirectories that are mere implementation details have been excluded from this layout. -#### Targets +### Targets For each package in the underlying ROS 2 workspace install space, depending on the artifacts it generates, the following targets may be found at the root @@ -77,7 +77,7 @@ the artifacts it generates, the following targets may be found at the root sourcing the workspace install space). These executables are exposed as Python binaries for simplicty. -#### Rules +### Rules To build C++ binaries and tests that depend on ROS 2, `ros_cc_binary` and `ros_cc_test` rules are available in the `ros_cc.bzl` file. These rules, @@ -103,7 +103,7 @@ the same file. By default, these naming conventions allow downstream `rosidl_interfaces_group` rules to depend on upstream `rosidl_interface_group` rules. -#### Tools +### Tools The `rmw_isolation` subpackage provides C++ and Python `isolate_rmw_by_path` APIs to enforce RMW network isolation. To that end, a unique path must be @@ -114,7 +114,7 @@ provided (such as Bazel's `$TEST_TMPDIR`). Tier 1 `rmw` implementations only. Collision rates are below 1% but not null. Use with care. -#### Metadata +### Metadata The `distro.bzl` file bears relevant ROS 2 workspace metadata for rules, tools, and downstream packages to use. From c333330d16cc1e82ba3bdc53ac91c6b87328e9e1 Mon Sep 17 00:00:00 2001 From: Eric Cousineau Date: Fri, 18 Nov 2022 11:41:35 -0500 Subject: [PATCH 2/5] [doc] Add "Alternatives" for Bazel and ROS 2 workflows --- README.md | 2 ++ bazel_ros2_rules/README.md | 3 +++ bazel_ros2_rules/ros2/README.md | 34 +++++++++++++++++++++++++++++++++ 3 files changed, 39 insertions(+) diff --git a/README.md b/README.md index d2120918..67e50a83 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,8 @@ capability: - Bazel Starlark macros and tooling to enable ingesting (already built) ROS 2 workspaces from either installed locations or tarballs in [`bazel_ros2_rules`](./bazel_ros2_rules). + - Be sure to read about + [alternative approaches](./bazel_ros2_rules/ros2/#alternatives). - Examples for using these APIs and Bazel macros in [`ros2_example_bazel_installed`](./ros2_example_bazel_installed). diff --git a/bazel_ros2_rules/README.md b/bazel_ros2_rules/README.md index 1bc5a36f..1651ebb0 100644 --- a/bazel_ros2_rules/README.md +++ b/bazel_ros2_rules/README.md @@ -2,6 +2,9 @@ This project provides rules to build and run against a ROS 2 distribution from Bazel. +Please be sure to review [Alternatives](./ros2#alternatives) for Bazel tooling +for use with the ROS 2 ecosystem. + ## Features - Automatic ROS 2 overlay scraping, `symlink` or `merge`-installed diff --git a/bazel_ros2_rules/ros2/README.md b/bazel_ros2_rules/ros2/README.md index 87100a76..7b33130a 100644 --- a/bazel_ros2_rules/ros2/README.md +++ b/bazel_ros2_rules/ros2/README.md @@ -118,3 +118,37 @@ provided (such as Bazel's `$TEST_TMPDIR`). The `distro.bzl` file bears relevant ROS 2 workspace metadata for rules, tools, and downstream packages to use. + +## Alternatives + +### `ApexAI/rules_ros` + +[`ApexAI/rules_ros`](https://github.com/ApexAI/rules_ros) is another great +method of ingesting ROS 2 into a Bazel-ified workflow. At present, it has a +[`vcstool`](https://github.com/dirk-thomas/vcstool)-like manifest of +repositories that will be used to fetch packages and build them from source. + +The benefit from this approach is being able to fully control the source build, +configuration flags, etc., for ensuring a build is consistent and easily +reconfigurable. + +The (present) possible con to this approach is scalability. You must presently +provide your own set of external `{repo}.BUILD.bazel` rules that reflect the +ament operations expressed in CMake. Until the `ament` / ROS 2 build ecosystem +provides scaffolding or affordances for Bazel tooling, and until pacakges +provide their own (tested) Bazel tooling, this may be a tall (but still +tractable) hill to climb. + +### Contrast + +`RobotLocomotion/drake-ros/bazel_ros2_rules` leverages a prebuilt workspace, be +it from a local path, a tarball, or some other Bazel `repository_rule` +provenance (e.g. +[`RobotLocomotion/bazel-external-data`](https://github.com/RobotLocomotion/bazel-external-data). + +The pro is that only scraping needs to be +done of CMake metadata, and thus can be more scalable, especially for complex +package ecosystems like RViz2 related things. + +The con is that this scraping can be slow, is currently in the analysis phase, +and does not admit source-level configurability. From 2ca6ff8883bb837ad958c0d0aca1b5115b01de73 Mon Sep 17 00:00:00 2001 From: Eric Cousineau Date: Sun, 20 Nov 2022 15:47:32 -0500 Subject: [PATCH 3/5] fixup! add in link / initial analysis of mvukov/rules_ros2 --- bazel_ros2_rules/ros2/README.md | 56 ++++++++++++++++++++++++++++----- 1 file changed, 49 insertions(+), 7 deletions(-) diff --git a/bazel_ros2_rules/ros2/README.md b/bazel_ros2_rules/ros2/README.md index 7b33130a..5d2841ec 100644 --- a/bazel_ros2_rules/ros2/README.md +++ b/bazel_ros2_rules/ros2/README.md @@ -121,12 +121,18 @@ and downstream packages to use. ## Alternatives -### `ApexAI/rules_ros` +### `mvukov/rules_ros2` -[`ApexAI/rules_ros`](https://github.com/ApexAI/rules_ros) is another great -method of ingesting ROS 2 into a Bazel-ified workflow. At present, it has a -[`vcstool`](https://github.com/dirk-thomas/vcstool)-like manifest of -repositories that will be used to fetch packages and build them from source. +[`mvukov/rules_ros2`](https://github.com/mvukov/rules_ros2) provides an elegant +way of manually mapping a [`vcstool`](https://github.com/dirk-thomas/vcstool), +e.g. [`ros2.repos`](https://github.com/ros2/ros2/blob/rolling/ros2.repos), onto +a custom but simple manifest to then bootstrap into Bazel repository rules (and +the corresponding `BUILD` files) to build from source. + +Additionally, affordances are provided to leverage Python `pip` provisiong (via +[`rules_python`](https://github.com/bazelbuild/rules_python/)) and examples of +Docker container integration (via +[`rules_docker`](https://github.com/bazelbuild/rules_docker)). The benefit from this approach is being able to fully control the source build, configuration flags, etc., for ensuring a build is consistent and easily @@ -136,10 +142,23 @@ The (present) possible con to this approach is scalability. You must presently provide your own set of external `{repo}.BUILD.bazel` rules that reflect the ament operations expressed in CMake. Until the `ament` / ROS 2 build ecosystem provides scaffolding or affordances for Bazel tooling, and until pacakges -provide their own (tested) Bazel tooling, this may be a tall (but still +provide their own (tested) Bazel tooling, this may be a tall (but certainly tractable) hill to climb. -### Contrast +Additionally, some entry points need to be reflected into the codebase (e.g. +`ros2_topic.py`), which provides for nice flexibility, but at the cost of +duplication / redundancy w.r.t. upstream. + +### `ApexAI/rules_ros` + +[`ApexAI/rules_ros`](https://github.com/ApexAI/rules_ros) is another great +method of ingesting ROS 2 into a Bazel-ified workflow. At present, it has a +`vcstool`-like manifest of +repositories that will be used to fetch packages and build them from source. + +The pros and cons to this approach are similar to `mvukov/rules_ros2`. + +### This Repository (`RobotLocomotion/drake-ros/bazel_ros2_rules`) `RobotLocomotion/drake-ros/bazel_ros2_rules` leverages a prebuilt workspace, be it from a local path, a tarball, or some other Bazel `repository_rule` @@ -152,3 +171,26 @@ package ecosystems like RViz2 related things. The con is that this scraping can be slow, is currently in the analysis phase, and does not admit source-level configurability. + +#### Features + +From the above two examples (at present), the following features are in +`RobotLocomotion/bazel_ros2_rules` that may be missing from the others: + +- Host-based isolation (see `rmw_isolation` tooling here) +- Ament index analysis (e.g. using `ros2 interface list` in Bazel and seeing + your custom types) +- Examples leverage RViz from within a Bazel workspace +- Writing Python bindings in `pybind11` against other C++ libraries that have + their own bindings - e.g., [Drake](https://drake.mit.edu/). + - There is *some* affordance for leveraging `pybind11` against ROS 2 RMW + libraries. However, because the Python bindings do not leverage C++ + directly, but instead leverage the C-level interfaces, we get into an + awkward ground of mutually exclusive memory / resource management + paradigms. + +The other repos, however, have the following that `bazel_ros2_rules` is +missing: + +- Affordances for `ros2 launch` +- Launching from containers (Docker, Apptainer) From 0ef58e9b1187388655f315b5c48444ab45dbc478 Mon Sep 17 00:00:00 2001 From: Eric Cousineau Date: Sun, 20 Nov 2022 15:57:32 -0500 Subject: [PATCH 4/5] fixup! review --- bazel_ros2_rules/ros2/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bazel_ros2_rules/ros2/README.md b/bazel_ros2_rules/ros2/README.md index 5d2841ec..1cfd8ee1 100644 --- a/bazel_ros2_rules/ros2/README.md +++ b/bazel_ros2_rules/ros2/README.md @@ -141,7 +141,7 @@ reconfigurable. The (present) possible con to this approach is scalability. You must presently provide your own set of external `{repo}.BUILD.bazel` rules that reflect the ament operations expressed in CMake. Until the `ament` / ROS 2 build ecosystem -provides scaffolding or affordances for Bazel tooling, and until pacakges +provides scaffolding or affordances for Bazel tooling, and until packages provide their own (tested) Bazel tooling, this may be a tall (but certainly tractable) hill to climb. From c1f285ebd177bf58593a8328e3b05ef07c3424c5 Mon Sep 17 00:00:00 2001 From: Eric Cousineau Date: Tue, 29 Nov 2022 08:46:06 -0500 Subject: [PATCH 5/5] fixup! address review --- bazel_ros2_rules/ros2/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/bazel_ros2_rules/ros2/README.md b/bazel_ros2_rules/ros2/README.md index 1cfd8ee1..bf71c139 100644 --- a/bazel_ros2_rules/ros2/README.md +++ b/bazel_ros2_rules/ros2/README.md @@ -181,8 +181,8 @@ From the above two examples (at present), the following features are in - Ament index analysis (e.g. using `ros2 interface list` in Bazel and seeing your custom types) - Examples leverage RViz from within a Bazel workspace -- Writing Python bindings in `pybind11` against other C++ libraries that have - their own bindings - e.g., [Drake](https://drake.mit.edu/). +- Examples include Python bindings (via `pybind11`) against other C++ libraries + that have their own bindings - e.g., [Drake](https://drake.mit.edu/). - There is *some* affordance for leveraging `pybind11` against ROS 2 RMW libraries. However, because the Python bindings do not leverage C++ directly, but instead leverage the C-level interfaces, we get into an