[lldb][test] 1 - Don't do test-replication for gmodules debug_info variant

[Michael137]

Summary

Currently, by default LLDB runs an API test with 3 variants,
one of which, depending on platform, is gmodules. However,
most tests don't actually make use of any specific gmodules
feature since they compile a single main.cpp file without
imporint types from other modules.

Instead of running all tests an extra time with -gmodules
enabled, we plan to test gmodules features with dedicated
API tests that explicitly opt-into compiling with -gmodules.
One of the main benefits of this will be a reduction in total
API test-suite run-time (by around 1/3).

This patch adds a flag to debug_info_categories that indicates
whether a category is eligible to be replicated by lldbtest.

Keeping gmodules a debug-info category is desirable because
builder.py knows how to inject the appropriate Makefile flags
into the build command for debug-info categories already. Whereas
for non-debug-info categories we'd have to teach it how to. The
category is inferred from the test-name debug-info suffix currently.

[Michael137]

• Fixup prototype

[Michael137]

• Reword commit
• Add docs

[Michael137]

• Fixup

lldb/docs/resources/test.rst

::
   include Makefile.rules
 
 Finding the right variables to set can be tricky. You can always take a look at
 `Makefile.rules <https://github.com/llvm/llvm-project/blob/main/lldb/packages/Python/lldbsuite/test/make/Makefile.rules>`_
 but often it's easier to find an existing ``Makefile`` that does something
 similar to what you want to do.
 
 Another thing this enables is having different variants for the same test
-case. By default, we run every test for all 3 debug info formats, so once with
-DWARF from the object files, once with gmodules and finally with a dSYM on
-macOS or split DWARF (DWO) on Linux. But there are many more things we can test
+case. By default, we run every test for two debug info formats, once with
+DWARF from the object files and another with a dSYM on macOS or split
+DWARF (DWO) on Linux. But there are many more things we can test
 that are orthogonal to the test itself. On GreenDragon we have a matrix bot
 that runs the test suite under different configurations, with older host
 compilers and different DWARF versions.
 
 As you can imagine, this quickly lead to combinatorial explosion in the number
 of variants. It's very tempting to add more variants because it's an easy way
 to increase test coverage. It doesn't scale. It's easy to set up, but increases
 the runtime of the tests and has a large ongoing cost.

lldb/packages/Python/lldbsuite/test/lldbtest.py

def __new__(cls, name, bases, attrs):
         newattrs = {}
         for attrname, attrvalue in attrs.items():
             if attrname.startswith("test") and not getattr(
                     attrvalue, "__no_debug_info_test__", False):
 
                 # If any debug info categories were explicitly tagged, assume that list to be
                 # authoritative.  If none were specified, try with all debug
                 # info formats.
-                all_dbginfo_categories = set(test_categories.debug_info_categories)
+                all_dbginfo_categories = set(test_categories.debug_info_categories.keys())
                 categories = set(
                     getattr(
                         attrvalue,
                         "categories",
                         [])) & all_dbginfo_categories
                 if not categories:
-                    categories = all_dbginfo_categories
+                    categories = [category for category, can_replicate \
+                                  in test_categories.debug_info_categories.items() \
+                                  if can_replicate]
 
                 for cat in categories:
                     @decorators.add_test_categories([cat])
                     @wraps(attrvalue)
                     def test_method(self, attrvalue=attrvalue):
                         return attrvalue(self)
 
                     method_name = attrname + "_" + cat

lldb/packages/Python/lldbsuite/test/test_categories.py

 """
 Provides definitions for various lldb test categories
 """
 
 from __future__ import absolute_import
 from __future__ import print_function
 
 # System modules
 import sys
 
 # Third-party modules
 
 # LLDB modules
 from lldbsuite.support import gmodules
 
-
-debug_info_categories = [
-    'dwarf', 'dwo', 'dsym', 'gmodules'
-]
+# Key: Category name
+# Value: should be used in lldbtest's debug-info replication
+debug_info_categories = {
+    'dwarf'    : True,
+    'dwo'      : True,
+    'dsym'     : True,
+    'gmodules' : False
+}
 
 all_categories = {
     'basic_process': 'Basic process execution sniff tests.',
     'cmdline': 'Tests related to the LLDB command-line interface',
     'dataformatters': 'Tests related to the type command and the data formatters subsystem',
     'debugserver': 'Debugserver tests',
     'dsym': 'Tests that can be run with DSYM debug information',
     'dwarf': 'Tests that can be run with DWARF debug information',