
ros2-workspace
Complete ROS 2 workspace management with intelligent build/test automation, ccache support, and smart package selection
- version
- 0.1.0
- GitHub stars
- 10
Install
/plugin install ros2-workspace@ros2-workspace-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add hakuturu583/ros2-claude-code-plugin.
Contents
Discovered from sourceCommands 3
Execute a ROS 2 colcon build with automatic workspace detection and configuration.
Steps to Execute
0. Find Git Repository Root
First, find the Git repository root directory:
- Traverse up from the current working directory to find the directory containing
.git - Start from current directory and check each parent directory for
.gitdirectory or file - The first directory containing
.gitis the Git repository root - If no
.gitfound, display error: "Error: Not in a Git repository. Please run this command from within a Git repository." - Store this path as the "file operation directory" for all
.ros_workspace.txt,.gitignore, andcolcon_build_options.yamloperations
0.5. Manage colcon_build_options.yaml
Check and create colcon build options file in Git repository root:
- Check if
colcon_build_options.yamlexists in the Git repository root - If it does NOT exist:
- Create
colcon_build_options.yamlin the Git repository root with default template:# Colcon build options for this ROS 2 workspace # This file will be copied to <workspace_root>/colcon.meta before building # See: https://colcon.readthedocs.io/en/released/user/configuration.html { "names": { } } - Inform user: "Created colcon_build_options.yaml in [git-repo-root] with default template"
- Create
- If it exists:
- Inform user: "Found existing colcon_build_options.yaml in [git-repo-root]"
1. Find ROS 2 Workspace Root
First, check if .ros_workspace.txt exists in the Git repository root:
- If
.ros_workspace.txtexists in the Git repository root:- Read the workspace root path from the file
- Verify the path exists and is a valid directory
- Use this path as the workspace root
- Inform user: "Using workspace root from .ros_workspace.txt: [path]"
- Skip to step 3 (Update .gitignore)
If .ros_workspace.txt does NOT exist, detect workspace root:
- Traverse up from the current working directory to find the ROS 2 workspace root:
- Start from current directory
- Check each parent directory for:
- A
src/subdirectory exists - No
package.xmlfile in that directory (to distinguish workspace root from ROS 2 packages)
- A
- The first directory meeting both conditions is the workspace root
- If no workspace root found, display error: "Error: Could not find ROS 2 workspace root. Make sure you're inside a ROS 2 workspace with a 'src/' directory."
2. Create/Update .ros_workspace.txt and build.sh Files
Once workspace root is detected:
2a. Create/Update .ros_workspace.txt:
- Check if
.ros_workspace.txtexists in the Git repository root (found in step 0) - If it does NOT exist:
- Create
.ros_workspace.txtin the Git repository root - Write the absolute path of the workspace root to this file
- Inform user: "Created .ros_workspace.txt in [git-repo-root] with workspace root: [workspace-path]"
- Create
- If it exists:
- Inform user: "Using existing .ros_workspace.txt in [git-repo-root]"
2b. Create/Update build.sh script:
- Create
build.shin the Git repository root (found in step 0) - Write the following shell script content:
#!/bin/bash # Script to build ROS 2 workspace with ccache for faster compilation # Auto-generated by ros2-workspace Claude Code plugin # Usage: ./build.sh [colcon_args...] set -e # Get the directory where this script is located SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" # Check if ccache is installed if ! command -v ccache &> /dev/null; then echo "WARNING: ccache is not installed!" echo "ccache significantly speeds up recompilation by caching previous builds." echo "" echo "To install ccache:" echo " Ubuntu/Debian: sudo apt install ccache" echo " Fedora/RHEL: sudo dnf install ccache" echo " Arch Linux: sudo pacman -S ccache" echo " macOS: brew install ccache" echo "" echo "Continuing without ccache..." echo "" # Don't use ccache if not installed USE_CCACHE=false else # Set ccache environment variables for faster compilation export CC="ccache gcc" export CXX="ccache g++" USE_CCACHE=true fi # Read ROS workspace directory from .ros_workspace.txt WORKSPACE_ROOT=$(cat "$SCRIPT_DIR/.ros_workspace.txt") # Change to ROS workspace directory cd "$WORKSPACE_ROOT" # Run colcon build if [ "$USE_CCACHE" = true ]; then echo "Building ROS 2 workspace with ccache enabled..." echo "Workspace: $WORKSPACE_ROOT" echo "CC=$CC" echo "CXX=$CXX" echo "" else echo "Building ROS 2 workspace..." echo "Workspace: $WORKSPACE_ROOT" echo "" fi # Check if arguments are provided if [ $# -eq 0 ]; then echo "Error: No colcon build arguments specified!" echo "Usage: $0 [colcon_args...]" echo "" echo "Examples:" echo " $0 --packages-select my_package" echo " $0 --packages-up-to my_package" echo " $0 --packages-up-to pkg1 pkg2 --symlink-install" echo "" echo "Discovering available packages in workspace..." colcon list --names-only 2>/dev/null || echo "Failed to list packages" exit 1 else echo "Running: colcon build $@" echo "" colcon build "$@" fi echo "" echo "Build completed!" # Show ccache statistics if ccache was used if [ "$USE_CCACHE" = true ]; then echo "" echo "ccache statistics:" ccache -s fi - Make the script executable:
chmod +x build.sh - Inform user: "Updated build.sh script in [git-repo-root]" (always update to ensure latest version)
3. Update .gitignore
Ensure .ros_workspace.txt, colcon_build_options.yaml, and build.sh are ignored by git:
- Check if
.gitignoreexists in the Git repository root (found in step 0) - If
.gitignoredoes not exist:- Create
.gitignorein the Git repository root with content:.ros_workspace.txt colcon_build_options.yaml build.sh - Inform user: "Created .gitignore in [git-repo-root] and added generated files"
- Create
- If
.gitignoreexists:- Read the file and check if each file is already present:
.ros_workspace.txt- If NOT present: Append to.gitignorecolcon_build_options.yaml- If NOT present: Append to.gitignorebuild.sh- If NOT present: Append to.gitignore
- Inform user with appropriate message about what was added
- Read the file and check if each file is already present:
4. Discover Packages in Current Directory and Update Configuration
Discover packages in current working directory and workspace:
4a. Find packages in current working directory:
- Execute
colcon list --names-onlyin the current working directory (where Claude Code was started) - Parse the output to get list of package names in current directory
- Store this list as "current_directory_packages"
- If packages found: Inform user: "Found [N] package(s) in current directory: [package names]"
- If no packages found: Inform user: "No packages found in current directory, will build entire workspace"
4b. Update colcon_build_options.yaml with all workspace packages:
- Change to the workspace root directory
- Execute:
colcon list --names-only - Parse the output to get list of all package names in workspace
- Read
colcon_build_options.yamlfrom Git repository root and parse as YAML/JSON - For each package name from
colcon list:- Check if package exists in
colcon_build_options.yamlundernameskey - If package does NOT exist:
- Add package entry to
nameswith empty configuration:"package_name": {}
- Add package entry to
- Check if package exists in
- Write the updated content back to
colcon_build_options.yaml - Inform user: "Updated colcon_build_options.yaml: added [N] new package(s)" (if any were added)
5. Copy Build Options to colcon.meta
Before building, copy updated configuration to workspace:
- Read the content of
colcon_build_options.yamlfrom Git repository root - Copy the content to
<workspace_root>/colcon.meta- Overwrite if
colcon.metaalready exists
- Overwrite if
- Inform user: "Copied colcon_build_options.yaml to [workspace-root]/colcon.meta"
6. Execute Colcon Build via build.sh Script
Run the colcon build command through the build.sh script with intelligent package selection:
-
Save the current working directory to return to after build completion
-
Change to the Git repository root directory (where build.sh is located)
-
Determine build command based on user arguments and current directory packages:
Case 1: User provided package selection arguments
- If user arguments contain
--packages-select,--packages-up-to,--packages-skip, or--packages-above:- Use user-provided arguments as-is:
./build.sh [user-provided-arguments] - Inform user: "Building with user-specified package selection"
- Use user-provided arguments as-is:
Case 2: Packages found in current directory (no user package selection)
- If "current_directory_packages" is not empty AND user did not specify package selection:
- Build with
--packages-up-tofor current directory packages - Command:
./build.sh --packages-up-to [current_directory_packages] [other-user-arguments] - Example:
./build.sh --packages-up-to pkg1 pkg2 pkg3 --symlink-install - Inform user: "Building packages in current directory and their dependencies: [package names]"
- Build with
Case 3: No packages in current directory (no user package selection)
- If "current_directory_packages" is empty AND user did not specify package selection:
- Build entire workspace:
./build.sh [user-provided-arguments] - Example:
./build.sh --symlink-install - Inform user: "Building entire workspace"
- Build entire workspace:
- If user arguments contain
-
Display the output of the build process to the user (including ccache info from build.sh)
-
If build fails, show the error and exit code
7. Return to Original Directory
- Change back to the original directory (saved in step 6)
- Inform user: "Returned to original directory: [original-path]"
Note: The build.sh script handles:
- Setting up ccache for faster compilation (CC="ccache gcc", CXX="ccache g++")
- Changing to the workspace root directory
- Running colcon build with the provided arguments
- Displaying ccache statistics after build completion
Important Notes
- All file operations (creating .ros_workspace.txt, colcon_build_options.yaml, build.sh, modifying .gitignore) should happen in the Git repository root (directory containing .git)
- The command requires being run from within a Git repository
- Use absolute paths when writing to .ros_workspace.txt
- Preserve existing .gitignore content when adding new entries
- build.sh script:
- Auto-generated and updated on every run to ensure latest version
- Stored in Git repository root
- Automatically detects and uses ccache if installed (CC="ccache gcc", CXX="ccache g++")
- Displays warning with installation instructions if ccache not found
- Works without ccache (falls back to normal gcc/g++)
- Reads workspace root from .ros_workspace.txt
- Displays ccache statistics after build completion (if ccache is used)
- Added to .gitignore (local configuration)
- Intelligent package selection:
colcon list --names-onlyis executed in both current directory and workspace root- If packages are found in current directory, automatically builds only those packages and dependencies with
--packages-up-to - If no packages in current directory, builds entire workspace
- User can override with explicit
--packages-selector--packages-up-toarguments
- New packages are automatically added to
colcon_build_options.yamlwith empty configuration colcon_build_options.yamlis copied to<workspace_root>/colcon.metabefore every build- Colcon build is executed via build.sh script from Git repository root
- Pass through any arguments the user provides to the colcon build command
Display detailed test results from the ROS 2 workspace with colcon test-result.
Steps to Execute
0. Find Git Repository Root
First, find the Git repository root directory:
- Traverse up from the current working directory to find the directory containing
.git - Start from current directory and check each parent directory for
.gitdirectory or file - The first directory containing
.gitis the Git repository root - If no
.gitfound, display error: "Error: Not in a Git repository. Please run this command from within a Git repository."
1. Find ROS 2 Workspace Root
Check if .ros_workspace.txt exists in the Git repository root:
- If
.ros_workspace.txtexists in the Git repository root:- Read the workspace root path from the file
- Verify the path exists and is a valid directory
- Use this path as the workspace root
- Inform user: "Using workspace root from .ros_workspace.txt: [path]"
- If
.ros_workspace.txtdoes NOT exist:- Display error: "Error: .ros_workspace.txt not found. Please run /colcon-build first to set up the workspace."
- Stop execution
2. Save Current Directory
- Get the current working directory (where Claude Code was started)
- Store this path to return to after displaying test results
3. Display Test Results
Execute colcon test-result in the workspace:
- Change to the workspace root directory (from .ros_workspace.txt)
- Execute:
colcon test-result --verbose [user-provided-arguments]- Default:
colcon test-result --verbose(shows detailed test results) - If user provided arguments (e.g.,
--all,--test-result-base), pass them to colcon test-result - The
--verboseflag is always included unless user explicitly provides other verbosity flags
- Default:
- Display the full output of the command to the user
- If command fails, show the error and exit code
4. Return to Original Directory
- Change back to the original directory (saved in step 2)
- Inform user: "Returned to original directory: [original-path]"
Important Notes
- The command requires being run from within a Git repository
- Requires
.ros_workspace.txtto exist (run/colcon-buildfirst if it doesn't) - Always returns to the original directory after displaying results
- Default verbosity is
--verbosefor detailed output - User can override with options like
--all,--test-result-base, etc. - Does not modify any files or state
- Works from any directory within the Git repository
Usage Examples
# Display detailed test results
/colcon-test-result
# Display all test results including passed tests
/colcon-test-result --all
# Use custom test result directory
/colcon-test-result --test-result-base custom_results
Execute ROS 2 colcon test with automatic workspace detection and configuration.
Steps to Execute
0. Find Git Repository Root
First, find the Git repository root directory:
- Traverse up from the current working directory to find the directory containing
.git - Start from current directory and check each parent directory for
.gitdirectory or file - The first directory containing
.gitis the Git repository root - If no
.gitfound, display error: "Error: Not in a Git repository. Please run this command from within a Git repository." - Store this path as the "file operation directory" for all test.sh operations
1. Find ROS 2 Workspace Root
Check if .ros_workspace.txt exists in the Git repository root:
- If
.ros_workspace.txtexists in the Git repository root:- Read the workspace root path from the file
- Verify the path exists and is a valid directory
- Use this path as the workspace root
- Inform user: "Using workspace root from .ros_workspace.txt: [path]"
- If
.ros_workspace.txtdoes NOT exist:- Display error: "Error: .ros_workspace.txt not found. Please run /colcon-build first to set up the workspace."
- Stop execution
2. Create/Update test.sh Script
Create or update the test script in Git repository root:
Create/Update test.sh script:
- Create
test.shin the Git repository root (found in step 0) - Write the following shell script content:
#!/bin/bash # Script to test ROS 2 workspace # Auto-generated by ros2-workspace Claude Code plugin # Usage: ./test.sh [colcon_test_args...] set -e # Get the directory where this script is located SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" # Read ROS workspace directory from .ros_workspace.txt if [ ! -f "$SCRIPT_DIR/.ros_workspace.txt" ]; then echo "Error: .ros_workspace.txt not found!" echo "Please run /colcon-build first to set up the workspace." exit 1 fi WORKSPACE_ROOT=$(cat "$SCRIPT_DIR/.ros_workspace.txt") # Change to ROS workspace directory cd "$WORKSPACE_ROOT" # Run colcon test echo "Testing ROS 2 workspace..." echo "Workspace: $WORKSPACE_ROOT" echo "" # Check if arguments are provided if [ $# -eq 0 ]; then echo "Error: No colcon test arguments specified!" echo "Usage: $0 [colcon_test_args...]" echo "" echo "Examples:" echo " $0 --packages-select my_package" echo " $0 --packages-up-to my_package" echo " $0 --packages-up-to pkg1 pkg2" echo "" echo "Discovering available packages in workspace..." colcon list --names-only 2>/dev/null || echo "Failed to list packages" exit 1 else echo "Running: colcon test $@" echo "" colcon test "$@" fi echo "" echo "Test completed!" echo "" echo "Viewing test results..." colcon test-result --all - Make the script executable:
chmod +x test.sh - Inform user: "Updated test.sh script in [git-repo-root]" (always update to ensure latest version)
3. Update .gitignore
Ensure test.sh is ignored by git:
- Check if
.gitignoreexists in the Git repository root (found in step 0) - Read the file and check if
test.shis already present - If NOT present:
- Append
test.shto.gitignore - Inform user: "Added test.sh to .gitignore in [git-repo-root]"
- Append
- If already present:
- Inform user: "test.sh already in .gitignore"
4. Discover Packages in Current Directory
Find packages in current working directory:
- Execute
colcon list --names-onlyin the current working directory (where Claude Code was started) - Parse the output to get list of package names in current directory
- Store this list as "current_directory_packages"
- If packages found: Inform user: "Found [N] package(s) in current directory: [package names]"
- If no packages found: Inform user: "No packages found in current directory, will test entire workspace"
5. Execute Colcon Test via test.sh Script
Run the colcon test command through the test.sh script with intelligent package selection:
-
Save the current working directory to return to after test completion
-
Change to the Git repository root directory (where test.sh is located)
-
Determine test command based on user arguments and current directory packages:
Case 1: User provided package selection arguments
- If user arguments contain
--packages-select,--packages-up-to,--packages-skip, or--packages-above:- Use user-provided arguments as-is:
./test.sh [user-provided-arguments] - Inform user: "Testing with user-specified package selection"
- Use user-provided arguments as-is:
Case 2: Packages found in current directory (no user package selection)
- If "current_directory_packages" is not empty AND user did not specify package selection:
- Test with
--packages-up-tofor current directory packages - Command:
./test.sh --packages-up-to [current_directory_packages] [other-user-arguments] - Example:
./test.sh --packages-up-to pkg1 pkg2 pkg3 - Inform user: "Testing packages in current directory and their dependencies: [package names]"
- Test with
Case 3: No packages in current directory (no user package selection)
- If "current_directory_packages" is empty AND user did not specify package selection:
- Test entire workspace:
./test.sh [user-provided-arguments] - Example:
./test.sh - Inform user: "Testing entire workspace"
- Test entire workspace:
- If user arguments contain
-
Display the output of the test process to the user (including test results from test.sh)
-
If test fails, show the error and exit code
6. Return to Original Directory
- Change back to the original directory (saved in step 5)
- Inform user: "Returned to original directory: [original-path]"
Note: The test.sh script handles:
- Checking for .ros_workspace.txt existence
- Changing to the workspace root directory
- Running colcon test with the provided arguments
- Displaying test results with colcon test-result --all
Important Notes
- All file operations (creating test.sh, modifying .gitignore) should happen in the Git repository root (directory containing .git)
- The command requires being run from within a Git repository
- Requires
.ros_workspace.txtto exist (run/colcon-buildfirst if it doesn't) - test.sh script:
- Auto-generated and updated on every run to ensure latest version
- Stored in Git repository root
- Reads workspace root from .ros_workspace.txt
- Displays test results with colcon test-result --all after test completion
- Added to .gitignore (local configuration)
- Intelligent package selection:
colcon list --names-onlyis executed in current directory- If packages are found in current directory, automatically tests only those packages and dependencies with
--packages-up-to - If no packages in current directory, tests entire workspace
- User can override with explicit
--packages-selector--packages-up-toarguments
- Colcon test is executed via test.sh script from Git repository root
- Pass through any arguments the user provides to the colcon test command
Sponsors
Details
- Marketplace
- hakuturu583/ros2-claude-code-plugin
- Author
- Masaya Kataoka
- Category
- Development Tools
- License
- MIT
- Keywords
- ros2, robotics, colcon, build, test, workspace, automation, ccache, development