{"id":4904,"library":"catkin-pkg","title":"catkin-pkg: Catkin Package Library","description":"catkin-pkg is a standalone Python library designed to support the Catkin build system, primarily used in the Robot Operating System (ROS) ecosystem. It provides functionalities for finding, introspecting, and managing Catkin packages within the file system, including parsing `package.xml` manifest files. The current version is 1.1.0, and it maintains an active development status with periodic releases.","status":"active","version":"1.1.0","language":"en","source_language":"en","source_url":"https://github.com/ros-infrastructure/catkin_pkg","tags":["ros","catkin","build-system","package-management","robotics"],"install":[{"cmd":"pip install catkin-pkg","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"Package","correct":"from catkin_pkg.package import Package"},{"note":"Import specific functions or classes directly for clarity and better tree-shaking.","wrong":"import catkin_pkg.package.parse_package","symbol":"parse_package","correct":"from catkin_pkg.package import parse_package"},{"symbol":"find_packages","correct":"from catkin_pkg.packages import find_packages"}],"quickstart":{"code":"import os\nimport tempfile\nimport shutil\nfrom pathlib import Path\nfrom catkin_pkg.packages import find_packages\n\n# Create a dummy catkin workspace for demonstration\ntemp_dir = Path(tempfile.mkdtemp())\nworkspace_path = temp_dir / \"my_catkin_ws\"\nsrc_path = workspace_path / \"src\"\nsrc_path.mkdir(parents=True, exist_ok=True)\n\n# Create a dummy package A\npkg_a_path = src_path / \"package_a\"\npkg_a_path.mkdir(exist_ok=True)\n(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>\"\"\")\n\n# Create a dummy package B depending on A\npkg_b_path = src_path / \"package_b\"\npkg_b_path.mkdir(exist_ok=True)\n(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>\"\"\")\n\n# Find and parse packages\nprint(f\"Searching for packages in: {src_path}\")\nfound_packages = find_packages(str(src_path))\n\nprint(f\"Found {len(found_packages)} packages:\")\nfor path, pkg in found_packages.items():\n    print(f\"- Path: {path}\")\n    print(f\"  Name: {pkg.name}\")\n    print(f\"  Version: {pkg.version}\")\n    print(f\"  Description: {pkg.description}\")\n    print(f\"  Dependencies:\")\n    for dep in pkg.buildtool_depends:\n        print(f\"    Buildtool: {dep.name}\")\n    for dep in pkg.depends:\n        print(f\"    Runtime/Build: {dep.name}\")\n\n# Clean up the dummy workspace\nshutil.rmtree(temp_dir)","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions of Catkin tools"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If changes are not being picked up, try running `catkin clean --force` followed by `catkin build` to force a complete rebuild.","message":"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.","severity":"gotcha","affected_versions":"All versions of Catkin tools"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}