Merge branch 'master' into bugfix/documentation_check_info

Author: vkarak

docs/running.rst

@@ -629,3 +629,78 @@ Here is an example output of ReFrame using asynchronous execution policy:
 
 The asynchronous execution policy may provide significant overall performance benefits for run-only regression tests.
 For compile-only and normal tests that require a compilation, the execution time will be bound by the total compilation time of the test.
+
+
+Manipulating modules
+--------------------
+
+.. versionadded:: 2.11
+
+ReFrame allows you to change the modules loaded by a regression test on-the-fly without having to edit the regression test file.
+This feature is extremely useful when you need to quickly test a newer version of a module, but it also allows you to completely decouple the module names used in your regression tests from the real module names in a system, thus making your test even more portable.
+This is achieved by defining *module mappings*.
+
+There are two ways to pass module mappings to ReFrame.
+The first is to use the ``--map-module`` command-line option, which accepts a module mapping.
+For example, the following line maps the module ``test_module`` to the module ``real_module``:
+
+.. code-block:: none
+
+  --map-module='test_module: real_module'
+
+In this case, whenever ReFrame is asked to load ``test_module``, it will load ``real_module``.
+Any string without spaces may be accepted in place of ``test_module`` and ``real_module``.
+You can also define multiple module mappings at once by repeating the ``--map-module``.
+If more than one mapping is specified for the same module, then the last mapping will take precedence.
+It is also possible to map a single module to more than one target.
+This can be done by listing the target modules separated by spaces in the order that they should be loaded.
+In the following example, ReFrame will load ``real_module0`` and ``real_module1`` whenever the ``test_module`` is encountered:
+
+.. code-block:: none
+
+  --map-module 'test_module: real_module0 real_module1'
+
+The second way of defining mappings is by listing them on a file, which you can then pass to ReFrame through the command-line option ``--module-mappings``.
+Each line on the file corresponds to the definition of a mapping for a single module.
+The syntax of the individual mappings in the file is the same as with the option ``--map-module`` and the same rules apply regarding repeated definitions.
+Text starting with ``#`` is considered a comment and is ignored until the end of line is encountered.
+Empty lines are ignored.
+The following block shows an example of module mapping file:
+
+.. code-block:: none
+
+  module-1: module-1a  # an inline comment
+  module-2: module-2a module-2b module-2c
+
+  # This is a full line comment
+  module-4: module-4a module-4b
+
+If both ``--map-module`` and ``--module-mappings`` are passed, ReFrame will first create a mapping from the definitions on the file and it will then process the definitions passed with the ``--map-module`` options.
+As usual, later definitions will override the former.
+
+A final note on module mappings.
+Module mappings can be arbitrarily deep as long as they do not form a cycle.
+In this case, ReFrame will issue an error (denoting the offending cyclic dependency).
+For example, suppose having the following mapping file:
+
+.. code-block:: none
+
+   cudatoolkit: foo
+   foo: bar
+   bar: foobar
+   foobar: cudatoolkit
+
+If you now try to run a test that loads the module `cudatoolkit`, the following error will be yielded:
+
+.. code-block:: none
+
+   ------------------------------------------------------------------------------
+   FAILURE INFO for example7_check
+     * System partition: daint:gpu
+     * Environment: PrgEnv-gnu
+     * Stage directory: None
+     * Job type: batch job (id=-1)
+     * Maintainers: ['you-can-type-your-email-here']
+     * Failing phase: setup
+     * Reason: caught framework exception: module cyclic dependency: cudatoolkit->foo->bar->foobar->cudatoolkit
+   ------------------------------------------------------------------------------

reframe/core/modules.py

@@ -5,6 +5,7 @@
 import abc
 import os
 import re
+from collections import OrderedDict
 
 import reframe.core.fields as fields
 import reframe.utility.os as os_ext
@@ -203,6 +204,35 @@ def is_module_loaded(self, name):
     def _is_module_loaded(self, name):
         return self._backend.is_module_loaded(Module(name))
 
+    def load_mapping(self, mapping):
+        """Updates the internal module mapping with a single mapping"""
+        key, *rest = mapping.split(':')
+        if len(rest) != 1:
+            raise ConfigError('invalid mapping syntax: %s' % mapping)
+
+        key = key.strip()
+        values = rest[0].split()
+        if not key:
+            raise ConfigError('no key found in mapping: %s' % mapping)
+
+        if not values:
+            raise ConfigError('no mapping defined for module: %s' % key)
+
+        self.module_map[key] = list(OrderedDict.fromkeys(values))
+
+    def load_mapping_from_file(self, filename):
+        """Update the internal module mapping from mappings in a file."""
+        with open(filename) as fp:
+            for lineno, line in enumerate(fp, start=1):
+                line = line.strip().split('#')[0]
+                if not line:
+                    continue
+
+                try:
+                    self.load_mapping(line)
+                except ConfigError as e:
+                    raise ConfigError('%s:%s' % (filename, lineno)) from e
+
     @property
     def name(self):
         """Return the name of this module system."""

reframe/frontend/cli.py

@@ -7,8 +7,7 @@
 import reframe.utility.os as os_ext
 from reframe.core.exceptions import (EnvironError, ReframeError,
                                      ReframeFatalError, format_exception)
-from reframe.core.modules import get_modules_system
-from reframe.core.modules import init_modules_system
+from reframe.core.modules import get_modules_system, init_modules_system
 from reframe.frontend.argparse import ArgumentParser
 from reframe.frontend.executors import Runner
 from reframe.frontend.executors.policies import (SerialExecutionPolicy,
@@ -123,7 +122,7 @@ def main():
         help='Run checks on the selected list of nodes')
     run_options.add_argument(
         '--exclude-nodes', action='store', metavar='NODELIST',
-        help='Exclude the list of nodes from runnning checks')
+        help='Exclude the list of nodes from running checks')
     run_options.add_argument(
         '--job-option', action='append', metavar='OPT',
         dest='job_options', default=[],
@@ -159,6 +158,14 @@ def main():
         '-m', '--module', action='append', default=[],
         metavar='MOD', dest='user_modules',
         help='Load module MOD before running the regression')
+    misc_options.add_argument(
+        '-M', '--map-module', action='append', metavar='MAPPING',
+        dest='module_mappings', default=[],
+        help='Apply a single module mapping')
+    misc_options.add_argument(
+        '--module-mappings', action='store', metavar='FILE',
+        dest='module_map_file',
+        help='Apply module mappings defined in FILE')
     misc_options.add_argument(
         '--nocolor', action='store_false', dest='colorize', default=True,
         help='Disable coloring of output')
@@ -229,6 +236,19 @@ def main():
     # Init modules system
     init_modules_system(system.modules_system)
 
+    try:
+        if options.module_map_file:
+            get_modules_system().load_mapping_from_file(
+                options.module_map_file)
+
+        if options.module_mappings:
+            for m in options.module_mappings:
+                get_modules_system().load_mapping(m)
+
+    except (ReframeError, OSError) as e:
+        printer.error('could not load module mappings: %s' % e)
+        sys.exit(1)
+
     if options.mode:
         try:
             mode_args = site_config.modes[options.mode]

unittests/test_modules.py

@@ -1,5 +1,6 @@
 import os
 import unittest
+from tempfile import NamedTemporaryFile
 
 import reframe.core.modules as modules
 from reframe.core.environments import EnvironmentSnapshot
@@ -199,6 +200,11 @@ class TestModuleMapping(unittest.TestCase):
     def setUp(self):
         self.modules_activity = ModulesSystemEmulator()
         self.modules_system = modules.ModulesSystem(self.modules_activity)
+        self.mapping_file = NamedTemporaryFile('wt', delete=False)
+
+    def tearDown(self):
+        self.mapping_file.close()
+        os.remove(self.mapping_file.name)
 
     def test_mapping_simple(self):
         #
@@ -401,3 +407,57 @@ def test_mapping_deep_cycle(self):
         }
         self.assertRaisesRegex(EnvironError, 'm0->m1->m3->m4->m2->m1',
                                self.modules_system.load_module, 'm0')
+
+    def test_mapping_from_file_simple(self):
+        with self.mapping_file:
+            self.mapping_file.write('m1:m2  m3   m3\n'
+                                    'm2 : m4 \n'
+                                    ' #m5: m6\n'
+                                    '\n'
+                                    ' m2: m7 m8\n'
+                                    'm9: m10 # Inline comment')
+
+        reference_map = {
+            'm1': ['m2', 'm3'],
+            'm2': ['m7', 'm8'],
+            'm9': ['m10']
+        }
+        self.modules_system.load_mapping_from_file(self.mapping_file.name)
+        self.assertEqual(reference_map, self.modules_system.module_map)
+
+    def test_maping_from_file_missing_key_separator(self):
+        with self.mapping_file:
+            self.mapping_file.write('m1 m2')
+
+        self.assertRaises(ConfigError,
+                          self.modules_system.load_mapping_from_file,
+                          self.mapping_file.name)
+
+    def test_maping_from_file_empty_value(self):
+        with self.mapping_file:
+            self.mapping_file.write('m1: # m2')
+
+        self.assertRaises(ConfigError,
+                          self.modules_system.load_mapping_from_file,
+                          self.mapping_file.name)
+
+    def test_maping_from_file_multiple_key_separators(self):
+        with self.mapping_file:
+            self.mapping_file.write('m1 : m2 : m3')
+
+        self.assertRaises(ConfigError,
+                          self.modules_system.load_mapping_from_file,
+                          self.mapping_file.name)
+
+    def test_maping_from_file_empty_key(self):
+        with self.mapping_file:
+            self.mapping_file.write(' :  m2')
+
+        self.assertRaises(ConfigError,
+                          self.modules_system.load_mapping_from_file,
+                          self.mapping_file.name)
+
+    def test_maping_from_file_missing_file(self):
+        self.assertRaises(OSError,
+                          self.modules_system.load_mapping_from_file,
+                          'foo')