gh-109972: Enhance test_gdb (#110026)

* Split test_pycfunction.py: add test_cfunction_full.py.
  Split the function into the following 6 functions. In verbose
  mode, these "pycfunction" tests now log each tested call.

  * test_pycfunction_noargs()
  * test_pycfunction_o()
  * test_pycfunction_varargs()
  * test_pycfunction_varargs_keywords()
  * test_pycfunction_fastcall()
  * test_pycfunction_fastcall_keywords()

* Move get_gdb_repr() to PrettyPrintTests.
* Replace DebuggerTests.get_sample_script() with SAMPLE_SCRIPT.
* Rename checkout_hook_path to CHECKOUT_HOOK_PATH.
* Rename gdb_version to GDB_VERSION_TEXT.
* Replace (gdb_major_version, gdb_minor_version) with GDB_VERSION.
* run_gdb() uses "backslashreplace" error handler instead of "replace".
* Add check_gdb() function to util.py.
* Enhance support.check_cflags_pgo(): check also for sysconfig
  PGO_PROF_USE_FLAG (if available) in compiler flags.
* Move some SkipTest checks to test_gdb/__init__.py.
* Elaborate why gdb cannot be tested on Windows: gdb doesn't support
  PDB debug symbol files.

1 files changed, 119 insertions, 137 deletions

diff --git a/Lib/test/test_gdb/util.py b/Lib/test/test_gdb/util.py
index 30beb4e..7f4e3cb 100644
--- a/Lib/test/test_gdb/util.py
+++ b/Lib/test/test_gdb/util.py
@@ -1,5 +1,6 @@
 import os
 import re
+import shlex
 import subprocess
 import sys
 import sysconfig
@@ -7,29 +8,74 @@ import unittest
 from test import support
 
 
-MS_WINDOWS = (sys.platform == 'win32')
-if MS_WINDOWS:
-    raise unittest.SkipTest("test_gdb doesn't work on Windows")
+# Location of custom hooks file in a repository checkout.
+CHECKOUT_HOOK_PATH = os.path.join(os.path.dirname(sys.executable),
+                                  'python-gdb.py')
+
+SAMPLE_SCRIPT = os.path.join(os.path.dirname(__file__), 'gdb_sample.py')
+BREAKPOINT_FN = 'builtin_id'
+
+PYTHONHASHSEED = '123'
+
+
+def clean_environment():
+    # Remove PYTHON* environment variables such as PYTHONHOME
+    return {name: value for name, value in os.environ.items()
+            if not name.startswith('PYTHON')}
+
+
+# Temporary value until it's initialized by get_gdb_version() below
+GDB_VERSION = (0, 0)
+
+def run_gdb(*args, exitcode=0, **env_vars):
+    """Runs gdb in --batch mode with the additional arguments given by *args.
+
+    Returns its (stdout, stderr) decoded from utf-8 using the replace handler.
+    """
+    env = clean_environment()
+    if env_vars:
+        env.update(env_vars)
+
+    cmd = ['gdb',
+           # Batch mode: Exit after processing all the command files
+           # specified with -x/--command
+           '--batch',
+            # -nx: Do not execute commands from any .gdbinit initialization
+            # files (gh-66384)
+           '-nx']
+    if GDB_VERSION >= (7, 4):
+        cmd.extend(('--init-eval-command',
+                    f'add-auto-load-safe-path {CHECKOUT_HOOK_PATH}'))
+    cmd.extend(args)
+
+    proc = subprocess.run(
+        cmd,
+        # Redirect stdin to prevent gdb from messing with the terminal settings
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        encoding="utf8", errors="backslashreplace",
+        env=env)
+
+    stdout = proc.stdout
+    stderr = proc.stderr
+    if proc.returncode != exitcode:
+        cmd_text = shlex.join(cmd)
+        raise Exception(f"{cmd_text} failed with exit code {proc.returncode}, "
+                        f"expected exit code {exitcode}:\n"
+                        f"stdout={stdout!r}\n"
+                        f"stderr={stderr!r}")
+
+    return (stdout, stderr)
 
 
 def get_gdb_version():
     try:
-        cmd = ["gdb", "-nx", "--version"]
-        proc = subprocess.Popen(cmd,
-                                stdout=subprocess.PIPE,
-                                stderr=subprocess.PIPE,
-                                universal_newlines=True)
-        with proc:
-            version, stderr = proc.communicate()
-
-        if proc.returncode:
-            raise Exception(f"Command {' '.join(cmd)!r} failed "
-                            f"with exit code {proc.returncode}: "
-                            f"stdout={version!r} stderr={stderr!r}")
+        stdout, stderr = run_gdb('--version')
     except OSError:
         # This is what "no gdb" looks like.  There may, however, be other
         # errors that manifest this way too.
-        raise unittest.SkipTest("Couldn't find gdb on the path")
+        raise unittest.SkipTest("Couldn't find gdb program on the path")
 
     # Regex to parse:
     # 'GNU gdb (GDB; SUSE Linux Enterprise 12) 7.7\n' -> 7.7
@@ -37,32 +83,48 @@ def get_gdb_version():
     # 'GNU gdb 6.1.1 [FreeBSD]\n' -> 6.1
     # 'GNU gdb (GDB) Fedora (7.5.1-37.fc18)\n' -> 7.5
     # 'HP gdb 6.7 for HP Itanium (32 or 64 bit) and target HP-UX 11iv2 and 11iv3.\n' -> 6.7
-    match = re.search(r"^(?:GNU|HP) gdb.*?\b(\d+)\.(\d+)", version)
+    match = re.search(r"^(?:GNU|HP) gdb.*?\b(\d+)\.(\d+)", stdout)
     if match is None:
-        raise Exception("unable to parse GDB version: %r" % version)
-    return (version, int(match.group(1)), int(match.group(2)))
+        raise Exception("unable to parse gdb version: %r" % stdout)
+    version_text = stdout
+    major = int(match.group(1))
+    minor = int(match.group(2))
+    version = (major, minor)
+    return (version_text, version)
 
-gdb_version, gdb_major_version, gdb_minor_version = get_gdb_version()
-if gdb_major_version < 7:
-    raise unittest.SkipTest("gdb versions before 7.0 didn't support python "
-                            "embedding. Saw %s.%s:\n%s"
-                            % (gdb_major_version, gdb_minor_version,
-                               gdb_version))
+GDB_VERSION_TEXT, GDB_VERSION = get_gdb_version()
+if GDB_VERSION < (7, 0):
+    raise unittest.SkipTest(
+        f"gdb versions before 7.0 didn't support python embedding. "
+        f"Saw gdb version {GDB_VERSION[0]}.{GDB_VERSION[1]}:\n"
+        f"{GDB_VERSION_TEXT}")
 
-if not sysconfig.is_python_build():
-    raise unittest.SkipTest("test_gdb only works on source builds at the moment.")
 
-if ((sysconfig.get_config_var('PGO_PROF_USE_FLAG') or 'xxx') in
-    (sysconfig.get_config_var('PY_CORE_CFLAGS') or '')):
-    raise unittest.SkipTest("test_gdb is not reliable on PGO builds")
+def check_usable_gdb():
+    # Verify that "gdb" was built with the embedded Python support enabled and
+    # verify that "gdb" can load our custom hooks, as OS security settings may
+    # disallow this without a customized .gdbinit.
+    stdout, stderr = run_gdb(
+        '--eval-command=python import sys; print(sys.version_info)',
+        '--args', sys.executable)
 
-# Location of custom hooks file in a repository checkout.
-checkout_hook_path = os.path.join(os.path.dirname(sys.executable),
-                                  'python-gdb.py')
+    if "auto-loading has been declined" in stderr:
+        raise unittest.SkipTest(
+            f"gdb security settings prevent use of custom hooks; "
+            f"stderr: {stderr!r}")
 
-PYTHONHASHSEED = '123'
+    if not stdout:
+        raise unittest.SkipTest(
+            f"gdb not built with embedded python support; "
+            f"stderr: {stderr!r}")
+
+    if "major=2" in stdout:
+        raise unittest.SkipTest("gdb built with Python 2")
 
+check_usable_gdb()
 
+
+# Control-flow enforcement technology
 def cet_protection():
     cflags = sysconfig.get_config_var('CFLAGS')
     if not cflags:
@@ -74,63 +136,17 @@ def cet_protection():
             and any((flag.startswith('-fcf-protection')
                      and not flag.endswith(("=none", "=return")))
                     for flag in flags))
-
-# Control-flow enforcement technology
 CET_PROTECTION = cet_protection()
 
 
-def run_gdb(*args, **env_vars):
-    """Runs gdb in --batch mode with the additional arguments given by *args.
-
-    Returns its (stdout, stderr) decoded from utf-8 using the replace handler.
-    """
-    if env_vars:
-        env = os.environ.copy()
-        env.update(env_vars)
-    else:
-        env = None
-    # -nx: Do not execute commands from any .gdbinit initialization files
-    #      (issue #22188)
-    base_cmd = ('gdb', '--batch', '-nx')
-    if (gdb_major_version, gdb_minor_version) >= (7, 4):
-        base_cmd += ('-iex', 'add-auto-load-safe-path ' + checkout_hook_path)
-    proc = subprocess.Popen(base_cmd + args,
-                            # Redirect stdin to prevent GDB from messing with
-                            # the terminal settings
-                            stdin=subprocess.PIPE,
-                            stdout=subprocess.PIPE,
-                            stderr=subprocess.PIPE,
-                            env=env)
-    with proc:
-        out, err = proc.communicate()
-    return out.decode('utf-8', 'replace'), err.decode('utf-8', 'replace')
-
-# Verify that "gdb" was built with the embedded python support enabled:
-gdbpy_version, _ = run_gdb("--eval-command=python import sys; print(sys.version_info)")
-if not gdbpy_version:
-    raise unittest.SkipTest("gdb not built with embedded python support")
-
-if "major=2" in gdbpy_version:
-    raise unittest.SkipTest("gdb built with Python 2")
-
-# Verify that "gdb" can load our custom hooks, as OS security settings may
-# disallow this without a customized .gdbinit.
-_, gdbpy_errors = run_gdb('--args', sys.executable)
-if "auto-loading has been declined" in gdbpy_errors:
-    msg = "gdb security settings prevent use of custom hooks: "
-    raise unittest.SkipTest(msg + gdbpy_errors.rstrip())
-
-BREAKPOINT_FN='builtin_id'
-
-
 def setup_module():
     if support.verbose:
-        print("GDB version %s.%s:" % (gdb_major_version, gdb_minor_version))
-        for line in gdb_version.splitlines():
+        print(f"gdb version {GDB_VERSION[0]}.{GDB_VERSION[1]}:")
+        for line in GDB_VERSION_TEXT.splitlines():
             print(" " * 4 + line)
+        print()
 
 
-@unittest.skipIf(support.PGO, "not useful for PGO")
 class DebuggerTests(unittest.TestCase):
 
     """Test that the debugger can debug Python."""
@@ -163,20 +179,22 @@ class DebuggerTests(unittest.TestCase):
         # structures
 
         # Generate a list of commands in gdb's language:
-        commands = ['set breakpoint pending yes',
-                    'break %s' % breakpoint,
-
-                    # The tests assume that the first frame of printed
-                    #  backtrace will not contain program counter,
-                    #  that is however not guaranteed by gdb
-                    #  therefore we need to use 'set print address off' to
-                    #  make sure the counter is not there. For example:
-                    # #0 in PyObject_Print ...
-                    #  is assumed, but sometimes this can be e.g.
-                    # #0 0x00003fffb7dd1798 in PyObject_Print ...
-                    'set print address off',
-
-                    'run']
+        commands = [
+            'set breakpoint pending yes',
+            'break %s' % breakpoint,
+
+            # The tests assume that the first frame of printed
+            #  backtrace will not contain program counter,
+            #  that is however not guaranteed by gdb
+            #  therefore we need to use 'set print address off' to
+            #  make sure the counter is not there. For example:
+            # #0 in PyObject_Print ...
+            #  is assumed, but sometimes this can be e.g.
+            # #0 0x00003fffb7dd1798 in PyObject_Print ...
+            'set print address off',
+
+            'run',
+        ]
 
         # GDB as of 7.4 onwards can distinguish between the
         # value of a variable at entry vs current value:
@@ -184,7 +202,7 @@ class DebuggerTests(unittest.TestCase):
         # which leads to the selftests failing with errors like this:
         #   AssertionError: 'v@entry=()' != '()'
         # Disable this:
-        if (gdb_major_version, gdb_minor_version) >= (7, 4):
+        if GDB_VERSION >= (7, 4):
             commands += ['set print entry-values no']
 
         if cmds_after_breakpoint:
@@ -237,13 +255,16 @@ class DebuggerTests(unittest.TestCase):
         for pattern in (
             '(frame information optimized out)',
             'Unable to read information on python frame',
+
             # gh-91960: On Python built with "clang -Og", gdb gets
             # "frame=<optimized out>" for _PyEval_EvalFrameDefault() parameter
             '(unable to read python frame information)',
+
             # gh-104736: On Python built with "clang -Og" on ppc64le,
             # "py-bt" displays a truncated or not traceback, but "where"
             # logs this error message:
             'Backtrace stopped: frame did not save the PC',
+
             # gh-104736: When "bt" command displays something like:
             # "#1  0x0000000000000000 in ?? ()", the traceback is likely
             # truncated or wrong.
@@ -254,42 +275,6 @@ class DebuggerTests(unittest.TestCase):
 
         return out
 
-    def get_gdb_repr(self, source,
-                     cmds_after_breakpoint=None,
-                     import_site=False):
-        # Given an input python source representation of data,
-        # run "python -c'id(DATA)'" under gdb with a breakpoint on
-        # builtin_id and scrape out gdb's representation of the "op"
-        # parameter, and verify that the gdb displays the same string
-        #
-        # Verify that the gdb displays the expected string
-        #
-        # For a nested structure, the first time we hit the breakpoint will
-        # give us the top-level structure
-
-        # NOTE: avoid decoding too much of the traceback as some
-        # undecodable characters may lurk there in optimized mode
-        # (issue #19743).
-        cmds_after_breakpoint = cmds_after_breakpoint or ["backtrace 1"]
-        gdb_output = self.get_stack_trace(source, breakpoint=BREAKPOINT_FN,
-                                          cmds_after_breakpoint=cmds_after_breakpoint,
-                                          import_site=import_site)
-        # gdb can insert additional '\n' and space characters in various places
-        # in its output, depending on the width of the terminal it's connected
-        # to (using its "wrap_here" function)
-        m = re.search(
-            # Match '#0 builtin_id(self=..., v=...)'
-            r'#0\s+builtin_id\s+\(self\=.*,\s+v=\s*(.*?)?\)'
-            # Match ' at Python/bltinmodule.c'.
-            # bpo-38239: builtin_id() is defined in Python/bltinmodule.c,
-            # but accept any "Directory\file.c" to support Link Time
-            # Optimization (LTO).
-            r'\s+at\s+\S*[A-Za-z]+/[A-Za-z0-9_-]+\.c',
-            gdb_output, re.DOTALL)
-        if not m:
-            self.fail('Unexpected gdb output: %r\n%s' % (gdb_output, gdb_output))
-        return m.group(1), gdb_output
-
     def assertEndsWith(self, actual, exp_end):
         '''Ensure that the given "actual" string ends with "exp_end"'''
         self.assertTrue(actual.endswith(exp_end),
@@ -299,6 +284,3 @@ class DebuggerTests(unittest.TestCase):
         m = re.match(pattern, actual, re.DOTALL)
         if not m:
             self.fail(msg='%r did not match %r' % (actual, pattern))
-
-    def get_sample_script(self):
-        return os.path.join(os.path.dirname(__file__), 'gdb_sample.py')