Merge branch 'main' into luca/parameter_service

Signed-off-by: Luca Della Vedova <[email protected]>

Author: luca-della-vedova

.github/workflows/rust.yml

@@ -37,21 +37,21 @@ jobs:
     container:
       image: ${{ matrix.docker_image }}
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
 
     - name: Search packages in this repository
       id: list_packages
       run: |
         echo ::set-output name=package_list::$(colcon list --names-only)
 
     - name: Setup ROS environment
-      uses: ros-tooling/setup-ros@v0.6
+      uses: ros-tooling/setup-ros@v0.7
       with:
         required-ros-distributions: ${{ matrix.ros_distribution }}
         use-ros2-testing: ${{ matrix.ros_distribution == 'rolling' }}
 
     - name: Setup Rust
-      uses: dtolnay/rust-toolchain@1.71.0
+      uses: dtolnay/rust-toolchain@1.74.0
       with:
         components: clippy, rustfmt
 
@@ -87,7 +87,12 @@ jobs:
         for path in $(colcon list | awk '$3 == "(ament_cargo)" { print $2 }'); do
         cd $path
         echo "Running clippy in $path"
-        cargo clippy --all-targets --all-features -- -D warnings
+        # Run clippy for all features except generate_docs (needed for docs.rs)
+        if [ "$(basename $path)" = "rclrs" ]; then
+          cargo clippy --all-targets -F default,dyn_msg -- -D warnings
+        else
+          cargo clippy --all-targets --all-features -- -D warnings
+        fi
         cd -
         done
 
@@ -98,7 +103,14 @@ jobs:
         for path in $(colcon list | awk '$3 == "(ament_cargo)" && $1 != "examples_rclrs_minimal_pub_sub" && $1 != "examples_rclrs_minimal_client_service" { print $2 }'); do
         cd $path
         echo "Running cargo test in $path"
-        cargo test --all-features
+        # Run cargo test for all features except generate_docs (needed for docs.rs)
+        if [ "$(basename $path)" = "rclrs" ]; then
+          cargo test -F default,dyn_msg
+        elif [ "$(basename $path)" = "rosidl_runtime_rs" ]; then
+          cargo test -F default
+        else
+          cargo test --all-features
+        fi
         cd -
         done
 

Dockerfile

@@ -12,7 +12,7 @@ RUN apt-get update && apt-get install -y \
     && rm -rf /var/lib/apt/lists/*
 
 # Install Rust and the cargo-ament-build plugin
-RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- --default-toolchain 1.71.0 -y
+RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- --default-toolchain 1.74.0 -y
 ENV PATH=/root/.cargo/bin:$PATH
 RUN cargo install cargo-ament-build
 

docs/writing-your-first-rclrs-node.md

@@ -47,7 +47,7 @@ use std::sync::Arc;
 use std_msgs::msg::String as StringMsg;
 
 struct RepublisherNode {
-    node: rclrs::Node,
+    node: Arc<rclrs::Node>,
     _subscription: Arc<rclrs::Subscription<StringMsg>>,
     data: Option<StringMsg>,
 }
@@ -114,7 +114,7 @@ use std::sync::{Arc, Mutex};  // (1)
 use std_msgs::msg::String as StringMsg;
 
 struct RepublisherNode {
-    node: rclrs::Node,
+    node: Arc<rclrs::Node>,
     _subscription: Arc<rclrs::Subscription<StringMsg>>,
     data: Arc<Mutex<Option<StringMsg>>>,  // (2)
 }

examples/message_demo/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "examples_rclrs_message_demo"
-version = "0.3.1"
+version = "0.4.1"
 authors = ["Nikolai Morin <[email protected]>"]
 edition = "2021"
 
@@ -12,13 +12,13 @@ path = "src/message_demo.rs"
 anyhow = {version = "1", features = ["backtrace"]}
 
 [dependencies.rclrs]
-version = "0.3"
+version = "0.4"
 
 [dependencies.rosidl_runtime_rs]
-version = "0.3"
+version = "0.4"
 
 [dependencies.rclrs_example_msgs]
-version = "0.3"
+version = "0.4"
 features = ["serde"]
 
 [dependencies.serde_json]

examples/message_demo/package.xml

@@ -4,7 +4,7 @@
    schematypens="http://www.w3.org/2001/XMLSchema"?>
 <package format="3">
   <name>examples_rclrs_message_demo</name>
-  <version>0.3.1</version>
+  <version>0.4.1</version>
   <description>Package containing an example of message-related functionality in rclrs.</description>
   <maintainer email="[email protected]">Nikolai Morin</maintainer>
   <license>Apache License 2.0</license>

examples/minimal_client_service/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "examples_rclrs_minimal_client_service"
-version = "0.3.1"
+version = "0.4.1"
 authors = ["Esteve Fernandez <[email protected]>"]
 edition = "2021"
 
@@ -21,10 +21,10 @@ anyhow = {version = "1", features = ["backtrace"]}
 tokio = { version = "1", features = ["macros", "rt", "rt-multi-thread", "time"] }
 
 [dependencies.rclrs]
-version = "0.3"
+version = "0.4"
 
 [dependencies.rosidl_runtime_rs]
-version = "0.3"
+version = "0.4"
 
 [dependencies.example_interfaces]
 version = "*"

examples/minimal_client_service/package.xml

@@ -4,7 +4,7 @@
    schematypens="http://www.w3.org/2001/XMLSchema"?>
 <package format="3">
   <name>examples_rclrs_minimal_client_service</name>
-  <version>0.3.1</version>
+  <version>0.4.1</version>
   <description>Package containing an example of the client-service mechanism in rclrs.</description>
   <maintainer email="[email protected]">Esteve Fernandez</maintainer>
   <license>Apache License 2.0</license>

examples/minimal_pub_sub/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "examples_rclrs_minimal_pub_sub"
-version = "0.3.1"
+version = "0.4.1"
 # This project is not military-sponsored, Jacob's employment contract just requires him to use this email address
 authors = ["Esteve Fernandez <[email protected]>", "Nikolai Morin <[email protected]>", "Jacob Hassold <[email protected]>"]
 edition = "2021"
@@ -29,10 +29,10 @@ path = "src/zero_copy_publisher.rs"
 anyhow = {version = "1", features = ["backtrace"]}
 
 [dependencies.rclrs]
-version = "0.3"
+version = "0.4"
 
 [dependencies.rosidl_runtime_rs]
-version = "0.3"
+version = "0.4"
 
 [dependencies.std_msgs]
 version = "*"

examples/minimal_pub_sub/package.xml

@@ -4,7 +4,7 @@
    schematypens="http://www.w3.org/2001/XMLSchema"?>
 <package format="3">
   <name>examples_rclrs_minimal_pub_sub</name>
-  <version>0.3.1</version>
+  <version>0.4.1</version>
   <description>Package containing an example of the publish-subscribe mechanism in rclrs.</description>
   <maintainer email="[email protected]">Esteve Fernandez</maintainer>
   <maintainer email="[email protected]">Nikolai Morin</maintainer>

rclrs/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "rclrs"
-version = "0.3.1"
+version = "0.4.1"
 # This project is not military-sponsored, Jacob's employment contract just requires him to use this email address
 authors = ["Esteve Fernandez <[email protected]>", "Nikolai Morin <[email protected]>", "Jacob Hassold <[email protected]>"]
 edition = "2021"
@@ -16,14 +16,15 @@ path = "src/lib.rs"
 [dependencies]
 # Needed for dynamically finding type support libraries 
 ament_rs = { version = "0.2", optional = true }
+# Needed for uploading documentation to docs.rs
+cfg-if = "1.0.0"
+
 # Needed for clients
 futures = "0.3"
 # Needed for dynamic messages
 libloading = { version = "0.8", optional = true }
-# Needed for /clock topic subscription when using simulation time
-rosgraph_msgs = "*"
 # Needed for the Message trait, among others
-rosidl_runtime_rs = "0.3"
+rosidl_runtime_rs = "0.4"
 
 [dev-dependencies]
 # Needed for e.g. writing yaml files in tests
@@ -32,6 +33,15 @@ tempfile = "3.3.0"
 [build-dependencies]
 # Needed for FFI
 bindgen = "0.66.1"
+# Needed for uploading documentation to docs.rs
+cfg-if = "1.0.0"
 
 [features]
+default = []
 dyn_msg = ["ament_rs", "libloading"]
+# This feature is solely for the purpose of being able to generate documetation without a ROS installation
+# The only intended usage of this feature is for docs.rs builders to work, and is not intended to be used by end users
+generate_docs = ["rosidl_runtime_rs/generate_docs"]
+
+[package.metadata.docs.rs]
+features = ["generate_docs"]

rclrs/build.rs

@@ -18,7 +18,21 @@ fn get_env_var_or_abort(env_var: &'static str) -> String {
 }
 
 fn main() {
-    let ros_distro = get_env_var_or_abort(ROS_DISTRO);
+    let ros_distro = if let Ok(value) = env::var(ROS_DISTRO) {
+        value
+    } else {
+        let error_msg =
+            "ROS_DISTRO environment variable not set - please source ROS 2 installation first.";
+        cfg_if::cfg_if! {
+            if #[cfg(feature="generate_docs")] {
+                println!("{}", error_msg);
+                return;
+            } else {
+                panic!("{}", error_msg);
+            }
+        }
+    };
+
     println!("cargo:rustc-cfg=ros_distro=\"{ros_distro}\"");
 
     let mut builder = bindgen::Builder::default()

rclrs/package.xml

@@ -4,7 +4,7 @@
    schematypens="http://www.w3.org/2001/XMLSchema"?>
 <package format="3">
   <name>rclrs</name>
-  <version>0.3.1</version>
+  <version>0.4.1</version>
   <description>Package containing the Rust client library.</description>
   <maintainer email="[email protected]">Esteve Fernandez</maintainer>
   <maintainer email="[email protected]">Nikolai Morin</maintainer>

rclrs/src/arguments.rs

@@ -149,7 +149,7 @@ mod tests {
         .map(|x| x.to_string());
 
         let non_ros_args: Vec<String> = extract_non_ros_args(input_args).unwrap();
-        let expected = vec!["non-ros1", "non-ros2", "non-ros3"];
+        let expected = ["non-ros1", "non-ros2", "non-ros3"];
 
         if non_ros_args.len() != expected.len() {
             return Err(format!(

rclrs/src/clock.rs

@@ -28,15 +28,15 @@ impl From<ClockType> for rcl_clock_type_t {
 /// Struct that implements a Clock and wraps `rcl_clock_t`.
 #[derive(Clone, Debug)]
 pub struct Clock {
-    _type: ClockType,
-    _rcl_clock: Arc<Mutex<rcl_clock_t>>,
+    kind: ClockType,
+    rcl_clock: Arc<Mutex<rcl_clock_t>>,
     // TODO(luca) Implement jump callbacks
 }
 
 /// A clock source that can be used to drive the contained clock. Created when a clock of type
 /// `ClockType::RosTime` is constructed
 pub struct ClockSource {
-    _rcl_clock: Arc<Mutex<rcl_clock_t>>,
+    rcl_clock: Arc<Mutex<rcl_clock_t>>,
 }
 
 impl Clock {
@@ -54,52 +54,52 @@ impl Clock {
     /// to update it
     pub fn with_source() -> (Self, ClockSource) {
         let clock = Self::make(ClockType::RosTime);
-        let clock_source = ClockSource::new(clock._rcl_clock.clone());
+        let clock_source = ClockSource::new(clock.rcl_clock.clone());
         (clock, clock_source)
     }
 
     /// Creates a new clock of the given `ClockType`.
-    pub fn new(type_: ClockType) -> (Self, Option<ClockSource>) {
-        let clock = Self::make(type_);
+    pub fn new(kind: ClockType) -> (Self, Option<ClockSource>) {
+        let clock = Self::make(kind);
         let clock_source =
-            matches!(type_, ClockType::RosTime).then(|| ClockSource::new(clock._rcl_clock.clone()));
+            matches!(kind, ClockType::RosTime).then(|| ClockSource::new(clock.rcl_clock.clone()));
         (clock, clock_source)
     }
 
-    fn make(type_: ClockType) -> Self {
+    fn make(kind: ClockType) -> Self {
         let mut rcl_clock;
         unsafe {
             // SAFETY: Getting a default value is always safe.
             rcl_clock = Self::init_generic_clock();
             let mut allocator = rcutils_get_default_allocator();
             // Function will return Err(_) only if there isn't enough memory to allocate a clock
             // object.
-            rcl_clock_init(type_.into(), &mut rcl_clock, &mut allocator)
+            rcl_clock_init(kind.into(), &mut rcl_clock, &mut allocator)
                 .ok()
                 .unwrap();
         }
         Self {
-            _type: type_,
-            _rcl_clock: Arc::new(Mutex::new(rcl_clock)),
+            kind,
+            rcl_clock: Arc::new(Mutex::new(rcl_clock)),
         }
     }
 
     /// Returns the clock's `ClockType`.
     pub fn clock_type(&self) -> ClockType {
-        self._type
+        self.kind
     }
 
     /// Returns the current clock's timestamp.
     pub fn now(&self) -> Time {
-        let mut clock = self._rcl_clock.lock().unwrap();
+        let mut clock = self.rcl_clock.lock().unwrap();
         let mut time_point: i64 = 0;
         unsafe {
             // SAFETY: No preconditions for this function
             rcl_clock_get_now(&mut *clock, &mut time_point);
         }
         Time {
             nsec: time_point,
-            clock: Arc::downgrade(&self._rcl_clock),
+            clock: Arc::downgrade(&self.rcl_clock),
         }
     }
 
@@ -128,14 +128,14 @@ impl Drop for ClockSource {
 
 impl PartialEq for ClockSource {
     fn eq(&self, other: &Self) -> bool {
-        Arc::ptr_eq(&self._rcl_clock, &other._rcl_clock)
+        Arc::ptr_eq(&self.rcl_clock, &other.rcl_clock)
     }
 }
 
 impl ClockSource {
     /// Sets the value of the current ROS time.
     pub fn set_ros_time_override(&self, nanoseconds: i64) {
-        let mut clock = self._rcl_clock.lock().unwrap();
+        let mut clock = self.rcl_clock.lock().unwrap();
         // SAFETY: Safe if clock jump callbacks are not edited, which is guaranteed
         // by the mutex
         unsafe {
@@ -147,16 +147,16 @@ impl ClockSource {
         }
     }
 
-    fn new(clock: Arc<Mutex<rcl_clock_t>>) -> Self {
-        let source = Self { _rcl_clock: clock };
+    fn new(rcl_clock: Arc<Mutex<rcl_clock_t>>) -> Self {
+        let source = Self { rcl_clock };
         source.set_ros_time_enable(true);
         source
     }
 
     /// Sets the clock to use ROS Time, if enabled the clock will report the last value set through
     /// `Clock::set_ros_time_override(nanoseconds: i64)`.
     fn set_ros_time_enable(&self, enable: bool) {
-        let mut clock = self._rcl_clock.lock().unwrap();
+        let mut clock = self.rcl_clock.lock().unwrap();
         if enable {
             // SAFETY: Safe if clock jump callbacks are not edited, which is guaranteed
             // by the mutex

rclrs/src/lib.rs

@@ -89,14 +89,13 @@ pub fn create_node(context: &Context, node_name: &str) -> Result<Arc<Node>, Rclr
     Node::new(context, node_name)
 }
 
-/// Creates a [`NodeBuilder`][1].
+/// Creates a [`NodeBuilder`].
 ///
-/// Convenience function equivalent to [`NodeBuilder::new()`][2] and [`Node::builder()`][3].
+/// Convenience function equivalent to [`NodeBuilder::new()`][1] and [`Node::builder()`][2].
 /// Please see that function's documentation.
 ///
-/// [1]: crate::NodeBuilder
-/// [2]: crate::NodeBuilder::new
-/// [3]: crate::Node::builder
+/// [1]: crate::NodeBuilder::new
+/// [2]: crate::Node::builder
 ///
 /// # Example
 /// ```