cargo module install from source in a given directory (#8480)

* Fixes installed version for git/local.

* Support latest determination with local source.

* Adds docs.

* Improves error message.

* Setup for tests.

* Updates copyright.

* Align closer to #7895.

* Adds changelog.

* Check directory exists.

* Stop using format strings.

* Corrects directory arg type in docs.

* Setup test repo dynamically.

* Adds tests.

* Adds version matching tests.

* Update changelog fragment to match PR ID.

* Updates copyright.

* Import new directory tests.

plugins/modules/cargo.py

@@ -1,6 +1,7 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 # Copyright (c) 2021 Radek Sprta <mail@radeksprta.eu>
+# Copyright (c) 2024 Colin Nolan <cn580@alumni.york.ac.uk>
 # GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
 # SPDX-License-Identifier: GPL-3.0-or-later
 
@@ -65,6 +66,13 @@ options:
     type: str
     default: present
     choices: [ "present", "absent", "latest" ]
+  directory:
+    description:
+      - Path to the source directory to install the Rust package from.
+      - This is only used when installing packages.
+    type: path
+    required: false
+    version_added: 9.1.0
 requirements:
     - cargo installed
 """
@@ -98,8 +106,14 @@ EXAMPLES = r"""
   community.general.cargo:
     name: ludusavi
     state: latest
+
+- name: Install "ludusavi" Rust package from source directory
+  community.general.cargo:
+    name: ludusavi
+    directory: /path/to/ludusavi/source
 """
 
+import json
 import os
 import re
 
@@ -115,6 +129,7 @@ class Cargo(object):
         self.state = kwargs["state"]
         self.version = kwargs["version"]
         self.locked = kwargs["locked"]
+        self.directory = kwargs["directory"]
 
     @property
     def path(self):
@@ -143,7 +158,7 @@ class Cargo(object):
 
         data, dummy = self._exec(cmd, True, False, False)
 
-        package_regex = re.compile(r"^([\w\-]+) v(.+):$")
+        package_regex = re.compile(r"^([\w\-]+) v(\S+).*:$")
         installed = {}
         for line in data.splitlines():
             package_info = package_regex.match(line)
@@ -163,19 +178,53 @@ class Cargo(object):
         if self.version:
             cmd.append("--version")
             cmd.append(self.version)
+        if self.directory:
+            cmd.append("--path")
+            cmd.append(self.directory)
         return self._exec(cmd)
 
     def is_outdated(self, name):
         installed_version = self.get_installed().get(name)
+        latest_version = (
+            self.get_latest_published_version(name)
+            if not self.directory
+            else self.get_source_directory_version(name)
+        )
+        return installed_version != latest_version
 
+    def get_latest_published_version(self, name):
         cmd = ["search", name, "--limit", "1"]
         data, dummy = self._exec(cmd, True, False, False)
 
         match = re.search(r'"(.+)"', data)
-        if match:
-            latest_version = match.group(1)
+        if not match:
+            self.module.fail_json(
+                msg="No published version for package %s found" % name
+            )
+        return match.group(1)
 
-        return installed_version != latest_version
+    def get_source_directory_version(self, name):
+        cmd = [
+            "metadata",
+            "--format-version",
+            "1",
+            "--no-deps",
+            "--manifest-path",
+            os.path.join(self.directory, "Cargo.toml"),
+        ]
+        data, dummy = self._exec(cmd, True, False, False)
+        manifest = json.loads(data)
+
+        package = next(
+            (package for package in manifest["packages"] if package["name"] == name),
+            None,
+        )
+        if not package:
+            self.module.fail_json(
+                msg="Package %s not defined in source, found: %s"
+                % (name, [x["name"] for x in manifest["packages"]])
+            )
+        return package["version"]
 
     def uninstall(self, packages=None):
         cmd = ["uninstall"]
@@ -191,16 +240,21 @@ def main():
         state=dict(default="present", choices=["present", "absent", "latest"]),
         version=dict(default=None, type="str"),
         locked=dict(default=False, type="bool"),
+        directory=dict(default=None, type="path"),
     )
     module = AnsibleModule(argument_spec=arg_spec, supports_check_mode=True)
 
     name = module.params["name"]
     state = module.params["state"]
     version = module.params["version"]
+    directory = module.params["directory"]
 
     if not name:
         module.fail_json(msg="Package name must be specified")
 
+    if directory is not None and not os.path.isdir(directory):
+        module.fail_json(msg="Source directory does not exist")
+
     # Set LANG env since we parse stdout
     module.run_command_environ_update = dict(
         LANG="C", LC_ALL="C", LC_MESSAGES="C", LC_CTYPE="C"