catkin-pkg: Catkin Package Library

Warnings

• gotcha Do not install `catkin-pkg-modules` from PyPI. The `catkin-pkg-modules` package exists on Debian/Ubuntu for specific Python 2/3 co-installation scenarios, but for pip installations, `catkin-pkg` provides all necessary Python modules. Installing `catkin-pkg-modules` via pip is unnecessary and was previously a duplicated effort.
  Fix: Only install `catkin-pkg` via pip. If encountering issues related to `catkin-pkg-modules`, ensure you are not mixing system-installed (apt) and pip-installed Python packages for Catkin.
• gotcha Mixing Catkin build tools (e.g., building with `catkin_make` or `catkin_make_isolated` and then `catkin build` from `catkin_tools`) can lead to an 'Inconsistent Environment' and unpredictable build failures due to cached configuration differences.
  Fix: Always use a single build tool for a given workspace. If switching, perform a `catkin clean` before rebuilding, or start with a fresh workspace.
• gotcha Packages with incorrect or implicitly satisfied dependencies in their `package.xml` files (e.g., relying on side-effects of other packages in the same workspace) can fail to build or link correctly when using stricter build tools or migrating workspaces. Common errors include 'Unknown CMake command “catkin_package”' or missing headers/libraries.
  Fix: Ensure all direct dependencies are explicitly listed in `package.xml` and `CMakeLists.txt`. Verify packages build correctly in isolation before integrating them into a larger workspace.
• gotcha When using `catkin build` (part of `catkin_tools`), sometimes local changes to source files are not detected, leading to stale executables or libraries. This is often a caching issue in the build system.
  Fix: If changes are not being picked up, try running `catkin clean --force` followed by `catkin build` to force a complete rebuild.

Install

• pip install catkin-pkg Install latest version

Imports

• Package

  from catkin_pkg.package import Package

• parse_package

  from catkin_pkg.package import parse_package

  Import specific functions or classes directly for clarity and better tree-shaking.
• find_packages

  from catkin_pkg.packages import find_packages

Quickstart

This quickstart demonstrates how to use `catkin_pkg` to find and introspect Catkin packages within a directory. It creates a temporary directory simulating a Catkin workspace, adds two dummy packages with `package.xml` files, and then uses `find_packages` to locate and parse them, printing out key metadata for each.

import os
import tempfile
import shutil
from pathlib import Path
from catkin_pkg.packages import find_packages

# Create a dummy catkin workspace for demonstration
temp_dir = Path(tempfile.mkdtemp())
workspace_path = temp_dir / "my_catkin_ws"
src_path = workspace_path / "src"
src_path.mkdir(parents=True, exist_ok=True)

# Create a dummy package A
pkg_a_path = src_path / "package_a"
pkg_a_path.mkdir(exist_ok=True)
(pkg_a_path / "package.xml").write_text("""<?xml version=\"1.0\"?>\n<package format=\"2\">\n  <name>package_a</name>\n  <version>0.1.0</version>\n  <description>A dummy package A</description>\n  <maintainer email=\"user@example.com\">User Name</maintainer>\n  <license>MIT</license>\n  <buildtool_depend>catkin</buildtool_depend>\n  <depend>python3-catkin-pkg</depend>\n</package>""")

# Create a dummy package B depending on A
pkg_b_path = src_path / "package_b"
pkg_b_path.mkdir(exist_ok=True)
(pkg_b_path / "package.xml").write_text("""<?xml version=\"1.0\"?>\n<package format=\"2\">\n  <name>package_b</name>\n  <version>0.1.0</version>\n  <description>A dummy package B</description>\n  <maintainer email=\"user@example.com\">User Name</maintainer>\n  <license>MIT</license>\n  <buildtool_depend>catkin</buildtool_depend>\n  <depend>package_a</depend>\n</package>""")

# Find and parse packages
print(f"Searching for packages in: {src_path}")
found_packages = find_packages(str(src_path))

print(f"Found {len(found_packages)} packages:")
for path, pkg in found_packages.items():
    print(f"- Path: {path}")
    print(f"  Name: {pkg.name}")
    print(f"  Version: {pkg.version}")
    print(f"  Description: {pkg.description}")
    print(f"  Dependencies:")
    for dep in pkg.buildtool_depends:
        print(f"    Buildtool: {dep.name}")
    for dep in pkg.depends:
        print(f"    Runtime/Build: {dep.name}")

# Clean up the dummy workspace
shutil.rmtree(temp_dir)