Add option to install tox into a path location

We can't do this all the time, because of rootless environments.
But sometimes people have root and want to be able to use something
from scripts from normal path.

Change-Id: I3f57a6108f8f53ebfdd12f04ecb3d8c68c5b4a60

roles/ensure-tox/README.rst

@@ -16,6 +16,17 @@ virtual environment for the current user.
    will be automatically set to `True` to enable a Python 2
    installation of `pip`.
 
+.. zuul:rolevar:: ensure_global_symlinks
+   :default: False
+
+   Install a symlink to the tox executable into ``/usr/local/bin/tox``.
+   This can be useful when scripts need to be run that expect to find
+   tox in a more standard location and plumbing through the value
+   of ``tox_executable`` would be onerous.
+
+   Setting this requires root access, so should only be done in
+   circumstances where root access is available.
+
 **Output Variables**
 
 .. zuul:rolevar:: tox_executable

roles/ensure-tox/defaults/main.yaml

@@ -1,3 +1,4 @@
 tox_executable: tox
 tox_venv_path: '{{ ansible_user_dir }}/.local/tox'
 tox_prefer_python2: false
+ensure_global_symlinks: false

roles/ensure-tox/tasks/main.yaml

@@ -21,11 +21,11 @@
 - name: Install tox to local env
   when: tox_preinstalled.rc != 0
   block:
+    - name: Create local venv
+      command: '{{ ensure_pip_virtualenv_command }} {{ tox_venv_path }}'
+
     - name: Install tox to local venv
-      pip:
-        name: tox
-        virtualenv_command: '{{ ensure_pip_virtualenv_command }}'
-        virtualenv: '{{ tox_venv_path }}'
+      command: '{{ tox_venv_path }}/bin/pip install tox'
 
     - name: Export installed tox_executable path
       set_fact:
@@ -34,3 +34,13 @@
 
 - name: Output tox version
   command: "{{ tox_executable }} --version"
+
+- name: Make global symlink
+  when:
+    - ensure_global_symlinks
+    - tox_executable != '/usr/local/bin/tox'
+  file:
+    state: link
+    src: "{{ tox_executable }}"
+    dest: /usr/local/bin/tox
+  become: yes

test-playbooks/ensure-tox.yaml

@@ -40,11 +40,10 @@
 - hosts: all
   name: Test ensure-tox when tox_executable is set to an already installed tox
   tasks:
-    - name: Install tox inside a virtualenv
-      pip:
-        name: tox
-        virtualenv: "{{ ansible_user_dir }}/tox-venv"
-        virtualenv_command: "{{ ensure_pip_virtualenv_command }}"
+    - name: Create a virtualenv
+      command: '{{ ensure_pip_virtualenv_command }} {{ ansible_user_dir }}/tox-venv'
+    - name: Install tox to local venv
+      command: '{{ ansible_user_dir }}/tox-venv/bin/pip install tox'
     - name: Run ensure-tox pointing to an already installed tox
       include_role:
         name: ensure-tox