rostree and other tools¶
rostree is not the first tool to look at ROS package dependencies, and it does not replace the ones you already use. This page says what each is for, so you can pick the right one — and so it is clear what rostree adds rather than duplicates.
What already exists¶
colcon graph — part of colcon, the ROS 2 build tool. In its
documentation's
words it "generates a visual representation of the package dependency graph":
by default a topologically ordered list that uses ASCII art to show direct and
transitive dependencies, or DOT with --dot, ready for Graphviz. It describes
the packages colcon has discovered to build.
colcon list --packages-up-to / --packages-above —
package selection arguments
for building: "the packages with the passed names as well as their recursive
dependencies", or "as well as packages which recursively depend on them". They
answer which packages should this build include.
ros2 pkg — ros2 pkg list, ros2 pkg prefix and ros2 pkg xml list the
installed packages, say where one lives, and print its manifest. Lookups, one
package at a time.
rosdep — resolves the rosdep keys in a manifest (eigen, python3-numpy)
to operating-system packages and installs them. It is about system dependencies,
not about the graph of ROS packages.
rqt_dep — in ROS 1, a GUI plugin that drew the package dependency graph.
What rostree adds¶
colcon's tools are built around building: which packages to build, and in what order. rostree is built around understanding a dependency graph you already have, and keeping an eye on it.
- Everything the environment can see, not only what is being built — your workspace and the distro under it, wherever the distro is installed — with each package labelled by where it came from.
- Questions, not just pictures. Why does this package depend on that one —
every shortest chain (
why)? What breaks if I change this, by name, through any chain (rdeps --transitive)? What did this package gain, lose or bump since the last snapshot (diff)? - Readable at workspace scale. A ROS graph is a DAG, so printing it as a tree repeats shared subtrees thousands of times. rostree prints each package once and refers back to it — see How the algorithms work.
- A CI gate.
rostree checkfails on dependency cycles and on names that resolve to no package, with JUnit output;difffails on drift. - An interactive graph you can send.
graph -f htmlwrites one self-contained file — no CDN, no network — that shows one package's neighbourhood at a time instead of the whole workspace at once. - A library. Everything above is a function in
rostree.api. See Build on rostree.
When to use which¶
| You want to… | Use |
|---|---|
| choose which packages a build includes | colcon build --packages-up-to … |
| see the build order of the workspace you are building | colcon graph |
| install the system packages a workspace needs | rosdep install |
| find where one installed package lives | ros2 pkg prefix |
| know why one package pulls in another | rostree why |
| know what breaks if you change a package | rostree rdeps -t |
| fail CI on cycles, unresolved names or dependency drift | rostree check, rostree diff |
| explore a workspace's dependencies interactively | rostree (TUI) or rostree graph -f html |
If you know of a tool that belongs on this page, or something here is out of date, please open an issue.