ROS workspace overlay precedence: why builds link the wrong package

Your build fails with a 'has no member named' error for a function you can see in the source you cloned. That mismatch almost never means the code is wrong; it means the compiler read a different copy of the package. On a ROS machine, the copy is usually the distro install under /opt/ros, and the fix is a catkin overlay workspace sourced after the underlay. Below you get the resolution rule, a four-line test that proves which copy the compiler used, the overlay recipe that fixed a Melodic hand-eye calibration stack, and the OpenCV floor below which the marker stage cannot be trusted. Every step runs in the same shell that runs the build.

Symptom: the member is in the branch, not in the build

On a ROS Melodic hand-eye calibration stack built with catkin build, the failure looks like this:

error: 'class rviz_visual_tools::TFVisualTools' has no member named 'clearAllTransforms'; did you mean 'publishAllTransforms'?
error: no matching function for call to 'moveit_visual_tools::MoveItVisualTools::publishMesh(Eigen::Isometry3d&, shape_msgs::Mesh&, rviz_visual_tools::colors, double, const char [4], int)'

Both symbols exist. clearAllTransforms and that publishMesh overload live on the master branch of the two visual-tools packages, and a grep through your clone finds them in the src folder you added to the workspace. The compiler disagrees anyway, because it is reading a different include tree.

One mechanism explains nearly every failure of this shape: the build resolved an older copy of the package from the underlay and never saw your clone. The fix is about sourcing order, not code. Message and geometry packages fail the same way, which the missing ROS message package fix for calibration builds walks through.

Why the underlay wins

ROS installs are layered. The distro tree under /opt/ros is the underlay, every workspace you create is an overlay on top of it, and the last setup.bash you source sits at the front of the search chain. catkin keeps that order in CMAKE_PREFIX_PATH, and rospack mirrors it in ROS_PACKAGE_PATH. When a build asks for a package, the first directory on the chain that contains it wins, for headers, message definitions and libraries alike:

If the shell that ran catkin build never sourced the overlay's devel/setup.bash, the chain holds only /opt/ros, and the distro binary is the single candidate. That is also why catkin clean alone cannot fix it: cleaning deletes build artefacts, not candidates.

One more rule matters when the overridden package has consumers inside the underlay: the override must stay API and ABI compatible with them, or those consumers break at runtime. That is the reason a stack mixing binary move_group with the master visual tools ends up building moveit itself from source.

Likely causes, in order of probability

Check these five, top down; the first two account for most cases.

1. The overlay was never sourced in the build shell. Sourcing lasts for one terminal, so a newly opened window drops it. Test with echo $CMAKE_PREFIX_PATH: your devel path must appear ahead of /opt/ros/melodic.
2. The clone sits in a workspace that is not on the chain at all. rospack find rviz_visual_tools then prints /opt/ros/melodic/share/rviz_visual_tools, naming the underlay copy as the one resolving.
3. A stale CMake cache from before the sources were reordered. catkin caches prefix paths at configure time. Test: the error survives a correct source order, so clean the affected packages and build again.
4. The wrong branch was cloned. melodic-devel of rviz_visual_tools lacks clearAllTransforms; master carries it. git branch inside the clone settles which one you checked out.
5. rosdep reinstalled a binary you removed by hand. It happens at the next rosdep install step. List the installed packages afterwards and look for the ros-melodic- binary of the same package.

The test that proves which copy built

Run all four lines in the same shell that runs the build:

rospack find rviz_visual_tools
echo $CMAKE_PREFIX_PATH
git -C $(rospack find rviz_visual_tools) rev-parse --abbrev-ref HEAD
grep -rn clearAllTransforms /opt/ros/melodic/include | wc -l

Read the output as a chain. A rospack path under /opt/ros/melodic means the underlay copy resolves; git then answering nothing shows that path is not a repository, so it is the distro install and not your clone.

The grep closes the case: 0 hits for clearAllTransforms under the distro include tree, against a clone that contains the symbol, proves the compiler read the 0-hit copy. When rospack instead prints your clone's path and git answers master, resolution is fixed and the build can run.

Worked example: a Melodic hand-eye calibration build that links the system rviz_visual_tools

Inputs, with where each comes from:

• Error text: the two compiler lines above, demanding clearAllTransforms and one publishMesh overload (read off the failing build).
• Environment: ROS Melodic on Ubuntu bionic, distro OpenCV 3.2, built with catkin build (printed by the failing shell and the distro release).
• Branch facts: both demanded symbols exist on the master branch of the visual-tools packages (from the branch history).
• Version floor for the marker stage: OpenCV 3.4, because the ArUco module was buggy below it (from the module's release history).

Rule in words: the compiler can only use symbols from the include tree of the first chain entry that resolves each package.

1. Chain at failure: CMAKE_PREFIX_PATH holds 1 prefix, /opt/ros/melodic, and 0 overlays. Candidates for rviz_visual_tools: 1, the distro binary. Symbols demanded: 2. Hits for them in the distro include tree: 0. Compiler errors: 2, one per demand.
2. Fix the chain: source /opt/ros/melodic/setup.bash, then the overlay's devel/setup.bash. Chain: 2 prefixes, overlay first. Candidates: 2 copies; first match: the clone on master. Hits per demanded symbol in its include tree: at least 1. Compiler errors: 0, and the build completes.
3. Marker stage: distro OpenCV 3.2 < 3.4 floor, so ArUco output on this install stays untrustworthy until OpenCV is newer, regardless of the build fix.

Result: same source, same machine, same build command; the only change was which directory sits first on the chain.

Decision: build only when rospack find prints the clone path. While /opt/ros/melodic is the first prefix, any number of clean rebuilds reproduces the same two errors, and below OpenCV 3.4 the calibration result is not trustworthy even when it compiles.

Fix: build the needed branch in an overlay

1. Create a small overlay workspace that holds only the packages that must override the distro, starting with rviz_visual_tools cloned with -b master.
2. On Melodic, clone geometric_shapes, moveit and moveit_visual_tools with -b melodic-devel; master of those had started tracking newer ROS releases.
3. Build the overlay with catkin build; catkin_make works the same for this layout.
4. Source in order in every build shell: underlay first, overlay second, work workspace last. The last source takes precedence, so the overlay must come after /opt/ros/melodic/setup.bash. Put the source lines in your shell start-up file so new terminals inherit them.
5. Clean the packages that failed, then rebuild — order first, clean second; the reverse reproduces the error.
6. Re-run the four-line test and require rospack find to print the overlay path before calling the build fixed.

Branch choice and the OpenCV floor

If the overlay build then complains about moveit_msgs or geometric_shapes, add those to the same overlay on the branch that matches the moveit you compiled. For the full list of names that must match across build and runtime, the hand-eye calibration build-errors checklist is the companion page.

The marker stage has its own floor, separate from resolution order. The ArUco module was buggy before OpenCV 3.4, and a Melodic distro on bionic ships 3.2 — 0.2 below the floor. Expect weak or unstable marker detection at 3.2 and treat the calibration output accordingly: either build a newer OpenCV for the stack, or move the calibration to a newer ROS release where the module is mature. The CMake fix for a missing OpenCV aruco module covers the module side, and OpenCV version conflicts that crash vision calibration tools covers the runtime clash when two versions meet.

The machine that does the rebuild

A source build of a manipulation stack is the heavy case, and catkin compiles independent packages in parallel, so peak memory use grows with the job count you allow. Plan the rebuild on the machine that will run the result. The vision controllers category is built for that role; for a separate build workstation, industrial mini PCs are an alternative when the cell already has its vision hardware.

For nightly rebuilds and live camera feeds on one box, the MV-VC5525-256G70-NN pairs a 12th-gen Core i5 with 32 GB of memory and a 256 GB SSD, with PoE camera ports and 8 built-in light channels.

A single-workstation rebuild fits the MV-VC3301H-128G66, which runs a Core i3-8100 with 8 GB of memory and a 128 GB SSD, PCIe expansion supported.

Whichever box runs the stack, the hand-eye stage captures from an area scan camera mounted in the cell, so match the controller's camera ports to the interface you chose. The camera finder filters by interface and resolution, and the configurator assembles controller, camera and lens in one pass.

After the fix: runtime and accuracy checks

A clean build is not the finish line. At runtime the process must load the overlay's libraries rather than the distro's; a stack that compiled against new headers but loaded old binaries fails later with classic mismatch symptoms. Diagnosing ROS OpenCV runtime library mismatches shows the loader-side pattern, and missing shared-library dependencies in Linux vision builds covers the crash cases.

Reproducibility is the other half: the chain that worked on Tuesday must be identical on the rebuild box. Pinning beats memory, and pinning one library version everywhere in Docker shows the pattern that keeps SDK versions fixed across machines.

Then measure instead of assuming. Hand-eye output drifts with marker quality, and the OpenCV floor above caps what the marker stage can deliver on this distro. Verifying hand-eye calibration accuracy before you trust it gives the bench test, and verifying the eye-to-hand camera-to-base result covers the eye-to-hand layout where the camera watches the wrist from a fixed mount.

Quick checklist

Before the build

• Source underlay, overlay, then work workspace, in that order, in every shell — the last source takes precedence, and a missed source is the most common cause.
• Write the branch next to each clone line: rviz_visual_tools from master; geometric_shapes, moveit and moveit_visual_tools from melodic-devel on Melodic.

When the error returns

• Run rospack find on the failing package in the build shell; a path under /opt/ros means the underlay still resolves.
• Grep the distro include tree for the missing symbol; 0 hits against a clone that has it proves the wrong copy was read.
• Clean only after the source order is right, and expect rosdep to reinstall anything you removed by hand.

After it builds

• Confirm the running nodes load the overlay libraries, not the distro's.
• Keep the marker stage on OpenCV 3.4 or newer before trusting ArUco output on a Melodic distro.
• Verify the calibration against a physical target before the cell runs production parts.

When the rebuilt stack has to run on a controller on the line, contact us with your camera count and interface, and we will size the box. Related build fixes sit on the systems topic page.