Add support for cargo workspaces (#59)

* Specify package name in cargo operations

When inspecting the output from `cargo metadata` and when invoking other
cargo commands like `build`, `test`, and `fmt`, we should specify the
name of the package we're operating on.

When a package is part of a cargo workspace, these operations will
normally encompass the whole workspace but colcon operates on a
per-package basis, so we need to limit the scope to the specific package
we're working with.

* Add support for cargo workspaces

This change adds support for cargo workspaces, both virtual workspaces
and ones with top-level packages. It does so by caching the paths to the
workspace members as the workspaces are discovered by "primary"
discovery mechanisms (like a recursive crawl) and then specifically
loads packages from those directories after the primary discovery
extensions have completed.

Note that all of the packages in a workspace are discovered regardless
of the "default-members" value in the workspace configuration.

A subtle change in behavior introduced by this change is that any
packages in subdirectories of a workspace which are not listed as a
workspace member will not be discovered. The presence of a valid
workspace configuration, while not strictly a package itself, should
serve as a declaration of what packages live in subdirectories of said
workspace and colcon should respect that.

* Use a separate identification extension for workspaces

* Filter out false detection of circular dependencies (#62)

* Add a comment about ignoring other workspace members

Co-authored-by: Michael X. Grey <mxgrey@intrinsic.ai>

Author: cottsay

colcon_cargo/package_augmentation/cargo.py

@@ -40,16 +40,21 @@ def _augment_package(
         if not package:
             return
 
+        package_name = package.get('name')
         version = package.get('version', '0.0.0')
         if not metadata.metadata.get('version'):
             metadata.metadata['version'] = version
 
-        dependencies = extract_dependencies(content, metadata.path)
+        dependencies = extract_dependencies(
+            package_name, content, metadata.path
+        )
         for k, v in dependencies.items():
             metadata.dependencies[k] |= v
 
         for category, spec in content.get('target', {}).items():
-            dependencies = extract_dependencies(spec, metadata.path)
+            dependencies = extract_dependencies(
+                package_name, spec, metadata.path
+            )
             for k, v in dependencies.items():
                 metadata.dependencies[k] |= v
 
@@ -59,7 +64,7 @@ def _augment_package(
             metadata.metadata['maintainers'] += authors
 
 
-def extract_dependencies(content, path):
+def extract_dependencies(package_name, content, path):
     """
     Get the dependencies of a Cargo package.
 
@@ -68,29 +73,56 @@ def extract_dependencies(content, path):
     :returns: The dependencies
     :rtype: dict(string, set(DependencyDescriptor))
     """
-    name = content.get('name')
     depends = {
         create_dependency_descriptor(k, v, path)
-        for k, v in content.get('dependencies', {}).items()
-        if k != name
+        for k, v in filter_dependency_list(
+            content.get('dependencies', {}).items()
+        )
     }
     build_depends = {
         create_dependency_descriptor(k, v, path)
-        for k, v in content.get('build-dependencies', {}).items()
-        if k != name
+        for k, v in filter_dependency_list(
+            content.get('build-dependencies', {}).items()
+        )
     }
     dev_depends = {
         create_dependency_descriptor(k, v, path)
-        for k, v in content.get('dev-dependencies', {}).items()
-        if k != name
+        for k, v in filter_dependency_list(
+            content.get('dev-dependencies', {}).items(),
+            filter_out=package_name,
+        )
     }
     return {
         'build': depends | build_depends | dev_depends,
         'run': depends | build_depends,
     }
 
 
-def create_dependency_descriptor(name, constraints, path):
+def filter_dependency_list(dependencies, filter_out=None):
+    """
+    Filter dependency names.
+
+    Find the external names of dependencies and optionally filter out any that
+    match a pattern. The filtering is used for dev-dependencies which may have
+    the package itself as a dependency.
+
+    :param dependencies: The dictionary of every dependency and its constraints
+    :param filter_out: The name of a dependency to filter out.
+    :returns: The filtered dependency list with the external names as keys
+    :rtype: dict(string, dict)
+    """
+    filtered_dependencies = {}
+    for dependency, constraints in dependencies:
+        if isinstance(constraints, dict):
+            dependency = constraints.get('package', dependency)
+
+        if dependency != filter_out:
+            filtered_dependencies[dependency] = constraints
+
+    return filtered_dependencies.items()
+
+
+def create_dependency_descriptor(dependency_name, constraints, path):
     """
     Create a dependency descriptor from a Cargo dependency specification.
 
@@ -109,7 +141,6 @@ def create_dependency_descriptor(name, constraints, path):
         else:
             source = constraints.get('git') or \
                 constraints.get('registry')
-        name = constraints.get('package', name)
     else:
         source = None
     metadata = {
@@ -118,4 +149,4 @@ def create_dependency_descriptor(name, constraints, path):
     }
     # TODO: Interpret SemVer constraints and add appropriate constraint
     #       metadata. Handling arbitrary wildcards will be non-trivial.
-    return DependencyDescriptor(name, metadata=metadata)
+    return DependencyDescriptor(dependency_name, metadata=metadata)

colcon_cargo/package_discovery/__init__.py

@@ -0,0 +1,48 @@
+# Copyright 2025 Open Source Robotics Foundation, Inc.
+# Licensed under the Apache License, Version 2.0
+
+from colcon_cargo.package_identification.cargo_workspace \
+    import CargoWorkspaceIdentification
+from colcon_core.package_discovery import PackageDiscoveryExtensionPoint
+from colcon_core.package_identification import identify
+from colcon_core.package_identification import IgnoreLocationException
+from colcon_core.plugin_system import satisfies_version
+
+
+class CargoWorkspacePackageDiscovery(PackageDiscoveryExtensionPoint):
+    """Discover packages which are part of a cargo workspace."""
+
+    # the priority should be very low because we need to discover the
+    # workspaces themselves before we can enumerate their sub-packages
+    PRIORITY = 10
+
+    def __init__(self):  # noqa: D107
+        super().__init__()
+        satisfies_version(
+            PackageDiscoveryExtensionPoint.EXTENSION_POINT_VERSION,
+            '^1.1')
+
+    def has_parameters(self, *, args):  # noqa: D102
+        return None
+
+    def discover(self, *, args, identification_extensions):  # noqa: D102
+        # Nested workspaces are not currently supported by cargo. If they ever
+        # are, this code should be updated to run the whole process again until
+        # no additional member package paths are found.
+
+        paths = set()
+        for extensions_same_prio in identification_extensions.values():
+            for extension in extensions_same_prio.values():
+                if isinstance(extension, CargoWorkspaceIdentification):
+                    paths.update(extension.workspace_package_paths)
+                    extension.workspace_package_paths.clear()
+
+        descs = set()
+        for path in paths:
+            try:
+                result = identify(identification_extensions, path)
+            except IgnoreLocationException:
+                continue
+            if result:
+                descs.add(result)
+        return descs

colcon_cargo/package_discovery/cargo_workspace.py

@@ -39,12 +39,10 @@ def identify(self, metadata):  # noqa: D102
             return
 
         content = read_cargo_toml(cargo_toml)
-        if 'workspace' in content:
-            logger.debug(
-                f'Ignoring unsupported Cargo Workspace at {metadata.path}')
+        package = content.get('package', {})
+        if not package:
             return
 
-        package = content.get('package', {})
         name = package.get('name')
         if not name and not metadata.name:
             raise RuntimeError(

colcon_cargo/package_identification/cargo.py

@@ -0,0 +1,57 @@
+# Copyright 2025 Open Source Robotics Foundation, Inc.
+# Licensed under the Apache License, Version 2.0
+
+from colcon_cargo.package_identification.cargo import read_cargo_toml
+from colcon_core.package_identification import IgnoreLocationException
+from colcon_core.package_identification \
+    import PackageIdentificationExtensionPoint
+from colcon_core.plugin_system import satisfies_version
+
+
+class CargoWorkspaceIdentification(PackageIdentificationExtensionPoint):
+    """
+    Identify Cargo workspaces with `Cargo.toml` files.
+
+    This extension does not actually identify any packages per se, but is a
+    necessary component for CargoWorkspacePackageDiscovery to function.
+    """
+
+    # This
+    PRIORITY = 990
+
+    def __init__(self):  # noqa: D107
+        super().__init__()
+        satisfies_version(
+            PackageIdentificationExtensionPoint.EXTENSION_POINT_VERSION,
+            '^1.0')
+        self.workspace_package_paths = set()
+
+    def identify(self, metadata):  # noqa: D102
+        if metadata.type is not None and metadata.type != 'cargo':
+            return
+
+        cargo_toml = metadata.path / 'Cargo.toml'
+        if not cargo_toml.is_file():
+            return
+
+        content = read_cargo_toml(cargo_toml)
+        if 'workspace' not in content:
+            return
+
+        ws_members = {
+            member
+            for pattern in content['workspace'].get('members', ())
+            for member in metadata.path.glob(pattern)
+        }
+        ws_members.difference_update(
+            exclude
+            for pattern in content['workspace'].get('exclude', ())
+            for exclude in metadata.path.glob(pattern)
+        )
+        self.workspace_package_paths.update(ws_members)
+
+        if 'package' not in content:
+            # Prevent any further attempts to discover packages in this
+            # directory and let the workspace dictate where to look for
+            # packages later on
+            raise IgnoreLocationException()

colcon_cargo/package_identification/cargo_workspace.py

@@ -79,25 +79,26 @@ async def build(  # noqa: D102
 
         self.progress('build')
 
+        pkg = self.context.pkg
         rc = await run(
-            self.context, cmd, cwd=self.context.pkg.path, env=env)
+            self.context, cmd, cwd=pkg.path, env=env)
         if rc and rc.returncode:
             return rc.returncode
 
         # colcon-ros-cargo overrides install command to return None.
         # We also need to check if the package has any binaries, because if it
         # has no binaries then cargo install will return an error.
         cmd = self._install_cmd(cargo_args)
-        if cmd is not None and self._has_binaries(metadata):
+        if cmd is not None and self._has_binaries(metadata, pkg.name):
             self.progress('install')
             rc = await run(
-                self.context, cmd, cwd=self.context.pkg.path, env=env)
+                self.context, cmd, cwd=pkg.path, env=env)
             if rc and rc.returncode:
                 return rc.returncode
 
         if not skip_hook_creation:
             create_environment_scripts(
-                self.context.pkg, args, additional_hooks=additional_hooks)
+                pkg, args, additional_hooks=additional_hooks)
 
     # Overridden by colcon-ros-cargo
     def _prepare(self, env, additional_hooks):
@@ -111,10 +112,12 @@ def _prepare(self, env, additional_hooks):
     # Overridden by colcon-ros-cargo
     def _build_cmd(self, cargo_args):
         args = self.context.args
+        pkg = self.context.pkg
         cmd = [
             CARGO_EXECUTABLE,
             'build',
             '--quiet',
+            '--package', pkg.name,
             '--target-dir', args.build_base,
         ]
         if not any(
@@ -177,8 +180,13 @@ async def _get_metadata(self, env):
 
     # Identify if there are any binaries to install for the current package
     @staticmethod
-    def _has_binaries(metadata):
+    def _has_binaries(metadata, package_name):
         for package in metadata.get('packages', {}):
+            # If the package is part of a cargo workspace, the metadata
+            # contains all members. We're only interested in our target
+            # package - ignore the other workspace members here.
+            if package.get('name') != package_name:
+                continue
             for target in package.get('targets', {}):
                 for kind in target.get('kind', {}):
                     if kind == 'bin':

colcon_cargo/task/cargo/build.py

@@ -93,23 +93,26 @@ async def test(self, *, additional_hooks=None):  # noqa: D102
 
     def _test_cmd(self, cargo_args):
         args = self.context.args
+        pkg = self.context.pkg
         return [
             CARGO_EXECUTABLE,
             'test',
             '--quiet',
-            '--target-dir',
-            args.build_base,
+            '--package', pkg.name,
+            '--target-dir', args.build_base,
         ] + cargo_args + [
             '--',
             '--color=never',
         ]
 
     # Ignore cargo args for rustfmt
     def _fmt_cmd(self):
+        pkg = self.context.pkg
         return [
             CARGO_EXECUTABLE,
             'fmt',
             '--check',
+            '--package', pkg.name,
             '--',
             '--color=never',
         ]

colcon_cargo/task/cargo/test.py

@@ -24,7 +24,7 @@ keywords = colcon
 [options]
 python_requires = >=3.6
 install_requires =
-  colcon-core
+  colcon-core>=0.19.0
   # toml is also supported but deprecated
   tomli>=1.0.0; python_version < "3.11"
 packages = find:
@@ -67,8 +67,11 @@ colcon_argcomplete.argcomplete_completer =
     cargo_args = colcon_cargo.argcomplete_completer.cargo_args:CargoArgcompleteCompleter
 colcon_core.package_augmentation =
     cargo = colcon_cargo.package_augmentation.cargo:CargoPackageAugmentation
+colcon_core.package_discovery =
+    cargo_workspace = colcon_cargo.package_discovery.cargo_workspace:CargoWorkspacePackageDiscovery
 colcon_core.package_identification =
     cargo = colcon_cargo.package_identification.cargo:CargoPackageIdentification
+    cargo_workspace = colcon_cargo.package_identification.cargo_workspace:CargoWorkspaceIdentification
 colcon_core.task.build =
     cargo = colcon_cargo.task.cargo.build:CargoBuildTask
 colcon_core.task.test =

setup.cfg

@@ -1,6 +1,6 @@
 [colcon-cargo]
 No-Python2:
-Depends3: python3-colcon-core, python3 (>= 3.11) | python3-tomli (>= 1) | python3-toml
+Depends3: python3-colcon-core (>= 0.19.0), python3 (>= 3.11) | python3-tomli (>= 1) | python3-toml
 Suite: focal jammy noble bookworm trixie
 X-Python3-Version: >= 3.6
 Upstream-Version-Suffix: +upstream

stdeb.cfg

@@ -0,0 +1,9 @@
+[package]
+name = "rust-workspace"
+version = "0.1.0"
+authors = ["Test<test@test.com>"]
+edition = "2018"
+
+[workspace]
+members = ["workspace-mem*"]
+default-members = ["workspace-mem*"]