Table Of Contents

Previous topic

Catkin Python API

Next topic

interrogate_setup_dot_py Module

This Page

catkin Package

find_in_workspaces Module

catkin.find_in_workspaces.find_in_workspaces(search_dirs=None, project=None, path=None, _workspaces=None, considered_paths=None, first_matching_workspace_only=False, first_match_only=False, workspace_to_source_spaces=None, source_path_to_packages=None)[source]

Find all paths which match the search criteria. All workspaces are searched in order. Each workspace, each search_in subfolder, the project name and the path are concatenated to define a candidate path. If the candidate path exists it is appended to the result list. Note: the search might return multiple paths for ‘share’ from devel- and source-space.

  • search_dir – The list of subfolders to search in (default contains all valid values: ‘bin’, ‘etc’, ‘lib’, ‘libexec’, ‘share’), list
  • project – The project name to search for (optional, not possible with the global search_in folders ‘bin’ and ‘lib’), str
  • path – The path, str
  • _workspaces – (optional, used for unit tests), the list of workspaces to use.
  • considered_paths – If not None, function will append all path that were searched
  • first_matching_workspace_only – if True returns all results found for first workspace with results
  • first_match_only – if True returns first path found (supercedes first_matching_workspace_only)
  • workspace_to_source_spaces – the dictionary is populated with mappings from workspaces to source paths, pass in the same dictionary to avoid repeated reading of the catkin marker file
  • source_path_to_packages – the dictionary is populated with mappings from source paths to packages, pass in the same dictionary to avoid repeated crawling
Raises ValueError:

if search_dirs contains an invalid folder name


List of paths

init_workspace Module


Create a toplevel CMakeLists.txt in the root of a workspace.

The toplevel.cmake file is looked up either in the catkin workspaces contained in the CMAKE_PREFIX_PATH or relative to this file. Then it tries to create a symlink first and if that fails copies the file.

It installs manifest.xml to share/${PROJECT_NAME}.


The symlink is absolute when catkin is found outside the workspace_dir (since that indicates a different workspace and it may change relative location to the workspace referenced as a parameter). The symlink is relative when catkin is part of the to-be-initialized workspace.

Parameters:workspace_dir (string) – the path to the workspace where the CMakeLists.txt should be created

package_version Module

catkin.package_version.rename_section(data, old_label, new_label)[source]
catkin.package_version.update_changelog_sections(changelogs, new_version)[source]
catkin.package_version.update_versions(paths, new_version)[source]

bulk replace of version: searches for package.xml files directly in given folders and replaces version tag within.

  • paths – list of string, folder names
  • new_version – version string “”
Raises RuntimeError:

if any one package.xml cannot be updated

test_results Module

catkin.test_results.aggregate_results(results, callback_per_result=None)[source]

Same as aggregate_results2 except it doesn’t return num_skipped.

catkin.test_results.aggregate_results2(results, callback_per_result=None)[source]

Aggregate results

Parameters:results – dict as from test_results()
Returns:tuple (num_tests, num_errors, num_failures, num_skipped)
catkin.test_results.print_summary(results, show_stable=False, show_unstable=True)[source]

Same as print_summary2 except it doesn’t print skipped tests.

catkin.test_results.print_summary2(results, show_stable=False, show_unstable=True, print_skipped=True)[source]

print summary to stdout

  • results – dict as from test_results()
  • show_stable – print tests without failures extra
  • show_stable – print tests with failures extra
  • print_skipped – include skipped tests in output

Same as read_junit2 except it doesn’t return num_skipped.


parses xml file expected to follow junit/gtest conventions see


filename – str junit xml file name


num_tests, num_errors, num_failures, num_skipped

  • ParseError – if xml is not well-formed
  • IOError – if filename does not exist
catkin.test_results.test_results(test_results_dir, show_verbose=False, show_all=False)[source]

Same as test_results2 except the returned values don’t include num_skipped.

catkin.test_results.test_results2(test_results_dir, show_verbose=False, show_all=False)[source]

Collects test results by parsing all xml files in given path, attempting to interpret them as junit results.

  • test_results_dir – str foldername
  • show_verbose – bool show output for tests which had errors or failed

dict {rel_path, (num_tests, num_errors, num_failures, num_skipped)}

tidy_xml Module


read in file, screen out unsafe unicode characters, write back file in utf-8

Parameters:filename – str
Returns:False if unable to read from file

workspace Module


reads catkin workspace files and returns the list of all declared source paths

Parameters:workspace – path to catkin workspace folder, str

Based on CMAKE_PREFIX_PATH return all catkin workspaces

Parameters:_environ – environment module to use, dict

workspace_vcs Module

catkin.workspace_vcs.vcs_remotes(path, vcs_type=None)[source]