ff2ac5a47ea5063c9c283806f7a7c84bf2c7b3f6
[lldb.git] / lldb / packages / Python / lldbsuite / test / dotest_args.py
1 from __future__ import absolute_import
2
3 # System modules
4 import argparse
5 import sys
6 import os
7 import textwrap
8
9 # LLDB modules
10 from . import configuration
11
12
13 def create_parser():
14     parser = argparse.ArgumentParser(
15         description='description',
16         prefix_chars='+-',
17         add_help=False)
18     group = None
19
20     # Helper function for boolean options (group will point to the current
21     # group when executing X)
22     X = lambda optstr, helpstr, **kwargs: group.add_argument(
23         optstr, help=helpstr, action='store_true', **kwargs)
24
25     group = parser.add_argument_group('Help')
26     group.add_argument(
27         '-h',
28         '--help',
29         dest='h',
30         action='store_true',
31         help="Print this help message and exit.  Add '-v' for more detailed help.")
32
33     # C and Python toolchain options
34     group = parser.add_argument_group('Toolchain options')
35     group.add_argument(
36         '-A',
37         '--arch',
38         metavar='arch',
39         dest='arch',
40         help=textwrap.dedent('''Specify the architecture(s) to test. This option can be specified more than once'''))
41     group.add_argument('-C', '--compiler', metavar='compiler', dest='compiler', help=textwrap.dedent(
42         '''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.'''))
43     if sys.platform == 'darwin':
44         group.add_argument('--apple-sdk', metavar='apple_sdk', dest='apple_sdk', default="", help=textwrap.dedent(
45             '''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.'''))
46     # FIXME? This won't work for different extra flags according to each arch.
47     group.add_argument(
48         '-E',
49         metavar='extra-flags',
50         help=textwrap.dedent('''Specify the extra flags to be passed to the toolchain when building the inferior programs to be debugged
51                                                            suggestions: do not lump the "-A arch1 -A arch2" together such that the -E option applies to only one of the architectures'''))
52
53     group.add_argument('--dsymutil', metavar='dsymutil', dest='dsymutil', help=textwrap.dedent('Specify which dsymutil to use.'))
54
55     group.add_argument('--filecheck', metavar='filecheck', dest='filecheck', help=textwrap.dedent('Specify which FileCheck binary to use.'))
56
57     # Test filtering options
58     group = parser.add_argument_group('Test filtering options')
59     group.add_argument(
60         '-f',
61         metavar='filterspec',
62         action='append',
63         help=('Specify a filter, which looks like "TestModule.TestClass.test_name".  '+
64             'You may also use shortened filters, such as '+
65             '"TestModule.TestClass", "TestClass.test_name", or just "test_name".'))
66     group.add_argument(
67         '-p',
68         metavar='pattern',
69         help='Specify a regexp filename pattern for inclusion in the test suite')
70     group.add_argument('--excluded', metavar='exclusion-file', action='append', help=textwrap.dedent(
71         '''Specify a file for tests to exclude. File should contain lists of regular expressions for test files or methods,
72                                 with each list under a matching header (xfail files, xfail methods, skip files, skip methods)'''))
73     group.add_argument(
74         '-G',
75         '--category',
76         metavar='category',
77         action='append',
78         dest='categories_list',
79         help=textwrap.dedent('''Specify categories of test cases of interest. Can be specified more than once.'''))
80     group.add_argument(
81         '--skip-category',
82         metavar='category',
83         action='append',
84         dest='skip_categories',
85         help=textwrap.dedent('''Specify categories of test cases to skip. Takes precedence over -G. Can be specified more than once.'''))
86     group.add_argument(
87         '--xfail-category',
88         metavar='category',
89         action='append',
90         dest='xfail_categories',
91         help=textwrap.dedent('''Specify categories of test cases that are expected to fail. Can be specified more than once.'''))
92
93     # Configuration options
94     group = parser.add_argument_group('Configuration options')
95     group.add_argument(
96         '--framework',
97         metavar='framework-path',
98         help='The path to LLDB.framework')
99     group.add_argument(
100         '--executable',
101         metavar='executable-path',
102         help='The path to the lldb executable')
103     group.add_argument(
104         '--server',
105         metavar='server-path',
106         help='The path to the debug server executable to use')
107     group.add_argument(
108         '--out-of-tree-debugserver',
109         dest='out_of_tree_debugserver',
110         action='store_true',
111         help='A flag to indicate an out-of-tree debug server is being used')
112     group.add_argument(
113         '--dwarf-version',
114         metavar='dwarf_version',
115         dest='dwarf_version',
116         type=int,
117         help='Override the DWARF version.')
118     group.add_argument(
119         '--setting',
120         metavar='SETTING=VALUE',
121         dest='settings',
122         type=str,
123         nargs=1,
124         action='append',
125         help='Run "setting set SETTING VALUE" before executing any test.')
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     group.add_argument(
160         '--build-dir',
161         dest='test_build_dir',
162         metavar='Test build directory',
163         default='lldb-test-build.noindex',
164         help='The root build directory for the tests. It will be removed before running.')
165     group.add_argument(
166         '--lldb-module-cache-dir',
167         dest='lldb_module_cache_dir',
168         metavar='The clang module cache directory used by LLDB',
169         help='The clang module cache directory used by LLDB. Defaults to <test build directory>/module-cache-lldb.')
170     group.add_argument(
171         '--clang-module-cache-dir',
172         dest='clang_module_cache_dir',
173         metavar='The clang module cache directory used by Clang',
174         help='The clang module cache directory used in the Make files by Clang while building tests. Defaults to <test build directory>/module-cache-clang.')
175     group.add_argument(
176         '--lldb-libs-dir',
177         dest='lldb_libs_dir',
178         metavar='path',
179         help='The path to LLDB library directory (containing liblldb)')
180     group.add_argument(
181         '--enable-plugin',
182         dest='enabled_plugins',
183         action='append',
184         type=str,
185         metavar='A plugin whose tests will be enabled',
186         help='A plugin whose tests will be enabled. The only currently supported plugin is intel-pt.')
187
188     # Configuration options
189     group = parser.add_argument_group('Remote platform options')
190     group.add_argument(
191         '--platform-name',
192         dest='lldb_platform_name',
193         metavar='platform-name',
194         help='The name of a remote platform to use')
195     group.add_argument(
196         '--platform-url',
197         dest='lldb_platform_url',
198         metavar='platform-url',
199         help='A LLDB platform URL to use when connecting to a remote platform to run the test suite')
200     group.add_argument(
201         '--platform-working-dir',
202         dest='lldb_platform_working_dir',
203         metavar='platform-working-dir',
204         help='The directory to use on the remote platform.')
205
206     # Reproducer options
207     group = parser.add_argument_group('Reproducer options')
208     group.add_argument(
209         '--capture-path',
210         metavar='reproducer path',
211         help='The reproducer capture path')
212     group.add_argument(
213         '--replay-path',
214         metavar='reproducer path',
215         help='The reproducer replay path')
216
217     # Test-suite behaviour
218     group = parser.add_argument_group('Runtime behaviour options')
219     X('-d', 'Suspend the process after launch to wait indefinitely for a debugger to attach')
220     X('-t', 'Turn on tracing of lldb command and other detailed test executions')
221     group.add_argument(
222         '-u',
223         dest='unset_env_varnames',
224         metavar='variable',
225         action='append',
226         help='Specify an environment variable to unset before running the test cases. e.g., -u DYLD_INSERT_LIBRARIES -u MallocScribble')
227     group.add_argument(
228         '--env',
229         dest='set_env_vars',
230         metavar='variable',
231         action='append',
232         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')
233     group.add_argument(
234         '--inferior-env',
235         dest='set_inferior_env_vars',
236         metavar='variable',
237         action='append',
238         help='Specify an environment variable to set to the given value for the inferior.')
239     X('-v', 'Do verbose mode of unittest framework (print out each test case invocation)')
240     group.add_argument(
241         '--enable-crash-dialog',
242         dest='disable_crash_dialog',
243         action='store_false',
244         help='(Windows only) When LLDB crashes, display the Windows crash dialog.')
245     group.set_defaults(disable_crash_dialog=True)
246
247     # Test results support.
248     group = parser.add_argument_group('Test results options')
249     group.add_argument(
250         '--results-file',
251         action='store',
252         help=('Specifies the file where test results will be written '
253               'according to the results-formatter class used'))
254     group.add_argument(
255         '--results-formatter',
256         action='store',
257         help=('Specifies the full package/module/class name used to translate '
258               'test events into some kind of meaningful report, written to '
259               'the designated output results file-like object'))
260     group.add_argument(
261         '--results-formatter-option',
262         '-O',
263         action='append',
264         dest='results_formatter_options',
265         help=('Specify an option to pass to the formatter. '
266               'Use --results-formatter-option="--option1=val1" '
267               'syntax.  Note the "=" is critical, don\'t include whitespace.'))
268
269     # Re-run related arguments
270     group = parser.add_argument_group('Test Re-run Options')
271     group.add_argument(
272         '--rerun-all-issues',
273         action='store_true',
274         help=('Re-run all issues that occurred during the test run '
275               'irrespective of the test method\'s marking as flakey. '
276               'Default behavior is to apply re-runs only to flakey '
277               'tests that generate issues.'))
278
279     # Remove the reference to our helper function
280     del X
281
282     group = parser.add_argument_group('Test directories')
283     group.add_argument(
284         'args',
285         metavar='test-dir',
286         nargs='*',
287         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.')
288
289     return parser