1from __future__ import print_function
2
3import argparse
4import sys
5import multiprocessing
6import os
7import textwrap
8
9class ArgParseNamespace(object):
10    pass
11
12def parse_args(parser, argv):
13    """ Returns an argument object. LLDB_TEST_ARGUMENTS environment variable can
14        be used to pass additional arguments.
15    """
16    args = ArgParseNamespace()
17
18    if ('LLDB_TEST_ARGUMENTS' in os.environ):
19        print("Arguments passed through environment: '%s'" % os.environ['LLDB_TEST_ARGUMENTS'])
20        args = parser.parse_args([sys.argv[0]].__add__(os.environ['LLDB_TEST_ARGUMENTS'].split()),namespace=args)
21
22    return parser.parse_args(args=argv, namespace=args)
23
24
25def default_thread_count():
26    # Check if specified in the environment
27    num_threads_str = os.environ.get("LLDB_TEST_THREADS")
28    if num_threads_str:
29        return int(num_threads_str)
30    else:
31        return multiprocessing.cpu_count()
32
33
34def create_parser():
35    parser = argparse.ArgumentParser(description='description', prefix_chars='+-', add_help=False)
36    group = None
37
38    # Helper function for boolean options (group will point to the current group when executing X)
39    X = lambda optstr, helpstr, **kwargs: group.add_argument(optstr, help=helpstr, action='store_true', **kwargs)
40
41    group = parser.add_argument_group('Help')
42    group.add_argument('-h', '--help', dest='h', action='store_true', help="Print this help message and exit.  Add '-v' for more detailed help.")
43
44    # C and Python toolchain options
45    group = parser.add_argument_group('Toolchain options')
46    group.add_argument('-A', '--arch', metavar='arch', action='append', dest='archs', help=textwrap.dedent('''Specify the architecture(s) to test. This option can be specified more than once'''))
47    group.add_argument('-C', '--compiler', metavar='compiler', dest='compilers', action='append', 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.'''))
48    if sys.platform == 'darwin':
49        group.add_argument('--apple-sdk', metavar='apple_sdk', dest='apple_sdk', 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.'''))
50    # FIXME? This won't work for different extra flags according to each arch.
51    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
52                                                           suggestions: do not lump the "-A arch1 -A arch2" together such that the -E option applies to only one of the architectures'''))
53    X('-D', 'Dump the Python sys.path variable')
54
55    # Test filtering options
56    group = parser.add_argument_group('Test filtering options')
57    group.add_argument('-N', choices=['dwarf', 'dwo', 'dsym'], help="Don't do test cases marked with the @dsym_test/@dwarf_test/@dwo_test decorator by passing dsym/dwarf/dwo as the option arg")
58    X('+b', 'Just do benchmark tests', dest='plus_b')
59    group.add_argument('-b', metavar='blacklist', help='Read a blacklist file specified after this option')
60    group.add_argument('-f', metavar='filterspec', action='append', help='Specify a filter, which consists of the test class name, a dot, followed by the test method, to only admit such test into the test suite')  # FIXME: Example?
61    X('-g', 'If specified, the filterspec by -f is not exclusive, i.e., if a test module does not match the filterspec (testclass.testmethod), the whole module is still admitted to the test suite')
62    X('-l', "Don't skip long running tests")
63    group.add_argument('-p', metavar='pattern', help='Specify a regexp filename pattern for inclusion in the test suite')
64    group.add_argument('-X', metavar='directory', help="Exclude a directory from consideration for test discovery. -X types => if 'types' appear in the pathname components of a potential testfile, it will be ignored")
65    group.add_argument('-G', '--category', metavar='category', action='append', dest='categoriesList', help=textwrap.dedent('''Specify categories of test cases of interest. Can be specified more than once.'''))
66    group.add_argument('--skip-category', metavar='category', action='append', dest='skipCategories', help=textwrap.dedent('''Specify categories of test cases to skip. Takes precedence over -G. Can be specified more than once.'''))
67
68    # Configuration options
69    group = parser.add_argument_group('Configuration options')
70    group.add_argument('-c', metavar='config-file', help='Read a config file specified after this option')  # FIXME: additional doc.
71    group.add_argument('--framework', metavar='framework-path', help='The path to LLDB.framework')
72    group.add_argument('--executable', metavar='executable-path', help='The path to the lldb executable')
73    group.add_argument('--libcxx', metavar='directory', help='The path to custom libc++ library')
74    group.add_argument('-e', metavar='benchmark-exe', help='Specify the full path of an executable used for benchmark purposes (see also: -x)')
75    group.add_argument('-k', metavar='command', action='append', help="Specify a runhook, which is an lldb command to be executed by the debugger; The option can occur multiple times. The commands are executed one after the other to bring the debugger to a desired state, so that, for example, further benchmarking can be done")
76    group.add_argument('-R', metavar='dir', help='Specify a directory to relocate the tests and their intermediate files to. BE WARNED THAT the directory, if exists, will be deleted before running this test driver. No cleanup of intermediate test files is performed in this case')
77    group.add_argument('-r', metavar='dir', help="Similar to '-R', except that the directory must not exist before running this test driver")
78    group.add_argument('-s', metavar='name', help='Specify the name of the dir created to store the session files of tests with errored or failed status. If not specified, the test driver uses the timestamp as the session dir name')
79    group.add_argument('-x', metavar='breakpoint-spec', help='Specify the breakpoint specification for the benchmark executable')
80    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.")
81    group.add_argument('-#', type=int, metavar='sharp', dest='sharp', help='Repeat the test suite for a specified number of times')
82    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"))
83    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.)")
84
85    # Configuration options
86    group = parser.add_argument_group('Remote platform options')
87    group.add_argument('--platform-name', dest='lldb_platform_name', metavar='platform-name', help='The name of a remote platform to use')
88    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')
89    group.add_argument('--platform-working-dir', dest='lldb_platform_working_dir', metavar='platform-working-dir', help='The directory to use on the remote platform.')
90
91    # Test-suite behaviour
92    group = parser.add_argument_group('Runtime behaviour options')
93    X('-d', 'Suspend the process after launch to wait indefinitely for a debugger to attach')
94    X('-F', 'Fail fast. Stop the test suite on the first error/failure')
95    X('-i', "Ignore (don't bailout) if 'lldb.py' module cannot be located in the build tree relative to this script; use PYTHONPATH to locate the module")
96    X('-n', "Don't print the headers like build dir, lldb version, and svn info at all")
97    X('-P', "Use the graphic progress bar.")
98    X('-q', "Don't print extra output from this script.")
99    X('-S', "Skip the build and cleanup while running the test. Use this option with care as you would need to build the inferior(s) by hand and build the executable(s) with the correct name(s). This can be used with '-# n' to stress test certain test cases for n number of times")
100    X('-t', 'Turn on tracing of lldb command and other detailed test executions')
101    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')
102    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')
103    X('-v', 'Do verbose mode of unittest framework (print out each test case invocation)')
104    X('-w', 'Insert some wait time (currently 0.5 sec) between consecutive test cases')
105    X('-T', 'Obtain and dump svn information for this checkout of LLDB (off by default)')
106    group.add_argument('--enable-crash-dialog', dest='disable_crash_dialog', action='store_false', help='(Windows only) When LLDB crashes, display the Windows crash dialog.')
107    group.add_argument('--show-inferior-console', dest='hide_inferior_console', action='store_false', help='(Windows only) When launching an inferior, dont hide its console window.')
108    group.set_defaults(disable_crash_dialog=True)
109    group.set_defaults(hide_inferior_console=True)
110
111    group = parser.add_argument_group('Parallel execution options')
112    group.add_argument(
113        '--inferior',
114        action='store_true',
115        help=('specify this invocation is a multiprocess inferior, '
116              'used internally'))
117    group.add_argument(
118        '--no-multiprocess',
119        action='store_true',
120        help='skip running the multiprocess test runner')
121    group.add_argument(
122        '--output-on-success',
123        action='store_true',
124        help=('print full output of the dotest.py inferior, '
125              'even when all tests succeed'))
126    group.add_argument(
127        '--threads',
128        type=int,
129        dest='num_threads',
130        default=default_thread_count(),
131        help=('The number of threads/processes to use when running tests '
132              'separately, defaults to the number of CPU cores available'))
133    group.add_argument(
134        '--test-subdir',
135        action='store',
136        help='Specify a test subdirectory to use relative to the test root dir'
137    )
138    group.add_argument(
139        '--test-runner-name',
140        action='store',
141        help=('Specify a test runner strategy.  Valid values: multiprocessing,'
142              ' multiprocessing-pool, serial, threading, threading-pool')
143    )
144
145    # Test results support.
146    group = parser.add_argument_group('Test results options')
147    group.add_argument(
148        '--results-file',
149        action='store',
150        help=('Specifies the file where test results will be written '
151              'according to the results-formatter class used'))
152    group.add_argument(
153        '--results-port',
154        action='store',
155        type=int,
156        help=('Specifies the localhost port to which the results '
157              'formatted output should be sent'))
158    group.add_argument(
159        '--results-formatter',
160        action='store',
161        help=('Specifies the full package/module/class name used to translate '
162              'test events into some kind of meaningful report, written to '
163              'the designated output results file-like object'))
164    group.add_argument(
165        '--results-formatter-option',
166        '-O',
167        action='append',
168        dest='results_formatter_options',
169        help=('Specify an option to pass to the formatter. '
170              'Use --results-formatter-option="--option1=val1" '
171              'syntax.  Note the "=" is critical, don\'t include whitespace.'))
172    group.add_argument(
173        '--event-add-entries',
174        action='store',
175        help=('Specify comma-separated KEY=VAL entries to add key and value '
176              'pairs to all test events generated by this test run.  VAL may '
177              'be specified as VAL:TYPE, where TYPE may be int to convert '
178              'the value to an int'))
179    # Remove the reference to our helper function
180    del X
181
182    D = lambda optstr, **kwargs: group.add_argument(optstr, action='store_true', **kwargs)
183    group = parser.add_argument_group('Deprecated options (do not use)')
184    # Deprecated on 23.10.2015. Remove completely after a grace period.
185    D('-a')
186    D('+a', dest='plus_a')
187    D('-m')
188    D('+m', dest='plus_m')
189    del D
190
191    group = parser.add_argument_group('Test directories')
192    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.')
193
194    return parser
195