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

# System modules
import argparse
import sys
import os
import textwrap

# LLDB modules
from . import configuration


def create_parser():
    parser = argparse.ArgumentParser(
        description="description", prefix_chars="+-", add_help=False
    )
    group = None

    # Helper function for boolean options (group will point to the current
    # group when executing X)
    X = lambda optstr, helpstr, **kwargs: group.add_argument(
        optstr, help=helpstr, action="store_true", **kwargs
    )

    group = parser.add_argument_group("Help")
    group.add_argument(
        "-h",
        "--help",
        dest="h",
        action="store_true",
        help="Print this help message and exit.  Add '-v' for more detailed help.",
    )

    # C and Python toolchain options
    group = parser.add_argument_group("Toolchain options")
    group.add_argument(
        "--triple",
        metavar="triple",
        dest="triple",
        help=textwrap.dedent(
            """Specify the target triple to test with (e.g. x86_64-unknown-linux-gnu, arm64-apple-macosx)."""
        ),
    )
    group.add_argument(
        "-C",
        "--compiler",
        metavar="compiler",
        dest="compiler",
        help=textwrap.dedent(
            """Specify the compiler(s) used to build the inferior executables. The compiler path can be an executable basename or a full path to a compiler executable. This option can be specified multiple times."""
        ),
    )
    group.add_argument(
        "--sysroot",
        metavar="sysroot",
        dest="sysroot",
        default="",
        help=textwrap.dedent(
            """Specify the path to sysroot. This overrides apple_sdk sysroot."""
        ),
    )
    if sys.platform == "darwin":
        group.add_argument(
            "--apple-sdk",
            metavar="apple_sdk",
            dest="apple_sdk",
            default="",
            help=textwrap.dedent(
                """Specify the name of the Apple SDK (macosx, macosx.internal, iphoneos, iphoneos.internal, or path to SDK) and use the appropriate tools from that SDK's toolchain."""
            ),
        )
    group.add_argument(
        "--libcxx-include-dir",
        help=textwrap.dedent(
            "Specify the path to a custom libc++ include directory. Must be used in conjunction with --libcxx-library-dir."
        ),
    )
    group.add_argument(
        "--libcxx-include-target-dir",
        help=textwrap.dedent(
            "Specify the path to a custom libc++ include target directory to use in addition to --libcxx-include-dir. Optional."
        ),
    )
    group.add_argument(
        "--libcxx-library-dir",
        help=textwrap.dedent(
            "Specify the path to a custom libc++ library directory. Must be used in conjunction with --libcxx-include-dir."
        ),
    )
    # FIXME? This won't work for different extra flags according to each triple.
    group.add_argument(
        "-E",
        metavar="extra-flags",
        help=textwrap.dedent(
            """Specify the extra flags to be passed to the toolchain when building the inferior programs to be debugged."""
        ),
    )

    group.add_argument(
        "--make",
        metavar="make",
        dest="make",
        help=textwrap.dedent("Specify which make to use."),
    )
    group.add_argument(
        "--dsymutil",
        metavar="dsymutil",
        dest="dsymutil",
        help=textwrap.dedent("Specify which dsymutil to use."),
    )
    group.add_argument(
        "--resource-dir",
        metavar="dir",
        dest="resource_dir",
        default="",
        help=textwrap.dedent(
            "Specify the clang resource directory for cross-compiling test inferiors."
        ),
    )
    group.add_argument(
        "--llvm-tools-dir",
        metavar="dir",
        dest="llvm_tools_dir",
        help=textwrap.dedent(
            "The location of llvm tools used for testing (yaml2obj, FileCheck, etc.)."
        ),
    )

    # Test filtering options
    group = parser.add_argument_group("Test filtering options")
    group.add_argument(
        "-f",
        metavar="filterspec",
        action="append",
        help=(
            'Specify a filter, which looks like "TestModule.TestClass.test_name".  '
            + "You may also use shortened filters, such as "
            + '"TestModule.TestClass", "TestClass.test_name", or just "test_name".'
        ),
    )
    group.add_argument(
        "-p",
        metavar="pattern",
        help="Specify a regexp filename pattern for inclusion in the test suite",
    )
    group.add_argument(
        "--excluded",
        metavar="exclusion-file",
        action="append",
        help=textwrap.dedent(
            """Specify a file for tests to exclude. File should contain lists of regular expressions for test files or methods,
                                with each list under a matching header (xfail files, xfail methods, skip files, skip methods)"""
        ),
    )
    group.add_argument(
        "-G",
        "--category",
        metavar="category",
        action="append",
        dest="categories_list",
        help=textwrap.dedent(
            """Specify categories of test cases of interest. Can be specified more than once."""
        ),
    )
    group.add_argument(
        "--skip-category",
        metavar="category",
        action="append",
        dest="skip_categories",
        help=textwrap.dedent(
            """Specify categories of test cases to skip. Takes precedence over -G. Can be specified more than once."""
        ),
    )
    group.add_argument(
        "--xfail-category",
        metavar="category",
        action="append",
        dest="xfail_categories",
        help=textwrap.dedent(
            """Specify categories of test cases that are expected to fail. Can be specified more than once."""
        ),
    )

    # Configuration options
    group = parser.add_argument_group("Configuration options")
    group.add_argument(
        "--framework", metavar="framework-path", help="The path to LLDB.framework"
    )
    group.add_argument(
        "--executable",
        metavar="executable-path",
        help="The path to the lldb executable",
    )
    group.add_argument(
        "--out-of-tree-debugserver",
        dest="out_of_tree_debugserver",
        action="store_true",
        help="A flag to indicate an out-of-tree debug server is being used",
    )
    group.add_argument(
        "--dwarf-version",
        metavar="dwarf_version",
        dest="dwarf_version",
        type=int,
        help="Override the DWARF version.",
    )
    group.add_argument(
        "--setting",
        metavar="SETTING=VALUE",
        dest="settings",
        type=str,
        nargs=1,
        action="append",
        help='Run "setting set SETTING VALUE" before executing any test.',
    )
    group.add_argument(
        "-y",
        type=int,
        metavar="count",
        help="Specify the iteration count used to collect our benchmarks. An example is the number of times to do 'thread step-over' to measure stepping speed.",
    )
    group.add_argument(
        "-#",
        type=int,
        metavar="sharp",
        dest="sharp",
        help="Repeat the test suite for a specified number of times",
    )
    group.add_argument(
        "--channel",
        metavar="channel",
        dest="channels",
        action="append",
        help=textwrap.dedent(
            "Specify the log channels (and optional categories) e.g. 'lldb all' or 'gdb-remote packets' if no categories are specified, 'default' is used"
        ),
    )
    group.add_argument(
        "--log-success",
        dest="log_success",
        action="store_true",
        help="Leave logs/traces even for successful test runs (useful for creating reference log files during debugging.)",
    )
    group.add_argument(
        "--build-dir",
        dest="test_build_dir",
        metavar="Test build directory",
        default=(
            "lldb-test-build.noindex" if sys.platform == "darwin" else "lldb-test-build"
        ),
        help="The root build directory for the tests. It will be removed before running.",
    )
    group.add_argument(
        "--timeout",
        dest="timeout",
        metavar="Timeout in seconds",
        type=float,
        default=0,
        help="The timeout lit is using to run this test, if any.",
    )
    group.add_argument(
        "--lldb-module-cache-dir",
        dest="lldb_module_cache_dir",
        metavar="The clang module cache directory used by LLDB",
        help="The clang module cache directory used by LLDB. Defaults to <test build directory>/module-cache-lldb.",
    )
    group.add_argument(
        "--clang-module-cache-dir",
        dest="clang_module_cache_dir",
        metavar="The clang module cache directory used by Clang",
        help="The clang module cache directory used in the Make files by Clang while building tests. Defaults to <test build directory>/module-cache-clang.",
    )
    group.add_argument(
        "--lldb-obj-root",
        dest="lldb_obj_root",
        metavar="path",
        help="The path to the LLDB object files.",
    )
    group.add_argument(
        "--lldb-libs-dir",
        dest="lldb_libs_dir",
        metavar="path",
        help="The path to LLDB library directory (containing liblldb).",
    )
    group.add_argument(
        "--enable-plugin",
        dest="enabled_plugins",
        action="append",
        type=str,
        metavar="A plugin whose tests will be enabled",
        help="A plugin whose tests will be enabled. The only currently supported plugin is intel-pt.",
    )
    group.add_argument(
        "--enable-mte",
        dest="enable_mte",
        action="store_true",
        help="Indicate that the test suite is running with MTE (Memory Tagging Extension) enabled.",
    )
    group.add_argument(
        "--arm64e-debugserver",
        dest="arm64e_debugserver",
        action="store_true",
        help="Indicate that debugserver is built with arm64e support.",
    )
    group.add_argument(
        "--print-lldb-version",
        dest="print_lldb_version",
        action="store_true",
        help="Print the lldb version banner during test setup.",
    )
    group.add_argument(
        "--lldb-python-dir",
        dest="lldb_python_dir",
        metavar="path",
        help="Path to the directory that contains the 'lldb' Python module. ",
    )

    # Configuration options
    group = parser.add_argument_group("Remote platform options")
    group.add_argument(
        "--platform-name",
        dest="lldb_platform_name",
        metavar="platform-name",
        help="The name of a remote platform to use",
    )
    group.add_argument(
        "--platform-url",
        dest="lldb_platform_url",
        metavar="platform-url",
        help="A LLDB platform URL to use when connecting to a remote platform to run the test suite",
    )
    group.add_argument(
        "--platform-working-dir",
        dest="lldb_platform_working_dir",
        metavar="platform-working-dir",
        help="The directory to use on the remote platform.",
    )
    group.add_argument(
        "--platform-available-ports",
        dest="lldb_platform_available_ports",
        nargs="*",
        type=int,
        metavar="platform-available-ports",
        help="Ports available for connection to a lldb server on the remote platform",
    )
    group.add_argument(
        "--cmake-build-type",
        dest="cmake_build_type",
        metavar="cmake-build-type",
        help="Specifies the build type on single-configuration",
    )

    # Test-suite behaviour
    group = parser.add_argument_group("Runtime behaviour options")
    X(
        "-d",
        "Suspend the process after launch to wait indefinitely for a debugger to attach",
    )
    group.add_argument(
        "--debug-with",
        dest="debug_with",
        choices=["xcode"],
        type=str.lower,
        help="Suspend the process after launch, and instruct the specified debugger to attach to it",
    )
    X("-t", "Turn on tracing of lldb command and other detailed test executions")
    group.add_argument(
        "-u",
        dest="unset_env_varnames",
        metavar="variable",
        action="append",
        help="Specify an environment variable to unset before running the test cases. e.g., -u DYLD_INSERT_LIBRARIES -u MallocScribble",
    )
    group.add_argument(
        "--env",
        dest="set_env_vars",
        metavar="variable",
        action="append",
        help="Specify an environment variable to set to the given value before running the test cases e.g.: --env CXXFLAGS=-O3 --env DYLD_INSERT_LIBRARIES",
    )
    group.add_argument(
        "--inferior-env",
        dest="set_inferior_env_vars",
        metavar="variable",
        action="append",
        help="Specify an environment variable to set to the given value for the inferior.",
    )
    X(
        "-v",
        "Do verbose mode of unittest framework (print out each test case invocation)",
    )
    group.add_argument(
        "--enable-crash-dialog",
        dest="disable_crash_dialog",
        action="store_false",
        help="(Windows only) When LLDB crashes, display the Windows crash dialog.",
    )
    group.set_defaults(disable_crash_dialog=True)

    # Remove the reference to our helper function
    del X

    group = parser.add_argument_group("Test directories")
    group.add_argument(
        "args",
        metavar="test-dir",
        nargs="*",
        help="Specify a list of directory names to search for test modules named after Test*.py (test discovery). If empty, search from the current working directory instead.",
    )

    return parser