[REP-2013] ROS 2 Rust Client Library Integration

rep-2013.rst

@@ -0,0 +1,103 @@
+REP: 2013
+Title: ROS 2 Client Library Integration
+Author: Steven! Ragnarok <[email protected]>
+Status: Draft
+Type: Informational
+Content-Type: text/x-rst
+Created: 21-Sep-2022
+Post-History: 21-Sep-2022
+
+
+Abstract
+========
+
+This REP will document, retroactively, the aspects and expectations of language-specific client libraries in ROS 2 in order to serve as a template for new language communities and client libraries which can be integrated into ROS.
+In particular this REP is an attempt to elaborate on the questions raised on ROS Discourse [1]_ regarding incorporating third-party client libraries into the ROS 2 core.
+
+
+Integration and Infrastructure
+==============================
+
+rosidl pipeline
+^^^^^^^^^^^^^^^
+
+TODO introduce the idl pipeline in a way that is accurate and succinct.
+Message packages in ROS contain generated code for supported languages to directly interact with message fields.
+The rosidl pipeline handles the process of generating language specific code for working with each supported runtime and typesupport.
+Generating and distributing code for a rosidl runtime on the ROS build farm requires the rosidl runtime and typesupport packages to be available when message packages are built.
+
+package build types
+^^^^^^^^^^^^^^^^^^^
+
+TODO hoist in some of the stuff common to colcon and bloom
+
+colcon
+^^^^^^
+
+colcon is the recommended build tool for ROS 2.
+It is highly extensible and support for nearly all package build types is provided by extensions rather than built into colcon core.
+Support for most build types is also separated into base support and ros-specific support so that colcon can be used with that build type with or without ROS.
+The prime examples here are colcon-cmake [2]_ and colcon-ros-cmake [3]_ which provide general support for CMake packages and some ROS specific behavior which builds on the existing CMake support.
+
+rosdep
+^^^^^^
+
+If your client library is associated with a language-specific package manager, it can be useful to support that language specific package manager in rosdep.
+In order for a package to be released on the ROS build farm, all of its dependencies must be satisifed either in the ROS distribution directly (sometimes referred to as vendoring) or available from the platform package manager.
+However, it is still useful to have rosdep support while packages are being developed and to support community members who may be working on packages that do not need to be released on the ROS build farm.
+
+
+bloom
+^^^^^
+
+When building binary packages we convert ROS package metadata into metadata for each target platform's specific packaging infrastructure.
+As a result, a pre-requisite to supporting client library packages in ROS is supporting the target language and library ecosystem in ROS 2's supported platforms.
+Bloom templates supporting the new build type associated with the client library language must be added to generate platform packaging infrastructure for use on the ROS build farm.
+
+At the moment, bloom is also responsible for injecting certain dependencies (such as typesupport and idl pipeline dependencies) into packages containing idl.
+Changes to the injected packages may be required in order to support additional client libraries or typesupports.
+
+ros_buildfarm
+^^^^^^^^^^^^^
+
+If everything else has been set up successfully, no additional changes should be required in the ros_buildfarm project since it uses the information generated by bloom for packaging jobs, and runs development, PR, and CI jobs with colcon.
+
+Languages and ecosystems
+========================
+
+  * C and C++ with CMake
+  * python and PyPI
+  * C and C++ with Meson
+  * Rust and Crates
+
+Alternative approaches
+======================
+
+  * document the existing gradle, node, and rust approaches
+
+References
+==========
+
+.. [1] Process for third-party client libraries to be incorporated into the core ROS 2 distribution
+   (https://discourse.ros.org/t/process-for-third-party-client-libraries-to-be-incorporated-into-the-core-ros-2-distribution/27325/)
+
+.. [2] colcon-cmake project on GitHub
+   (https://github.com/colcon/colcon-cmake)
+
+.. [3] colcon-ros-cmake project on GitHub
+   (https://github.com/colcon/colcon-ros-cmake)
+
+Copyright
+=========
+
+This document has been placed in the public domain.
+
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   coding: utf-8
+   End: