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-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add hakuturu583/ros2-claude-code-plugin.

Contents

Discovered from source

Commands 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 .git directory or file
  • The first directory containing .git is the Git repository root
  • If no .git found, 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, and colcon_build_options.yaml operations

0.5. Manage colcon_build_options.yaml

Check and create colcon build options file in Git repository root:

  • Check if colcon_build_options.yaml exists in the Git repository root
  • If it does NOT exist:
    • Create colcon_build_options.yaml in 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"
  • 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.txt exists 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.xml file in that directory (to distinguish workspace root from ROS 2 packages)
    • 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.txt exists in the Git repository root (found in step 0)
  • If it does NOT exist:
    • Create .ros_workspace.txt in 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]"
  • If it exists:
    • Inform user: "Using existing .ros_workspace.txt in [git-repo-root]"

2b. Create/Update build.sh script:

  • Create build.sh in 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 .gitignore exists in the Git repository root (found in step 0)
  • If .gitignore does not exist:
    • Create .gitignore in 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"
  • If .gitignore exists:
    • Read the file and check if each file is already present:
      • .ros_workspace.txt - If NOT present: Append to .gitignore
      • colcon_build_options.yaml - If NOT present: Append to .gitignore
      • build.sh - If NOT present: Append to .gitignore
    • Inform user with appropriate message about what was added

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-only in 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.yaml from Git repository root and parse as YAML/JSON
  • For each package name from colcon list:
    • Check if package exists in colcon_build_options.yaml under names key
    • If package does NOT exist:
      • Add package entry to names with empty configuration: "package_name": {}
  • 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.yaml from Git repository root
  • Copy the content to <workspace_root>/colcon.meta
    • Overwrite if colcon.meta already exists
  • 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"

    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-to for 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]"

    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"
  • 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-only is 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-select or --packages-up-to arguments
  • New packages are automatically added to colcon_build_options.yaml with empty configuration
  • colcon_build_options.yaml is copied to <workspace_root>/colcon.meta before 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 .git directory or file
  • The first directory containing .git is the Git repository root
  • If no .git found, 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.txt exists 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.txt does 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 --verbose flag is always included unless user explicitly provides other verbosity flags
  • 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.txt to exist (run /colcon-build first if it doesn't)
  • Always returns to the original directory after displaying results
  • Default verbosity is --verbose for 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 .git directory or file
  • The first directory containing .git is the Git repository root
  • If no .git found, 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.txt exists 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.txt does 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.sh in 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 .gitignore exists in the Git repository root (found in step 0)
  • Read the file and check if test.sh is already present
  • If NOT present:
    • Append test.sh to .gitignore
    • Inform user: "Added test.sh to .gitignore in [git-repo-root]"
  • 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-only in 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"

    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-to for 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]"

    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"
  • 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.txt to exist (run /colcon-build first 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-only is 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-select or --packages-up-to arguments
  • 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