skills.rest
wimblerobotics
wimbleroboticsCOMMUNITY
Explore all skills by this author →
GitHub

workspace-overlays

Explain ROS 2 workspace overlay precedence and environment path chaining.

18|2|Updated Apr 20, 2026
Search Tags:#workspace#environment#ros2#overlay#ament_prefix_path
One-click install
npx skills add https://github.com/wimblerobotics/ros2-copilot-skills --skill workspace-overlays
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: workspace-overlays
Source: https://github.com/wimblerobotics/ros2-copilot-skills/tree/main/workspace-overlays
Command: npx skills add https://github.com/wimblerobotics/ros2-copilot-skills --skill workspace-overlays

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

ROS 2 projects commonly rely on layered workspaces where overlays take precedence over underlays. This skill guides understanding, debugging, and managing overlay chains to ensure predictable package resolution and environment configuration.

Core Features & Use Cases

  • Understands overlay priority and how setup.bash affects AMENT_PREFIX_PATH, PATH, and PYTHONPATH.
  • Provides two- and three-layer workflow examples to reproduce and resolve conflicts between overlays and underlays.
  • Use cases include overriding system packages with local workspaces, debugging build orders, and validating environment chains across terminals.

Quick Start

Source the underlay, build your overlays, and source your application workspace to verify the overlay chain.

Frequently Asked Questions about workspace-overlays

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do ROS 2 workspace overlays control package resolution?▼

ROS 2 workspace overlays control package resolution by chaining sourcing sequences that modify environment variables like AMENT_PREFIX_PATH, PATH, and PYTHONPATH, ensuring overlays take precedence over underlays for predictable package discovery.

How do I set up a multi-layer ROS 2 workspace overlay chain?▼

To set up a multi-layer ROS 2 workspace overlay chain, source the underlay first, build your overlays, and then source the application workspace to validate the precedence and verify the environment path chaining.

Why does sourcing order affect AMENT_PREFIX_PATH in ROS 2?▼

Sourcing order affects AMENT_PREFIX_PATH because executing setup.bash sequentially appends new workspace paths, directly controlling which overlay packages override the existing underlay packages in the resolution chain.

Can I override system packages with a local ROS 2 overlay?▼

Yes, you can override system packages with a local ROS 2 overlay by sourcing the local workspace setup.bash after the system underlay, which prioritizes local packages in the environment paths and package resolution.

Why are my ROS 2 overlay packages not overriding the underlay?▼

ROS 2 overlay packages fail to override underlays when sourcing order is incorrect, meaning the underlay setup.bash was sourced after the overlay, breaking the intended AMENT_PREFIX_PATH precedence chain.

How do I debug ROS 2 build order conflicts across overlay workspaces?▼

Debug ROS 2 build order conflicts by validating the sourcing sequence across terminals and checking environment variable effects like AMENT_PREFIX_PATH, PYTHONPATH, and PATH to ensure correct overlay precedence.

Related Skills

Explore More Software Engineering Skills→
wimbleroboticswimblerobotics
18

colcon-workspace

Manage ROS 2 colcon workspaces with structured builds and overlays.

Community
Advanced
dcc-mcpdcc-mcp
4

3dsmax-scripting

Execute auditable Python or MaxScript snippets to inspect 3ds Max runtime symbols and node references.

Official
Advanced
liueggyliueggy
1

ros

Guide ROS and ROS2 development with runnable examples and diagnostic commands.

Community
Intermediate
cindy-woocindy-woo

integrate-module-into-layer

Integrate ROS 2 modules into layer bringup packages with topic remapping.

Community
Advanced