[lit] Improve the ToolSubst class a bit

[zturner]

Summary

In a separate patch, I'm working on re-working clang and lld's lit config's to call a common use_clang and use_lld functions, respectively. Making this work and be generic enough that it also supports debuginfo-test's use case requires a little bit more power in how we specify a tool substitution. For example, lld doesn't prefix its tool substitutions with %, but clang does. And debuginfo-tests shouldn't fail if lld can't be found, but obviously lld should.

This patch adds the necessary bits to make this possible.

It also renames ToolFilter to ToolSubst, and moves it to its own file, to avoid a cyclic dependency between __init__.py and the other files in the same module.

[zturner]

There are some issues with the introducer concept here, so I'm going to rework this a little.

[zturner]

This got a little bit more complicated. There were a lot of latent issues and inconsistencies in the way we added tool substitutions, but I think these are all gone now and everything is consistent.

The main change here is the improvements to the ToolSubst class to customize various parts of the substitution algorithm. The idea being twofold:

1. Take this logic away from the person providing the name of the tool, so that everybody doesn't do it a little bit differently.
2. Provide a way to specify more complex subsitution handling behavior, such as what happens when a tool can't be found, or how to find a tool (Sometimes people would look in the os PATH, sometimes in a specific set of directories, sometimes in the configuration's PATH.

For an example of #1, there was the ability to specify before and after characters that should fail a match, so that for example if a substitution is llc, then you won't match /llc when it is used as part of a path, or llc.exe when it used as a filename. But not all tools followed these guidelines, and it was done (unnecessarily) on a case-by-case basis without people understanding when/why to do it. And it didn't even handle everything, like a \ in front of a path (it always assume / paths). Now, you have to go out of your way to avoid the default behavior, which is almost always correct.

For #2, the motivation for this is that I want to provide a standardized set of substitutions for a tool. So that for example, debuginfo-tests can say use_clang() and lld can say use_clang() and get the same substitutions that lld and clang themselves use. But if lld fails to find its tools, then that's a fatal error, whereas if debuginfo-tests can't find lld tools, that's expected in certain scenarios. So the ability to customize this is needed.

As an aside, this patch exposed a bug in an existing test where clang-cc1 was being used instead of %clang_cc1, so that is fixed here.

[rnk]

This CL contains a lot of whitespace, formatting, and style changes. Can you commit those separately?

clang/test/lit.cfg.py

229–230

These new lines seem unnecessary, the comment is associated with this def.

llvm/test/lit.cfg.py

60–61

ditto

llvm/utils/lit/lit/util.py

1 ↗

(On Diff #117887)

This all looks like style/formatting changes. Can you commit that separately?

[zturner]

Removed formatting changes. Technically, I did the formatting changes first (using pyformat), and then rebased the original patch on top of the formatting changes and ran pyformat again.

[rnk]

lgtm

llvm/test/lit.cfg.py

154

I don't think we need this FIXME, it's explained above where we compute lli_args.

[zturner]

llvm/test/lit.cfg.py

154

It's not explained why some tests rely on the default args and some tests rely on a different set of args. Is that even correct? Reading the comment makes it sound like lli should be used for everything. Most people are probably just going to write lli without thinking about it, because that's how most other tool substitutions work, but it's nto clear from the comment if that's always the right thing to do, and the person writing the test may not even know to check. If anything, the "fix" suggested by the FIXME could be along the lines of "rename %lli to something that more clearly differentiates it from lli.

clang/test/lit.cfg.py

 # -*- Python -*-
 
 import os
 import platform
 import re
 import subprocess
 import tempfile
 
 import lit.formats
 import lit.util
 
 from lit.llvm import llvm_config
-from lit.llvm import ToolFilter
+from lit.llvm.subst import ToolSubst
 
 # Configuration file for the 'lit' test runner.
 
 # name: The name of this test suite.
 config.name = 'Clang'
 
 # testFormat: The test format to use to interpret tests.
 #

 # Tweak the PATH to include the tools dir and the scripts dir.
 llvm_config.with_environment('PATH', [config.llvm_tools_dir, config.clang_tools_dir], append_path=True)
 
 llvm_config.with_environment('LD_LIBRARY_PATH', [config.llvm_shlib_dir, config.llvm_libs_dir], append_path=True)
 
 # Propagate path to symbolizer for ASan/MSan.
 llvm_config.with_system_environment(['ASAN_SYMBOLIZER_PATH', 'MSAN_SYMBOLIZER_PATH'])
 
+llvm_config.use_default_substitutions()
+
 # Discover the 'clang' and 'clangcc' to use.
 
 def inferClang(PATH):
     # Determine which clang to use.
     clang = os.getenv('CLANG')
 
     # If the user set clang in the environment, definitely use that and don't
     # try to validate.

 
 # For each occurrence of a clang tool name, replace it with the full path to
 # the build directory holding that tool.  We explicitly specify the directories
 # to search to ensure that we get the tools just built and not some random
 # tools that might happen to be in the user's PATH.
 tool_dirs = [config.clang_tools_dir, config.llvm_tools_dir]
 
 tool_patterns = [
-    'FileCheck', 'c-index-test',
-    ToolFilter('clang-check', pre='-.', post='-.'),
-    ToolFilter('clang-diff', pre='-.', post='-.'),
-    ToolFilter('clang-format', pre='-.', post='-.'),
+    'c-index-test',
+    ToolSubst('clang-check', pre='-.', post='-.'),
+    ToolSubst('clang-diff', pre='-.', post='-.'),
+    ToolSubst('clang-format', pre='-.', post='-.'),
     # FIXME: Some clang test uses opt?
-    ToolFilter('opt', pre='-.', post=r'/\-.'),
-    # Handle these specially as they are strings searched for during testing.
-    ToolFilter(r'\| \bcount\b', verbatim=True),
-    ToolFilter(r'\| \bnot\b', verbatim=True)]
+    ToolSubst('opt', pre='-.', post=r'/\-.')]
 
 if config.clang_examples:
-    tool_patterns.append(ToolFilter('clang-interpreter', '-.', '-.'))
+    tool_patterns.append(ToolSubst('clang-interpreter', '-.', '-.'))
 
 llvm_config.add_tool_substitutions(tool_patterns, tool_dirs)
 
 # Set available features we allow tests to conditionalize on.
 #
 if config.clang_default_cxx_stdlib != '':
     config.available_features.add('default-cxx-stdlib-set')
 
if platform.system() not in ['Windows']:
     config.available_features.add('utf8-capable-terminal')
 
 # Support for libgcc runtime. Used to rule out tests that require
 # clang to run with -rtlib=libgcc.
 if platform.system() not in ['Darwin', 'Fuchsia']:
     config.available_features.add('libgcc')
 
 # Case-insensitive file system
 def is_filesystem_case_insensitive():
     handle, path = tempfile.mkstemp(prefix='case-test', dir=config.test_exec_root)
     isInsensitive = os.path.exists(
         os.path.join(
             os.path.dirname(path),
             os.path.basename(path).upper()
             ))
     os.close(handle)
     os.remove(path)
     return isInsensitive

lld/test/lit.cfg.py

 # -*- Python -*-
 
 import os
 import platform
 import re
 import subprocess
 import locale
 
 import lit.formats
 import lit.util
 
 from lit.llvm import llvm_config
-from lit.llvm import ToolFilter
+from lit.llvm.subst import ToolSubst
 
 # Configuration file for the 'lit' test runner.
 
 # name: The name of this test suite.
 config.name = 'lld'
 
 # testFormat: The test format to use to interpret tests.
 #

 
 # Tweak the PATH to include the tools dir and the scripts dir.
 llvm_config.with_environment('PATH',
                              [config.llvm_tools_dir, config.lld_tools_dir], append_path=True)
 
 llvm_config.with_environment('LD_LIBRARY_PATH',
                              [config.lld_libs_dir, config.llvm_libs_dir], append_path=True)
 
+llvm_config.use_default_substitutions()
+
 # For each occurrence of a clang tool name, replace it with the full path to
 # the build directory holding that tool.  We explicitly specify the directories
 # to search to ensure that we get the tools just built and not some random
 # tools that might happen to be in the user's PATH.
 tool_dirs = [config.lld_tools_dir, config.llvm_tools_dir]
 
 config.substitutions.append( (r"\bld.lld\b", 'ld.lld --full-shutdown') )
 
 tool_patterns = [
-    'FileCheck', 'not', 'ld.lld', 'lld-link', 'llvm-as', 'llvm-mc', 'llvm-nm',
+    'ld.lld', 'lld-link', 'llvm-as', 'llvm-mc', 'llvm-nm',
     'llvm-objdump', 'llvm-pdbutil', 'llvm-readobj', 'obj2yaml', 'yaml2obj',
-    ToolFilter('lld', pre='-./', post='-.')]
+    ToolSubst('lld', pre='-./', post='-.')]
 
 llvm_config.add_tool_substitutions(tool_patterns, tool_dirs)
 
 # Add site-specific substitutions.
 config.substitutions.append( ('%python', config.python_executable) )
 
 # When running under valgrind, we mangle '-vg' onto the end of the triple so we
 # can check it with XFAIL and XTARGET.

llvm/test/lit.cfg.py

 # -*- Python -*-
 
 # Configuration file for the 'lit' test runner.
 
 import os
 import sys
 import re
 import platform
 import subprocess
 
 import lit.util
 import lit.formats
 from lit.llvm import llvm_config
-from lit.llvm import ToolFilter
+from lit.llvm.subst import ToolSubst
 
 # name: The name of this test suite.
 config.name = 'LLVM'
 
 # testFormat: The test format to use to interpret tests.
 config.test_format = lit.formats.ShTest(not llvm_config.use_lit_shell)
 
 # suffixes: A list of file extensions to treat as test files. This is overriden

 llvm_config.with_system_environment('CAML_LD_LIBRARY_PATH')
 llvm_config.with_environment('CAML_LD_LIBRARY_PATH', llvm_ocaml_lib, append_path=True)
 
 # Set up OCAMLRUNPARAM to enable backtraces in OCaml tests.
 llvm_config.with_environment('OCAMLRUNPARAM', 'b')
 
 # Provide the path to asan runtime lib 'libclang_rt.asan_osx_dynamic.dylib' if
 # available. This is darwin specific since it's currently only needed on darwin.
 def get_asan_rtlib():
     if not "Address" in config.llvm_use_sanitizer or \
        not "Darwin" in config.host_os or \
        not "x86" in config.host_triple:
         return ""
     try:
         import glob
     except:
         print("glob module not found, skipping get_asan_rtlib() lookup")
         return ""

 
 # Avoid matching RUN line fragments that are actually part of
 # path names or options or whatever.
 # The regex is a pre-assertion to avoid matching a preceding
 # dot, hyphen, carat, or slash (.foo, -foo, etc.).  Some patterns
 # also have a post-assertion to not match a trailing hyphen (foo-).
 JUNKCHARS = r".-^/<"
 
-required_tools = [
+llvm_config.use_default_substitutions()
+
+tools = [
     'lli', 'llvm-ar', 'llvm-as', 'llvm-bcanalyzer', 'llvm-config', 'llvm-cov',
     'llvm-cxxdump', 'llvm-cvtres', 'llvm-diff', 'llvm-dis', 'llvm-dsymutil',
     'llvm-dwarfdump', 'llvm-extract', 'llvm-isel-fuzzer', 'llvm-lib',
     'llvm-link', 'llvm-lto', 'llvm-lto2', 'llvm-mc', 'llvm-mcmarkup',
     'llvm-modextract', 'llvm-nm', 'llvm-objcopy', 'llvm-objdump',
     'llvm-pdbutil', 'llvm-profdata', 'llvm-ranlib', 'llvm-readobj',
     'llvm-rtdyld', 'llvm-size', 'llvm-split', 'llvm-strings', 'llvm-tblgen',
     'llvm-c-test', 'llvm-cxxfilt', 'llvm-xray', 'yaml2obj', 'obj2yaml',
-    'FileCheck', 'yaml-bench', 'verify-uselistorder',
-    ToolFilter('bugpoint', post='-'),
-    ToolFilter('llc', pre=JUNKCHARS),
-    ToolFilter('llvm-symbolizer', pre=JUNKCHARS),
-    ToolFilter('opt', JUNKCHARS),
-    ToolFilter('sancov', pre=JUNKCHARS),
-    ToolFilter('sanstats', pre=JUNKCHARS),
-    # Handle these specially as they are strings searched for during testing.
-    ToolFilter(r'\| \bcount\b', verbatim=True),
-    ToolFilter(r'\| \bnot\b', verbatim=True)]
-
-llvm_config.add_tool_substitutions(required_tools, config.llvm_tools_dir)
+    'yaml-bench', 'verify-uselistorder',
+    ToolSubst('bugpoint', post='-', ),
+    ToolSubst('llc', pre=JUNKCHARS),
+    ToolSubst('llvm-symbolizer', pre=JUNKCHARS),
+    ToolSubst('opt', JUNKCHARS),
+    ToolSubst('sancov', pre=JUNKCHARS),
+    ToolSubst('sanstats', pre=JUNKCHARS)]
 
-# For tools that are optional depending on the config, we won't warn
-# if they're missing.
-
-optional_tools = [
+# The following tools are optional
+tools.extend(map(lambda x : ToolSubst(x, unresolved='ignore'), [
     'llvm-go', 'llvm-mt', 'Kaleidoscope-Ch3', 'Kaleidoscope-Ch4',
     'Kaleidoscope-Ch5', 'Kaleidoscope-Ch6', 'Kaleidoscope-Ch7',
-    'Kaleidoscope-Ch8']
-llvm_config.add_tool_substitutions(optional_tools, config.llvm_tools_dir,
-                                   warn_missing=False)
+    'Kaleidoscope-Ch8']))
+
+llvm_config.add_tool_substitutions(tools, config.llvm_tools_dir)
 
 ### Targets
 
 config.targets = frozenset(config.targets_to_build.split())
 
 for arch in config.targets_to_build.split():
     config.available_features.add(arch.lower() + '-registered-target')
 

llvm/utils/lit/lit/llvm/__init__.py

 from lit.llvm import config
-import lit.util
-import re
 
 llvm_config = None
 
-class ToolFilter(object):
-    """
-        String-like class used to build regex substitution patterns for
-        llvm tools.  Handles things like adding word-boundary patterns,
-        and filtering characters from the beginning an end of a tool name
-    """
-
-    def __init__(self, name, pre=None, post=None, verbatim=False):
-        """
-            Construct a ToolFilter.
-
-            name: the literal name of the substitution to look for.
-
-            pre: If specified, the substitution will not find matches where
-            the character immediately preceding the word-boundary that begins
-            `name` is any of the characters in the string `pre`.
-
-            post: If specified, the substitution will not find matches where
-            the character immediately after the word-boundary that ends `name`
-            is any of the characters specified in the string `post`.
-
-            verbatim: If True, `name` is an exact regex that is passed to the
-            underlying substitution
-        """
-        if verbatim:
-            self.regex = name
-            return
-
-        def not_in(chars, where=''):
-            if not chars:
-                return ''
-            pattern_str = '|'.join(re.escape(x) for x in chars)
-            return r'(?{}!({}))'.format(where, pattern_str)
-
-        self.regex = not_in(pre, '<') + r'\b' + name + r'\b' + not_in(post)
-
-    def __str__(self):
-        return self.regex
-
-
 def initialize(lit_config, test_config):
     global llvm_config
 
     llvm_config = config.LLVMConfig(lit_config, test_config)
 

llvm/utils/lit/lit/llvm/config.py

 import os
 import platform
 import re
 import subprocess
 import sys
 
 import lit.util
+from lit.llvm.subst import ToolSubst
 
 def binary_feature(on, feature, off_prefix):
     return feature if on else off_prefix + feature
 
 class LLVMConfig(object):
 
     def __init__(self, lit_config, config):
         self.lit_config = lit_config
def make_msabi_triple(self, triple):
           # If the OS is win32, we're done.
           return triple
         if isa.startswith('x86') or isa == 'amd64' or re.match(r'i\d86', isa):
           # For x86 ISAs, adjust the OS.
           return isa + '-' + vendor + '-win32'
         # -win32 is not supported for non-x86 targets; use a default.
         return 'i686-pc-win32'
 
-    def add_tool_substitutions(self, tools, search_dirs, warn_missing = True):
+    def add_tool_substitutions(self, tools, search_dirs = None):
+        if not search_dirs:
+            search_dirs = [self.config.llvm_tools_dir]
+
         if lit.util.is_string(search_dirs):
             search_dirs = [search_dirs]
 
+        tools = [x if isinstance(x, ToolSubst) else ToolSubst(x) for x in tools]
+
         search_dirs = os.pathsep.join(search_dirs)
+        substitutions = []
         for tool in tools:
             # Extract the tool name from the pattern.  This relies on the tool
             # name being surrounded by \b word match operators.  If the
             # pattern starts with "| ", include it in the string to be
             # substituted.
-            if lit.util.is_string(tool):
-                tool = lit.util.make_word_regex(tool)
-            else:
-                tool = str(tool)
+            tool_str = str(tool)
 
             tool_match = re.match(r"^(\\)?((\| )?)\W+b([0-9A-Za-z-_\.]+)\\b\W*$",
-                                  tool)
+                                  tool_str)
             if not tool_match:
                 continue
 
             tool_pipe = tool_match.group(2)
             tool_name = tool_match.group(4)
             tool_path = lit.util.which(tool_name, search_dirs)
             if not tool_path:
-                if warn_missing:
+                if tool.unresolved == 'warn':
                     # Warn, but still provide a substitution.
                     self.lit_config.note('Did not find ' + tool_name + ' in %s' % search_dirs)
                     tool_path = self.config.llvm_tools_dir + '/' + tool_name
+                elif tool.unresolved == 'fatal':
+                    self.lit_config.fatal('Did not find ' + tool_name + ' in %s' % search_dirs)
+                elif tool.unresolved == 'break':
+                    return False
+                elif tool.unresolved == 'ignore':
+                    continue
+                else:
+                    raise "Unexpected value for ToolSubst.unresolved"
 
             if tool_name == 'llc' and os.environ.get('LLVM_ENABLE_MACHINE_VERIFIER') == '1':
                 tool_path += ' -verify-machineinstrs'
             if tool_name == 'llvm-go':
                 exe = getattr(self.config, 'go_executable', None)
                 if exe:
                     tool_path += " go=" + exe
 
-            self.config.substitutions.append((tool, tool_pipe + tool_path))
+            pattern = tool.introducer + tool_str
+            substitutions.append((pattern, tool_pipe + tool_path))
+
+        self.config.substitutions.extend(substitutions)
+        return True
+
+    def use_default_substitutions(self):
+        tool_patterns = [
+            ToolSubst('FileCheck', unresolved='fatal'),
+            # Handle these specially as they are strings searched for during testing.
+            ToolSubst(r'\| \bcount\b', verbatim=True, unresolved='fatal'),
+            ToolSubst(r'\| \bnot\b', verbatim=True, unresolved='fatal')]
+
+        self.config.substitutions.append( ('%python', sys.executable) )
+        self.add_tool_substitutions(tool_patterns, [self.config.llvm_tools_dir])

llvm/utils/lit/lit/llvm/subst.py

+import re
+
+class ToolSubst(object):
+    """
+        String-like class used to build regex substitution patterns for
+        llvm tools.  Handles things like adding word-boundary patterns,
+        and filtering characters from the beginning an end of a tool name
+    """
+
+    def __init__(self, name, pre=None, post=None, verbatim=False,
+                 unresolved='warn', introducer=''):
+        """
+            Construct a ToolSubst.
+
+            name: the literal name of the substitution to look for.
+
+            pre: If specified, the substitution will not find matches where
+            the character immediately preceding the word-boundary that begins
+            `name` is any of the characters in the string `pre`.
+
+            post: If specified, the substitution will not find matches where
+            the character immediately after the word-boundary that ends `name`
+            is any of the characters specified in the string `post`.
+
+            verbatim: If True, `name` is an exact regex that is passed to the
+            underlying substitution
+
+            unresolved: Action to take if the tool substitution cannot be
+            resolved.  Valid values:
+                'warn' - log a warning but add the substitution anyway.
+                'fatal' - Exit the test suite and log a fatal error.
+                'break' - Don't add any of the substitutions from the current
+                          group, and return a value indicating a failure.
+                'ignore' - Don't add the substitution, and don't log an error
+
+            introducer: If specified, prepends to the beginning of the tool name
+            pattern.  For example, specifying an introducer of '%' with a tool
+            name of 'clang' would cause %clang to be substituted for the specified
+            path.
+
+        """
+        self.unresolved = unresolved
+        self.introducer = introducer
+        if verbatim:
+            self.regex = name
+            return
+
+        def not_in(chars, where=''):
+            if not chars:
+                return ''
+            pattern_str = '|'.join(re.escape(x) for x in chars)
+            return r'(?{}!({}))'.format(where, pattern_str)
+
+        self.regex = not_in(pre, '<') + r'\b' + name + r'\b' + not_in(post)
+
+    def __str__(self):
+        return self.regex