{"id":9607,"library":"colcon-powershell","title":"Colcon PowerShell Extension","description":"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.","status":"active","version":"0.5.0","language":"en","source_language":"en","source_url":"https://github.com/colcon/colcon-powershell/","tags":["colcon","ROS","PowerShell","build-system","plugin","automation"],"install":[{"cmd":"pip install colcon-powershell","lang":"bash","label":"Install using pip"}],"dependencies":[{"reason":"Provides the core 'colcon' command-line tool which this library extends.","package":"colcon-core","optional":false},{"reason":"Required Python interpreter version for the package.","package":"Python","version":">=3.6","optional":false}],"imports":[{"note":"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.","symbol":"__version__","correct":"from colcon_powershell import __version__"}],"quickstart":{"code":"import os\nimport subprocess\nimport shutil\n\n# --- Setup a dummy colcon workspace ---\nworkspace_root = 'colcon_ws_powershell'\npackage_name = 'my_powershell_pkg'\npkg_path = os.path.join(workspace_root, 'src', package_name)\n\n# Cleanup previous run if exists\nif os.path.exists(workspace_root):\n    shutil.rmtree(workspace_root)\nos.makedirs(pkg_path, exist_ok=True)\n\n# Create minimal package.xml and CMakeLists.txt\nwith open(os.path.join(pkg_path, 'package.xml'), 'w') as f:\n    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>''')\nwith open(os.path.join(pkg_path, 'CMakeLists.txt'), 'w') as f:\n    f.write(\"cmake_minimum_required(VERSION 3.8)\\nproject(my_powershell_pkg NONE)\\n\")\n\nprint(f\"Created dummy package '{package_name}'\")\n\n# --- Run colcon build ---\nprint(\"Running 'colcon build'...\")\ntry:\n    # Use encoding='utf-8' for consistent output handling across OS\n    subprocess.run(\n        ['colcon', 'build', '--base-paths', workspace_root],\n        capture_output=True, text=True, check=True, encoding='utf-8'\n    )\n    print(\"colcon build finished.\")\nexcept FileNotFoundError:\n    print(\"ERROR: 'colcon' command not found. Install 'colcon-core'.\")\n    exit(1)\nexcept subprocess.CalledProcessError as e:\n    print(f\"ERROR during colcon build: {e.returncode}\")\n    print(f\"STDOUT:\\n{e.stdout}\")\n    print(f\"STDERR:\\n{e.stderr}\")\n    exit(1)\n\n# --- Verify generated PowerShell scripts ---\ninstall_base = os.path.join(workspace_root, 'install')\nsetup_ps1_path = os.path.join(install_base, 'setup.ps1')\n\nprint(f\"\\nChecking for generated PowerShell setup scripts in '{install_base}'...\")\nif os.path.exists(setup_ps1_path):\n    print(f\"SUCCESS: Found '{setup_ps1_path}'\")\nelse:\n    print(f\"FAILURE: '{setup_ps1_path}' not found. Make sure colcon-powershell is installed and colcon-core is correctly configured.\")\n\n# Clean up (optional, good practice)\n# shutil.rmtree(workspace_root)\n# print(f\"\\nCleaned up workspace '{workspace_root}'\")","lang":"python","description":"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."},"warnings":[{"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.","message":"PowerShell Execution Policy on Windows can prevent sourcing setup scripts. By default, scripts downloaded from the internet or created locally might be blocked.","severity":"gotcha","affected_versions":"All"},{"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'`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install `colcon-core` and common extensions: `pip install colcon-core colcon-common-extensions`.","cause":"The 'colcon' command-line tool is not installed or not in your system's PATH.","error":"colcon: command not found"},{"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.","cause":"colcon-powershell was not active during the build, or there was no build output that required generating PowerShell scripts.","error":"FAILURE: 'setup.ps1' not found. Make sure colcon-powershell is installed and colcon-core is correctly configured."},{"fix":"Temporarily or permanently adjust the execution policy. For the current user, run `Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned` in an elevated PowerShell session.","cause":"Windows PowerShell's execution policy is set too restrictively, preventing local scripts from running.","error":"File C:\\path\\to\\install\\setup.ps1 cannot be loaded because running scripts is disabled on this system."}]}