1from __future__ import print_function
2from __future__ import absolute_import
3
4# System modules
5import argparse
6import sys
7import multiprocessing
8import os
9import textwrap
10
11# Third-party modules
12
13# LLDB modules
14from . import configuration
15
16
17class ArgParseNamespace(object):
18    pass
19
20
21def parse_args(parser, argv):
22    """ Returns an argument object. LLDB_TEST_ARGUMENTS environment variable can
23        be used to pass additional arguments.
24    """
25    args = ArgParseNamespace()
26
27    if ('LLDB_TEST_ARGUMENTS' in os.environ):
28        print(
29            "Arguments passed through environment: '%s'" %
30            os.environ['LLDB_TEST_ARGUMENTS'])
31        args = parser.parse_args([sys.argv[0]].__add__(
32            os.environ['LLDB_TEST_ARGUMENTS'].split()), namespace=args)
33
34    return parser.parse_args(args=argv, namespace=args)
35
36
37def default_thread_count():
38    # Check if specified in the environment
39    num_threads_str = os.environ.get("LLDB_TEST_THREADS")
40    if num_threads_str:
41        return int(num_threads_str)
42    else:
43        return multiprocessing.cpu_count()
44
45
46def create_parser():
47    parser = argparse.ArgumentParser(
48        description='description',
49        prefix_chars='+-',
50        add_help=False)
51    group = None
52
53    # Helper function for boolean options (group will point to the current
54    # group when executing X)
55    X = lambda optstr, helpstr, **kwargs: group.add_argument(
56        optstr, help=helpstr, action='store_true', **kwargs)
57
58    group = parser.add_argument_group('Help')
59    group.add_argument(
60        '-h',
61        '--help',
62        dest='h',
63        action='store_true',
64        help="Print this help message and exit.  Add '-v' for more detailed help.")
65
66    # C and Python toolchain options
67    group = parser.add_argument_group('Toolchain options')
68    group.add_argument(
69        '-A',
70        '--arch',
71        metavar='arch',
72        action='append',
73        dest='archs',
74        help=textwrap.dedent('''Specify the architecture(s) to test. This option can be specified more than once'''))
75    group.add_argument('-C', '--compiler', metavar='compiler', dest='compilers', action='append', help=textwrap.dedent(
76        '''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.'''))
77    if sys.platform == 'darwin':
78        group.add_argument('--apple-sdk', metavar='apple_sdk', dest='apple_sdk', default="macosx", help=textwrap.dedent(
79            '''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.'''))
80    # FIXME? This won't work for different extra flags according to each arch.
81    group.add_argument(
82        '-E',
83        metavar='extra-flags',
84        help=textwrap.dedent('''Specify the extra flags to be passed to the toolchain when building the inferior programs to be debugged
85                                                           suggestions: do not lump the "-A arch1 -A arch2" together such that the -E option applies to only one of the architectures'''))
86
87    # Test filtering options
88    group = parser.add_argument_group('Test filtering options')
89    group.add_argument(
90        '-f',
91        metavar='filterspec',
92        action='append',
93        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?
94    X('-l', "Don't skip long running tests")
95    group.add_argument(
96        '-p',
97        metavar='pattern',
98        help='Specify a regexp filename pattern for inclusion in the test suite')
99    group.add_argument('--excluded', metavar='exclusion-file', action='append', help=textwrap.dedent(
100        '''Specify a file for tests to exclude. File should contain lists of regular expressions for test files or methods,
101                                with each list under a matching header (xfail files, xfail methods, skip files, skip methods)'''))
102    group.add_argument(
103        '-G',
104        '--category',
105        metavar='category',
106        action='append',
107        dest='categoriesList',
108        help=textwrap.dedent('''Specify categories of test cases of interest. Can be specified more than once.'''))
109    group.add_argument(
110        '--skip-category',
111        metavar='category',
112        action='append',
113        dest='skipCategories',
114        help=textwrap.dedent('''Specify categories of test cases to skip. Takes precedence over -G. Can be specified more than once.'''))
115
116    # Configuration options
117    group = parser.add_argument_group('Configuration options')
118    group.add_argument(
119        '--framework',
120        metavar='framework-path',
121        help='The path to LLDB.framework')
122    group.add_argument(
123        '--executable',
124        metavar='executable-path',
125        help='The path to the lldb executable')
126    group.add_argument(
127        '-s',
128        metavar='name',
129        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')
130    group.add_argument(
131        '-S',
132        '--session-file-format',
133        default=configuration.session_file_format,
134        metavar='format',
135        help='Specify session file name format.  See configuration.py for a description.')
136    group.add_argument(
137        '-y',
138        type=int,
139        metavar='count',
140        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.")
141    group.add_argument(
142        '-#',
143        type=int,
144        metavar='sharp',
145        dest='sharp',
146        help='Repeat the test suite for a specified number of times')
147    group.add_argument('--channel', metavar='channel', dest='channels', action='append', help=textwrap.dedent(
148        "Specify the log channels (and optional categories) e.g. 'lldb all' or 'gdb-remote packets' if no categories are specified, 'default' is used"))
149    group.add_argument(
150        '--log-success',
151        dest='log_success',
152        action='store_true',
153        help="Leave logs/traces even for successful test runs (useful for creating reference log files during debugging.)")
154    group.add_argument(
155        '--codesign-identity',
156        metavar='Codesigning identity',
157        default='lldb_codesign',
158        help='The codesigning identity to use')
159
160    # Configuration options
161    group = parser.add_argument_group('Remote platform options')
162    group.add_argument(
163        '--platform-name',
164        dest='lldb_platform_name',
165        metavar='platform-name',
166        help='The name of a remote platform to use')
167    group.add_argument(
168        '--platform-url',
169        dest='lldb_platform_url',
170        metavar='platform-url',
171        help='A LLDB platform URL to use when connecting to a remote platform to run the test suite')
172    group.add_argument(
173        '--platform-working-dir',
174        dest='lldb_platform_working_dir',
175        metavar='platform-working-dir',
176        help='The directory to use on the remote platform.')
177
178    # Test-suite behaviour
179    group = parser.add_argument_group('Runtime behaviour options')
180    X('-d', 'Suspend the process after launch to wait indefinitely for a debugger to attach')
181    X('-q', "Don't print extra output from this script.")
182    X('-t', 'Turn on tracing of lldb command and other detailed test executions')
183    group.add_argument(
184        '-u',
185        dest='unset_env_varnames',
186        metavar='variable',
187        action='append',
188        help='Specify an environment variable to unset before running the test cases. e.g., -u DYLD_INSERT_LIBRARIES -u MallocScribble')
189    group.add_argument(
190        '--env',
191        dest='set_env_vars',
192        metavar='variable',
193        action='append',
194        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')
195    X('-v', 'Do verbose mode of unittest framework (print out each test case invocation)')
196    group.add_argument(
197        '--enable-crash-dialog',
198        dest='disable_crash_dialog',
199        action='store_false',
200        help='(Windows only) When LLDB crashes, display the Windows crash dialog.')
201    group.set_defaults(disable_crash_dialog=True)
202
203    group = parser.add_argument_group('Parallel execution options')
204    group.add_argument(
205        '--inferior',
206        action='store_true',
207        help=('specify this invocation is a multiprocess inferior, '
208              'used internally'))
209    group.add_argument(
210        '--no-multiprocess',
211        action='store_true',
212        help='skip running the multiprocess test runner')
213    group.add_argument(
214        '--threads',
215        type=int,
216        dest='num_threads',
217        default=default_thread_count(),
218        help=('The number of threads/processes to use when running tests '
219              'separately, defaults to the number of CPU cores available'))
220    group.add_argument(
221        '--test-subdir',
222        action='store',
223        help='Specify a test subdirectory to use relative to the test root dir'
224    )
225    group.add_argument(
226        '--test-runner-name',
227        action='store',
228        help=('Specify a test runner strategy.  Valid values: multiprocessing,'
229              ' multiprocessing-pool, serial, threading, threading-pool')
230    )
231
232    # Test results support.
233    group = parser.add_argument_group('Test results options')
234    group.add_argument(
235        '--curses',
236        action='store_true',
237        help='Shortcut for specifying test results using the curses formatter')
238    group.add_argument(
239        '--results-file',
240        action='store',
241        help=('Specifies the file where test results will be written '
242              'according to the results-formatter class used'))
243    group.add_argument(
244        '--results-port',
245        action='store',
246        type=int,
247        help=('Specifies the localhost port to which the results '
248              'formatted output should be sent'))
249    group.add_argument(
250        '--results-formatter',
251        action='store',
252        help=('Specifies the full package/module/class name used to translate '
253              'test events into some kind of meaningful report, written to '
254              'the designated output results file-like object'))
255    group.add_argument(
256        '--results-formatter-option',
257        '-O',
258        action='append',
259        dest='results_formatter_options',
260        help=('Specify an option to pass to the formatter. '
261              'Use --results-formatter-option="--option1=val1" '
262              'syntax.  Note the "=" is critical, don\'t include whitespace.'))
263    group.add_argument(
264        '--event-add-entries',
265        action='store',
266        help=('Specify comma-separated KEY=VAL entries to add key and value '
267              'pairs to all test events generated by this test run.  VAL may '
268              'be specified as VAL:TYPE, where TYPE may be int to convert '
269              'the value to an int'))
270
271    # Re-run related arguments
272    group = parser.add_argument_group('Test Re-run Options')
273    group.add_argument(
274        '--rerun-all-issues',
275        action='store_true',
276        help=('Re-run all issues that occurred during the test run '
277              'irrespective of the test method\'s marking as flakey. '
278              'Default behavior is to apply re-runs only to flakey '
279              'tests that generate issues.'))
280    group.add_argument(
281        '--rerun-max-file-threshold',
282        action='store',
283        type=int,
284        default=50,
285        help=('Maximum number of files requiring a rerun beyond '
286              'which the rerun will not occur.  This is meant to '
287              'stop a catastrophically failing test suite from forcing '
288              'all tests to be rerun in the single-worker phase.'))
289
290    # Remove the reference to our helper function
291    del X
292
293    group = parser.add_argument_group('Test directories')
294    group.add_argument(
295        'args',
296        metavar='test-dir',
297        nargs='*',
298        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.')
299
300    return parser
301