Colcon PowerShell Extension

0.5.0 · active · verified Fri Apr 17

colcon-powershell is an extension for the colcon build tool, providing support for generating and sourcing PowerShell setup scripts. It's a key component for ROS 2 development on Windows, allowing users to easily set up their environment after building. It's currently at version 0.5.0 and follows the release cadence of the wider colcon/ROS 2 ecosystem, with stable but not frequent updates.

Common errors

```
colcon: command not found
```
cause The 'colcon' command-line tool is not installed or not in your system's PATH.

fix Install `colcon-core` and common extensions: `pip install colcon-core colcon-common-extensions`.
```
FAILURE: 'setup.ps1' not found. Make sure colcon-powershell is installed and colcon-core is correctly configured.
```
cause colcon-powershell was not active during the build, or there was no build output that required generating PowerShell scripts.

fix Ensure `colcon-powershell` is installed (`pip install colcon-powershell`). Verify that your colcon workspace contains valid packages that produce build artifacts. Check colcon log output for any errors during extension discovery.
```
File C:\path\to\install\setup.ps1 cannot be loaded because running scripts is disabled on this system.
```
cause Windows PowerShell's execution policy is set too restrictively, preventing local scripts from running.

fix Temporarily or permanently adjust the execution policy. For the current user, run `Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned` in an elevated PowerShell session.

Warnings

gotcha PowerShell Execution Policy on Windows can prevent sourcing setup scripts. By default, scripts downloaded from the internet or created locally might be blocked.
Fix: Before sourcing, run `Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned` in PowerShell to allow locally created scripts to run. Adjust scope and policy as needed for security requirements.
gotcha colcon-powershell requires PowerShell to be installed and available in the system's PATH. While colcon itself is cross-platform, the generated PowerShell scripts naturally require a PowerShell environment to be sourced.
Fix: Ensure PowerShell is installed on your system (natively on Windows, via `pwsh` on Linux/macOS) and accessible from your environment. Verify with `pwsh --version` or `powershell.exe -Command '$PSVersionTable.PSVersion'`.
gotcha If multiple shell extensions (e.g., colcon-powershell, colcon-bash, colcon-zsh) are installed, colcon will generate setup files for all. However, only one set of environment variables (from one shell's setup file) can be active in a given shell session.
Fix: Choose the appropriate `setup.*` file (`setup.ps1`, `setup.bash`, etc.) for your specific shell and source only that one. For example, in PowerShell, use `. install/setup.ps1`.

Install

pip install colcon-powershell Install using pip

Imports

__version__
```
from colcon_powershell import __version__
```
colcon-powershell is primarily a colcon extension and is used via the 'colcon' CLI, not typically imported directly by end-user Python applications. This import is mainly for internal inspection.

Quickstart

This quickstart demonstrates how to programmatically trigger a 'colcon build' operation that leverages 'colcon-powershell' to generate environment setup scripts. It creates a minimal colcon workspace, runs a build, and then verifies that the 'setup.ps1' script (which is characteristic of colcon-powershell's output) has been generated in the install space. This confirms that the extension is active and functioning.

import os
import subprocess
import shutil

# --- Setup a dummy colcon workspace ---
workspace_root = 'colcon_ws_powershell'
package_name = 'my_powershell_pkg'
pkg_path = os.path.join(workspace_root, 'src', package_name)

# Cleanup previous run if exists
if os.path.exists(workspace_root):
    shutil.rmtree(workspace_root)
os.makedirs(pkg_path, exist_ok=True)

# Create minimal package.xml and CMakeLists.txt
with open(os.path.join(pkg_path, 'package.xml'), 'w') as f:
    f.write(f'''<?xml version="1.0"?><package format="3"><name>{package_name}</name><version>0.0.0</version><description>Dummy</description><maintainer email="a@b.com">User</maintainer><license>Apache-2.0</license><buildtool_depend>ament_cmake</buildtool_depend><export><build_type>ament_cmake</build_type></export></package>''')
with open(os.path.join(pkg_path, 'CMakeLists.txt'), 'w') as f:
    f.write("cmake_minimum_required(VERSION 3.8)\nproject(my_powershell_pkg NONE)\n")

print(f"Created dummy package '{package_name}'")

# --- Run colcon build ---
print("Running 'colcon build'...")
try:
    # Use encoding='utf-8' for consistent output handling across OS
    subprocess.run(
        ['colcon', 'build', '--base-paths', workspace_root],
        capture_output=True, text=True, check=True, encoding='utf-8'
    )
    print("colcon build finished.")
except FileNotFoundError:
    print("ERROR: 'colcon' command not found. Install 'colcon-core'.")
    exit(1)
except subprocess.CalledProcessError as e:
    print(f"ERROR during colcon build: {e.returncode}")
    print(f"STDOUT:\n{e.stdout}")
    print(f"STDERR:\n{e.stderr}")
    exit(1)

# --- Verify generated PowerShell scripts ---
install_base = os.path.join(workspace_root, 'install')
setup_ps1_path = os.path.join(install_base, 'setup.ps1')

print(f"\nChecking for generated PowerShell setup scripts in '{install_base}'...")
if os.path.exists(setup_ps1_path):
    print(f"SUCCESS: Found '{setup_ps1_path}'")
else:
    print(f"FAILURE: '{setup_ps1_path}' not found. Make sure colcon-powershell is installed and colcon-core is correctly configured.")

# Clean up (optional, good practice)
# shutil.rmtree(workspace_root)
# print(f"\nCleaned up workspace '{workspace_root}'")

view raw JSON →