colcon-notification

0.3.1 · active · verified Thu Apr 16

colcon-notification is an extension for the `colcon` meta build tool, primarily used within the Robot Operating System (ROS) ecosystem, to provide status notifications. It enables desktop notifications and updates a status line in the terminal title during `colcon` invocations like `build` or `test`. The current version is 0.3.1, and it maintains an active development and release cadence in line with the broader `colcon` and ROS projects.

Common errors

```
ERROR：Could not find the colcon-terminal-notifier.app in the install prefix '/usr/local
```
cause Mismatch in the application name (colcon_terminal_notifier.app vs colcon-terminal-notifier.app) for the macOS notification tool, typically on older versions or specific build setups.

fix Update `colcon-notification` to a newer version (post-0.2.19) where this was resolved. If updating is not an option, manually verify and correct the application name in the install prefix or in the `terminal_notifier.py` file.
```
Exception in desktop notification extension 'notify2':org.freedesktop.DBus.Error.NoReply: Message recipient disconnected from message bus without replying.
```
cause The `notify2` backend (used for desktop notifications on Linux) failed to connect or send a message via the D-Bus message bus, often due to a misconfigured desktop environment or D-Bus service.

fix Check your desktop environment's D-Bus setup and notification service. If the issue persists, disable desktop notifications for `colcon` using `colcon <verb> --event-handlers desktop_notification-` or set `COLCON_EXTENSION_BLOCKLIST=colcon_core.event_handler.desktop_notification`.
```
Unwanted or annoying desktop notifications pop up during colcon builds.
```
cause Desktop notifications are enabled by default through the `desktop_notification` event handler within colcon-notification.

fix Disable them per invocation with `colcon <verb> --event-handlers desktop_notification-`. For a system-wide disable, set the environment variable `COLCON_EXTENSION_BLOCKLIST=colcon_core.event_handler.desktop_notification`.

Warnings

breaking The environment variable to blacklist/block extensions was renamed from `COLCON_EXTENSION_BLACKLIST` to `COLCON_EXTENSION_BLOCKLIST`.
Fix: Update your environment variables or scripts to use `COLCON_EXTENSION_BLOCKLIST`.
gotcha Desktop notifications can be intrusive and are often enabled by default. Users frequently want to disable them.
Fix: To disable desktop notifications for a single invocation, use `colcon <verb> --event-handlers desktop_notification-`. To disable them system-wide, set the environment variable `COLCON_EXTENSION_BLOCKLIST=colcon_core.event_handler.desktop_notification`.
gotcha On some Linux desktop environments (e.g., Pop OS + Regolith), desktop notifications might fail with D-Bus related errors.
Fix: Ensure your D-Bus system is properly configured and accessible for desktop notifications. If issues persist, consider disabling desktop notifications using the `--event-handlers desktop_notification-` flag or `COLCON_EXTENSION_BLOCKLIST` environment variable.
gotcha On macOS, older versions had an issue with the `terminal-notifier.app` path due to a mismatch in naming conventions (underscore vs. dash).
Fix: This issue has been addressed in recent versions. If encountered with older installations, a workaround was to manually rename the `colcon_terminal_notifier.app` to `colcon-terminal-notifier.app` or modify `terminal_notifier.py`.

Install

pip install colcon-notification Install via pip

Imports

Extension functionality
```
colcon build --event-handlers desktop_notification+
```
colcon-notification is an extension, not typically imported directly into user Python scripts. Its functionality is enabled via colcon command-line arguments or configuration as an event handler.

Quickstart

colcon-notification provides event handlers for the `colcon` command-line tool. To use its features, you typically invoke `colcon` with specific `--event-handlers` arguments. `desktop_notification+` enables desktop pop-up notifications, while `status+` shows a continuously updating status line in your terminal title.

# This is not a Python import, but how to use the notification feature through colcon CLI.
# To build a workspace and enable desktop notifications:
mkdir -p ~/my_ros2_ws/src
cd ~/my_ros2_ws
# Populate src/ with colcon-compatible packages (e.g., ROS 2 examples)
# git clone https://github.com/ros2/examples src/examples

# Build with desktop notifications enabled
colcon build --event-handlers desktop_notification+

# Or to only show a status line in the terminal title
colcon build --event-handlers status+

view raw JSON →