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        dest='arch',
73        help=textwrap.dedent('''Specify the architecture(s) to test. This option can be specified more than once'''))
74    group.add_argument('-C', '--compiler', metavar='compiler', dest='compiler', help=textwrap.dedent(
75        '''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.'''))
76    if sys.platform == 'darwin':
77        group.add_argument('--apple-sdk', metavar='apple_sdk', dest='apple_sdk', default="macosx", help=textwrap.dedent(
78            '''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.'''))
79    # FIXME? This won't work for different extra flags according to each arch.
80    group.add_argument(
81        '-E',
82        metavar='extra-flags',
83        help=textwrap.dedent('''Specify the extra flags to be passed to the toolchain when building the inferior programs to be debugged
84                                                           suggestions: do not lump the "-A arch1 -A arch2" together such that the -E option applies to only one of the architectures'''))
85
86    group.add_argument('--dsymutil', metavar='dsymutil', dest='dsymutil', help=textwrap.dedent('Specify which dsymutil to use.'))
87
88    group.add_argument('--filecheck', metavar='filecheck', dest='filecheck', help=textwrap.dedent('Specify which FileCheck binary to use.'))
89
90    # Test filtering options
91    group = parser.add_argument_group('Test filtering options')
92    group.add_argument(
93        '-f',
94        metavar='filterspec',
95        action='append',
96        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?
97    X('-l', "Don't skip long running tests")
98    group.add_argument(
99        '-p',
100        metavar='pattern',
101        help='Specify a regexp filename pattern for inclusion in the test suite')
102    group.add_argument('--excluded', metavar='exclusion-file', action='append', help=textwrap.dedent(
103        '''Specify a file for tests to exclude. File should contain lists of regular expressions for test files or methods,
104                                with each list under a matching header (xfail files, xfail methods, skip files, skip methods)'''))
105    group.add_argument(
106        '-G',
107        '--category',
108        metavar='category',
109        action='append',
110        dest='categoriesList',
111        help=textwrap.dedent('''Specify categories of test cases of interest. Can be specified more than once.'''))
112    group.add_argument(
113        '--skip-category',
114        metavar='category',
115        action='append',
116        dest='skipCategories',
117        help=textwrap.dedent('''Specify categories of test cases to skip. Takes precedence over -G. Can be specified more than once.'''))
118
119    # Configuration options
120    group = parser.add_argument_group('Configuration options')
121    group.add_argument(
122        '--framework',
123        metavar='framework-path',
124        help='The path to LLDB.framework')
125    group.add_argument(
126        '--executable',
127        metavar='executable-path',
128        help='The path to the lldb executable')
129    group.add_argument(
130        '--server',
131        metavar='server-path',
132        help='The path to the debug server executable to use')
133    group.add_argument(
134        '--out-of-tree-debugserver',
135        dest='out_of_tree_debugserver',
136        action='store_true',
137        help='A flag to indicate an out-of-tree debug server is being used')
138    group.add_argument(
139        '-s',
140        metavar='name',
141        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')
142    group.add_argument(
143        '-S',
144        '--session-file-format',
145        default=configuration.session_file_format,
146        metavar='format',
147        help='Specify session file name format.  See configuration.py for a description.')
148    group.add_argument(
149        '-y',
150        type=int,
151        metavar='count',
152        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.")
153    group.add_argument(
154        '-#',
155        type=int,
156        metavar='sharp',
157        dest='sharp',
158        help='Repeat the test suite for a specified number of times')
159    group.add_argument('--channel', metavar='channel', dest='channels', action='append', help=textwrap.dedent(
160        "Specify the log channels (and optional categories) e.g. 'lldb all' or 'gdb-remote packets' if no categories are specified, 'default' is used"))
161    group.add_argument(
162        '--log-success',
163        dest='log_success',
164        action='store_true',
165        help="Leave logs/traces even for successful test runs (useful for creating reference log files during debugging.)")
166    group.add_argument(
167        '--codesign-identity',
168        metavar='Codesigning identity',
169        default='lldb_codesign',
170        help='The codesigning identity to use')
171    group.add_argument(
172        '--build-dir',
173        dest='test_build_dir',
174        metavar='Test build directory',
175        default='lldb-test-build.noindex',
176        help='The root build directory for the tests. It will be removed before running.')
177
178    # Configuration options
179    group = parser.add_argument_group('Remote platform options')
180    group.add_argument(
181        '--platform-name',
182        dest='lldb_platform_name',
183        metavar='platform-name',
184        help='The name of a remote platform to use')
185    group.add_argument(
186        '--platform-url',
187        dest='lldb_platform_url',
188        metavar='platform-url',
189        help='A LLDB platform URL to use when connecting to a remote platform to run the test suite')
190    group.add_argument(
191        '--platform-working-dir',
192        dest='lldb_platform_working_dir',
193        metavar='platform-working-dir',
194        help='The directory to use on the remote platform.')
195
196    # Test-suite behaviour
197    group = parser.add_argument_group('Runtime behaviour options')
198    X('-d', 'Suspend the process after launch to wait indefinitely for a debugger to attach')
199    X('-q', "Don't print extra output from this script.")
200    X('-t', 'Turn on tracing of lldb command and other detailed test executions')
201    group.add_argument(
202        '-u',
203        dest='unset_env_varnames',
204        metavar='variable',
205        action='append',
206        help='Specify an environment variable to unset before running the test cases. e.g., -u DYLD_INSERT_LIBRARIES -u MallocScribble')
207    group.add_argument(
208        '--env',
209        dest='set_env_vars',
210        metavar='variable',
211        action='append',
212        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')
213    X('-v', 'Do verbose mode of unittest framework (print out each test case invocation)')
214    group.add_argument(
215        '--enable-crash-dialog',
216        dest='disable_crash_dialog',
217        action='store_false',
218        help='(Windows only) When LLDB crashes, display the Windows crash dialog.')
219    group.set_defaults(disable_crash_dialog=True)
220
221    group = parser.add_argument_group('Parallel execution options')
222    group.add_argument(
223        '--inferior',
224        action='store_true',
225        help=('specify this invocation is a multiprocess inferior, '
226              'used internally'))
227    group.add_argument(
228        '--no-multiprocess',
229        action='store_true',
230        help='skip running the multiprocess test runner')
231    group.add_argument(
232        '--threads',
233        type=int,
234        dest='num_threads',
235        default=default_thread_count(),
236        help=('The number of threads/processes to use when running tests '
237              'separately, defaults to the number of CPU cores available'))
238    group.add_argument(
239        '--test-subdir',
240        action='store',
241        help='Specify a test subdirectory to use relative to the test root dir'
242    )
243    group.add_argument(
244        '--test-runner-name',
245        action='store',
246        help=('Specify a test runner strategy.  Valid values: multiprocessing,'
247              ' multiprocessing-pool, serial, threading, threading-pool')
248    )
249
250    # Test results support.
251    group = parser.add_argument_group('Test results options')
252    group.add_argument(
253        '--curses',
254        action='store_true',
255        help='Shortcut for specifying test results using the curses formatter')
256    group.add_argument(
257        '--results-file',
258        action='store',
259        help=('Specifies the file where test results will be written '
260              'according to the results-formatter class used'))
261    group.add_argument(
262        '--results-port',
263        action='store',
264        type=int,
265        help=('Specifies the localhost port to which the results '
266              'formatted output should be sent'))
267    group.add_argument(
268        '--results-formatter',
269        action='store',
270        help=('Specifies the full package/module/class name used to translate '
271              'test events into some kind of meaningful report, written to '
272              'the designated output results file-like object'))
273    group.add_argument(
274        '--results-formatter-option',
275        '-O',
276        action='append',
277        dest='results_formatter_options',
278        help=('Specify an option to pass to the formatter. '
279              'Use --results-formatter-option="--option1=val1" '
280              'syntax.  Note the "=" is critical, don\'t include whitespace.'))
281    group.add_argument(
282        '--event-add-entries',
283        action='store',
284        help=('Specify comma-separated KEY=VAL entries to add key and value '
285              'pairs to all test events generated by this test run.  VAL may '
286              'be specified as VAL:TYPE, where TYPE may be int to convert '
287              'the value to an int'))
288
289    # Re-run related arguments
290    group = parser.add_argument_group('Test Re-run Options')
291    group.add_argument(
292        '--rerun-all-issues',
293        action='store_true',
294        help=('Re-run all issues that occurred during the test run '
295              'irrespective of the test method\'s marking as flakey. '
296              'Default behavior is to apply re-runs only to flakey '
297              'tests that generate issues.'))
298    group.add_argument(
299        '--rerun-max-file-threshold',
300        action='store',
301        type=int,
302        default=50,
303        help=('Maximum number of files requiring a rerun beyond '
304              'which the rerun will not occur.  This is meant to '
305              'stop a catastrophically failing test suite from forcing '
306              'all tests to be rerun in the single-worker phase.'))
307
308    # Remove the reference to our helper function
309    del X
310
311    group = parser.add_argument_group('Test directories')
312    group.add_argument(
313        'args',
314        metavar='test-dir',
315        nargs='*',
316        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.')
317
318    return parser
319