Enh/create wrapper

When an "official" FSL distribution is installed via the fslinstaller script, wrapper scripts for all FSL executables are created in $FSLDIR/share/fsl/bin/, so that all FSL executables can be added to the user $PATH without all executables in $FSLDIR/bin/ being added.

The new wrapper creation/removal scripts are located in the share/fsl/sbin/ directory - the intent is that the pre-unlink.sh and post-link.sh scripts of a FSL conda recipe will call these scripts during installation/removal of a FSL conda package.

Note that thhis MR includes a few rudimentary tests, and CI infrastructure for automatically running those tests (and integration with the fsl/fsl-ci-rules logic for automated conda builds).

Background

I think this is currently the best option out of the ones that have been discussed (in the related [non-existent, but perhaps should be for future code changes] gitlab issue). To make things clear, we need a solution which supports:

• "Official" installation of a full FSL distribution (via the future fslinstaller)
• Direct installation of a sub-set of FSL into a user-managed conda environment, via conda install

The problems we are trying to solve are solely related to official FSL installations:

• Not clobbering the user $PATH with non-FSL commands that are installed into the same $FSLDIR/bin/, such as python, pip, conda, tcl, etc
• Running FSL python commands in isolated mode, so that other Python libraries available in the user's environment do not clobber the Python libraries installed into $FSLDIR

Generating a "wrapper script" for every FSL command, and installing those wrapper scripts into an isolated directory allows these problems to be overcome:

• The user can add $FSLDIR/fsl/share/bin/ to their $PATH instead of $FSLDIR/bin/
• Wrapper scripts for Python commands can explicitly pass -I to the python interpreter so that it runs in isolated mode

Other proposals which were discussed and rejected:

• Install everything directly into $FSLDIR/fsl/share/bin/
  • Would require all FSL scripts which refer to $FSLDIR/bin/, which would be a fair amount of work, but is possible, and hence not a show stopper
  • Would break third-party/user scripts which refer to $FSLDIR/bin/
  • would potentially have library linking issues, so would possibly need the Make system to be adjusted to be able to install into either $FSLDIR/bin/ or to $FSLDIR/fsl/share/bin/, which could get messy
  • Not "officially" possible for python projects (from what I could tell), so we would need to manually mv/cp python entry points from $FSLDIR/bin/ anyway, which feels just as hacky as a wrapper script
• Sym-link rather than use wrapper scripts
  • Does not solve the python isolation problem, nor the problem of long hashbangs (although the latter could be considered a problem for the user)

.ci/test_create_remove_wrapper.py

+#!/usr/bin/env python
+#
+# test_create_remove_wrapper.py - Test the createFSLWrapper.sh and
+# removeFSLWrapper.sh scripts. Requires Python 3.7.
+#
+# Author: Paul McCarthy <pauldmccarthy@gmail.com>
+#
+
+
+import os.path as op
+import subprocess as sp
+import textwrap as tw
+import os
+import shlex
+import shutil
+import tempfile
+import contextlib
+from unittest import mock
+
+
+BASE_DIR       = op.abspath(op.join(op.dirname(__file__), '..'))
+CREATE_WRAPPER = op.join(BASE_DIR, 'share', 'fsl', 'sbin', 'createFSLWrapper')
+REMOVE_WRAPPER = op.join(BASE_DIR, 'share', 'fsl', 'sbin', 'removeFSLWrapper')
+
+
+def run(cmd, **kwargs):
+    return sp.run(shlex.split(cmd), check=True, **kwargs)
+
+
+@contextlib.contextmanager
+def temp_fsldir():
+
+    testdir    = tempfile.mkdtemp()
+    prevdir    = os.getcwd()
+    fsldir     = op.join(testdir, 'fsl')
+    wrapperdir = op.join(testdir, 'fsl', 'share', 'fsl', 'bin')
+    try:
+
+        os.chdir(testdir)
+        os.mkdir(fsldir)
+
+        with mock.patch.dict(os.environ, {
+                'FSLDIR'                     : fsldir,
+                'PREFIX'                     : fsldir,
+                'FSL_CREATE_WRAPPER_SCRIPTS' : '1'}):
+            yield fsldir, wrapperdir
+
+    finally:
+        os.chdir(prevdir)
+        shutil.rmtree(testdir)
+
+
+def touch(path):
+    dirname = op.dirname(path)
+    if not op.exists(dirname):
+        os.makedirs(dirname)
+    with open(path, 'wt') as f:
+        f.write('.')
+
+
+def test_env_vars_not_set():
+    """Test that wrapper scripts are not created if the
+    FSL_CREATE_WRAPPER_SCRIPTS, FSLDIR, or PREFIX environment variables
+    are not set.
+    """
+    with temp_fsldir() as (fsldir, wrapperdir):
+        touch(op.join(fsldir, 'bin', 'test_script'))
+
+        env = os.environ.copy()
+        env.pop('FSL_CREATE_WRAPPER_SCRIPTS')
+        run(f'{CREATE_WRAPPER} test_script', env=env)
+        assert not op.exists(op.join(wrapperdir, 'test_script1'))
+
+        env = os.environ.copy()
+        env.pop('FSLDIR')
+        run(f'{CREATE_WRAPPER} test_script', env=env)
+        assert not op.exists(op.join(wrapperdir, 'test_script1'))
+
+        env = os.environ.copy()
+        env.pop('PREFIX')
+        run(f'{CREATE_WRAPPER} test_script', env=env)
+        assert not op.exists(op.join(wrapperdir, 'test_script1'))
+
+        # FSLDIR invalid
+        env = os.environ.copy()
+        env['FSLDIR'] = '/some/non-existent/path'
+        run(f'{CREATE_WRAPPER} test_script', env=env)
+        assert not op.exists(op.join(wrapperdir, 'test_script1'))
+
+        # FSLDIR != PREFIX
+        env = os.environ.copy()
+        env['FSLDIR'] = op.join(env['PREFIX'], 'other_fsl')
+        run(f'{CREATE_WRAPPER} test_script', env=env)
+        assert not op.exists(op.join(wrapperdir, 'test_script1'))
+
+
+def test_create_python_wrapper():
+    """Test creation of a wrapper script for a python executable"""
+    with temp_fsldir() as (fsldir, wrapperdir):
+
+        script_path  = op.join(fsldir, 'bin', 'test_script')
+        wrapper_path = op.join(wrapperdir,    'test_script')
+
+        touch(script_path)
+        with open(script_path, 'wt') as f:
+            f.write('#!/usr/bin/env python\n')
+            f.write('print("hello")\n')
+
+        expect = tw.dedent(f"""
+        #!/usr/bin/env bash
+        {fsldir}/bin/python -I {script_path} "$@"
+        """).strip()
+
+        run(f'{CREATE_WRAPPER} test_script')
+
+        assert op.exists(wrapper_path)
+        with open(wrapper_path, 'rt') as f:
+            got = f.read().strip()
+
+        assert got == expect
+
+
+def test_create_other_wrapper():
+    """Test creation of a wrapper script for a non-python executable."""
+    with temp_fsldir() as (fsldir, wrapperdir):
+        script_path  = op.join(fsldir, 'bin', 'test_script')
+        wrapper_path = op.join(wrapperdir,    'test_script')
+
+        touch(script_path)
+        with open(op.join(fsldir, 'bin', 'test_script'), 'wt') as f:
+            f.write('#!/usr/bin/env bash\n')
+            f.write('echo "hello"\n')
+
+        expect = tw.dedent(f"""
+        #!/usr/bin/env bash
+        {script_path} "$@"
+        """).strip()
+
+        run(f'{CREATE_WRAPPER} test_script')
+
+        assert op.exists(wrapper_path)
+        with open(wrapper_path, 'rt') as f:
+            got = f.read().strip()
+
+        assert got == expect
+
+
+def test_permissions_preserved():
+    """Test that wrapper script has same permissions as wrapped script."""
+    with temp_fsldir() as (fsldir, wrapperdir):
+        perms        = [0o777, 0o755, 0o644, 0o600, 0o755, 0o700]
+        script_path  = op.join(fsldir, 'bin', 'test_script')
+        wrapper_path = op.join(wrapperdir,    'test_script')
+        touch(script_path)
+
+        for perm in perms:
+            os.chmod(script_path, perm)
+            run(f'{CREATE_WRAPPER} test_script')
+
+            stat = os.stat(wrapper_path)
+            assert (stat.st_mode & 0o777) == perm
+
+
+def test_create_remove_wrappers():
+    """Tests normal usage. """
+    with temp_fsldir() as (fsldir, wrapperdir):
+        touch(op.join(fsldir, 'bin', 'test_script1'))
+        touch(op.join(fsldir, 'bin', 'test_script2'))
+
+        run(f'{CREATE_WRAPPER} test_script1 test_script2')
+
+        assert op.exists(op.join(wrapperdir, 'test_script1'))
+        assert op.exists(op.join(wrapperdir, 'test_script2'))
+
+        run(f'{REMOVE_WRAPPER} test_script1 test_script2')
+
+        assert not op.exists(op.join(wrapperdir, 'test_script1'))
+        assert not op.exists(op.join(wrapperdir, 'test_script2'))