Skip to content

Update README with newest features / architecture #36

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.

Sign up for GitHub

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

Open
luca-della-vedova wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update README with newest features / architecture #36

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 2 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@ Build cargo projects with colcon.


## Usage
Packages need to have a `package.xml` in addition to `Cargo.toml`. You should see such packages classified as `ament_cargo` in the output of `colcon list`. If they are classified as `ros.ament_cargo` instead, the `colcon-ros-cargo` extension has not been found by `colcon`. Make sure that you have built and loaded (`source install/setup.bash`) the extension.
Packages need to have a `package.xml` in addition to `Cargo.toml`. Make sure that you have built and loaded (`source install/setup.bash`) the extension.

@Blast545 Blast545 Dec 12, 2025

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you elaborate on this section?

Make sure that you have built and loaded (`source install/setup.bash`) the extension.

As a newcomer to the tool, from the usage described in: https://github.com/ros2-rust/ros2_rust?tab=readme-ov-file#sounds-great-how-can-i-try-this-out

It seems like we source the workspace of Rust crates after we build the ROS workspace. Is my understanding incorrect?

I would expect that we don't have to source anything from colcon-ros-cargo since it's a colcon extension

@luca-della-vedova luca-della-vedova Dec 15, 2025

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's perhaps a bit redundant and more of a general direction about how to install colcon extensions, since for now there are no debian packages this can only be pip installed (with the scary --break-system-packages flag) or put in a colcon workspace and colcon build.
I gave it a quick try and indeed if I have a workspace with this colcon extension and a package that would be built by it (something that is identified as a ros.ament_cargo package named example) the following seem to be true:

  • Doing colcon build --packages-up-to example doesn't build this colcon extension, which makes sense since it's not an explicit dependency I guess.
  • Doing colcon build --packages-select colcon-ros-cargo, followed by colcon build --package-select example does not correctly identify the package, and colcon still reports that it doesn't know how to handle a ros.ament_cargo package.
  • Doing a colcon build --packages-select colcon-ros-cargo, followed by a source install/setup.bash, followed by a colcon build --packages-select example correctly works, suggesting that indeed colcon extensions need to be built and sourced before they can be used.


Simply list dependencies (other `ament_cargo` packages or message packages) in `Cargo.toml` and `package.xml` as if they were hosted on crates.io. `colcon-ros-cargo` will find the dependencies and create a `.cargo/config.toml` file that helps cargo find these packages.
Simply list dependencies (other `ros.ament_cargo` packages or message packages) in `Cargo.toml` and `package.xml` as if they were hosted on crates.io. `colcon-ros-cargo` will find the dependencies and create a `.cargo/config.toml` file that helps cargo find these packages.

Extra arguments to `cargo` can be passed via the `--cargo-args` option, e.g. `colcon build --cargo-args --release`.

Expand All @@ -18,5 +18,3 @@ After building, run binaries with `ros2 run`.
This is by far not a perfect build system.

Notably, there is _quadratic_ build cost as a function of the dependency chain length. To illustrate this, assume there are packages A, B and C, where C depends on B and B depends on A. If colcon builds this workspace, it builds A first, then B, then C. However, Cargo will _also_ build all the dependencies, i.e., to build B, Cargo will build A again, and to build C, it will build A and B again.

`colcon test` is not yet supported.
Loading