pacman: add 'executable' option to use an alternative pacman binary (#2524) (#2554)

* Add 'bin' option to use an alternative pacman binary

* Add changelog entry

* Incorporate recommendations

* Update plugins/modules/packaging/os/pacman.py

* Apply suggestions from code review

Co-authored-by: Felix Fontein <felix@fontein.de>
(cherry picked from commit c4624d3ad8)

Co-authored-by: Andre Lehmann <aisberg@posteo.de>

changelogs/fragments/2524-pacman_add_bin_option.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - pacman - add ``executable`` option to use an alternative pacman binary (https://github.com/ansible-collections/community.general/issues/2524).

plugins/modules/packaging/os/pacman.py

@@ -44,6 +44,14 @@ options:
         default: no
         type: bool
 
+    executable:
+        description:
+            - Name of binary to use. This can either be C(pacman) or a pacman compatible AUR helper.
+            - Beware that AUR helpers might behave unexpectedly and are therefore not recommended.
+        default: pacman
+        type: str
+        version_added: 3.1.0
+
     extra_args:
         description:
             - Additional option to pass to pacman when enforcing C(state).
@@ -79,8 +87,10 @@ options:
         type: str
 
 notes:
-  - When used with a `loop:` each package will be processed individually,
+  - When used with a C(loop:) each package will be processed individually,
-    it is much more efficient to pass the list directly to the `name` option.
+    it is much more efficient to pass the list directly to the I(name) option.
+  - To use an AUR helper (I(executable) option), a few extra setup steps might be required beforehand.
+    For example, a dedicated build user with permissions to install packages could be necessary.
 '''
 
 RETURN = '''
@@ -109,6 +119,13 @@ EXAMPLES = '''
       - ~/bar-1.0-1-any.pkg.tar.xz
     state: present
 
+- name: Install package from AUR using a Pacman compatible AUR helper
+  community.general.pacman:
+    name: foo
+    state: present
+    executable: yay
+    extra_args: --builddir /var/cache/yay
+
 - name: Upgrade package foo
   community.general.pacman:
     name: foo
@@ -419,6 +436,7 @@ def main():
             name=dict(type='list', elements='str', aliases=['pkg', 'package']),
             state=dict(type='str', default='present', choices=['present', 'installed', 'latest', 'absent', 'removed']),
             force=dict(type='bool', default=False),
+            executable=dict(type='str', default='pacman'),
             extra_args=dict(type='str', default=''),
             upgrade=dict(type='bool', default=False),
             upgrade_extra_args=dict(type='str', default=''),
@@ -432,11 +450,13 @@ def main():
         supports_check_mode=True,
     )
 
-    pacman_path = module.get_bin_path('pacman', True)
     module.run_command_environ_update = dict(LC_ALL='C')
 
     p = module.params
 
+    # find pacman binary
+    pacman_path = module.get_bin_path(p['executable'], True)
+
     # normalize the state parameter
     if p['state'] in ['present', 'installed']:
         p['state'] = 'present'