llvm.org GIT mirror llvm / 3b709d5
[docs] Add ReST version of all the man pages. - The POD versions are slated for execution, but are still around until llvm.org machinery is in place. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@156384 91177308-0d34-0410-b5e6-96231b3b80d8 Daniel Dunbar 7 years ago
22 changed file(s) with 3953 addition(s) and 0 deletion(s). Raw diff Collapse all Expand all
0 FileCheck - Flexible pattern matching file verifier
1 ===================================================
2
3
4 SYNOPSIS
5 --------
6
7
8 **FileCheck** *match-filename* [*--check-prefix=XXX*] [*--strict-whitespace*]
9
10
11 DESCRIPTION
12 -----------
13
14
15 **FileCheck** reads two files (one from standard input, and one specified on the
16 command line) and uses one to verify the other. This behavior is particularly
17 useful for the testsuite, which wants to verify that the output of some tool
18 (e.g. llc) contains the expected information (for example, a movsd from esp or
19 whatever is interesting). This is similar to using grep, but it is optimized
20 for matching multiple different inputs in one file in a specific order.
21
22 The *match-filename* file specifies the file that contains the patterns to
23 match. The file to verify is always read from standard input.
24
25
26 OPTIONS
27 -------
28
29
30
31 **-help**
32
33 Print a summary of command line options.
34
35
36
37 **--check-prefix** *prefix*
38
39 FileCheck searches the contents of *match-filename* for patterns to match. By
40 default, these patterns are prefixed with "CHECK:". If you'd like to use a
41 different prefix (e.g. because the same input file is checking multiple
42 different tool or options), the **--check-prefix** argument allows you to specify
43 a specific prefix to match.
44
45
46
47 **--strict-whitespace**
48
49 By default, FileCheck canonicalizes input horizontal whitespace (spaces and
50 tabs) which causes it to ignore these differences (a space will match a tab).
51 The --strict-whitespace argument disables this behavior.
52
53
54
55 **-version**
56
57 Show the version number of this program.
58
59
60
61
62 EXIT STATUS
63 -----------
64
65
66 If **FileCheck** verifies that the file matches the expected contents, it exits
67 with 0. Otherwise, if not, or if an error occurs, it will exit with a non-zero
68 value.
69
70
71 TUTORIAL
72 --------
73
74
75 FileCheck is typically used from LLVM regression tests, being invoked on the RUN
76 line of the test. A simple example of using FileCheck from a RUN line looks
77 like this:
78
79
80 .. code-block:: perl
81
82 ; RUN: llvm-as < %s | llc -march=x86-64 | FileCheck %s
83
84
85 This syntax says to pipe the current file ("%s") into llvm-as, pipe that into
86 llc, then pipe the output of llc into FileCheck. This means that FileCheck will
87 be verifying its standard input (the llc output) against the filename argument
88 specified (the original .ll file specified by "%s"). To see how this works,
89 let's look at the rest of the .ll file (after the RUN line):
90
91
92 .. code-block:: perl
93
94 define void @sub1(i32* %p, i32 %v) {
95 entry:
96 ; CHECK: sub1:
97 ; CHECK: subl
98 %0 = tail call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %p, i32 %v)
99 ret void
100 }
101
102 define void @inc4(i64* %p) {
103 entry:
104 ; CHECK: inc4:
105 ; CHECK: incq
106 %0 = tail call i64 @llvm.atomic.load.add.i64.p0i64(i64* %p, i64 1)
107 ret void
108 }
109
110
111 Here you can see some "CHECK:" lines specified in comments. Now you can see
112 how the file is piped into llvm-as, then llc, and the machine code output is
113 what we are verifying. FileCheck checks the machine code output to verify that
114 it matches what the "CHECK:" lines specify.
115
116 The syntax of the CHECK: lines is very simple: they are fixed strings that
117 must occur in order. FileCheck defaults to ignoring horizontal whitespace
118 differences (e.g. a space is allowed to match a tab) but otherwise, the contents
119 of the CHECK: line is required to match some thing in the test file exactly.
120
121 One nice thing about FileCheck (compared to grep) is that it allows merging
122 test cases together into logical groups. For example, because the test above
123 is checking for the "sub1:" and "inc4:" labels, it will not match unless there
124 is a "subl" in between those labels. If it existed somewhere else in the file,
125 that would not count: "grep subl" matches if subl exists anywhere in the
126 file.
127
128 The FileCheck -check-prefix option
129 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
130
131
132 The FileCheck -check-prefix option allows multiple test configurations to be
133 driven from one .ll file. This is useful in many circumstances, for example,
134 testing different architectural variants with llc. Here's a simple example:
135
136
137 .. code-block:: perl
138
139 ; RUN: llvm-as < %s | llc -mtriple=i686-apple-darwin9 -mattr=sse41 \
140 ; RUN: | FileCheck %s -check-prefix=X32>
141 ; RUN: llvm-as < %s | llc -mtriple=x86_64-apple-darwin9 -mattr=sse41 \
142 ; RUN: | FileCheck %s -check-prefix=X64>
143
144 define <4 x i32> @pinsrd_1(i32 %s, <4 x i32> %tmp) nounwind {
145 %tmp1 = insertelement <4 x i32>; %tmp, i32 %s, i32 1
146 ret <4 x i32> %tmp1
147 ; X32: pinsrd_1:
148 ; X32: pinsrd $1, 4(%esp), %xmm0
149
150 ; X64: pinsrd_1:
151 ; X64: pinsrd $1, %edi, %xmm0
152 }
153
154
155 In this case, we're testing that we get the expected code generation with
156 both 32-bit and 64-bit code generation.
157
158
159 The "CHECK-NEXT:" directive
160 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
161
162
163 Sometimes you want to match lines and would like to verify that matches
164 happen on exactly consecutive lines with no other lines in between them. In
165 this case, you can use CHECK: and CHECK-NEXT: directives to specify this. If
166 you specified a custom check prefix, just use "-NEXT:". For
167 example, something like this works as you'd expect:
168
169
170 .. code-block:: perl
171
172 define void @t2(<2 x double>* %r, <2 x double>* %A, double %B) {
173 %tmp3 = load <2 x double>* %A, align 16
174 %tmp7 = insertelement <2 x double> undef, double %B, i32 0
175 %tmp9 = shufflevector <2 x double> %tmp3,
176 <2 x double> %tmp7,
177 <2 x i32> < i32 0, i32 2 >
178 store <2 x double> %tmp9, <2 x double>* %r, align 16
179 ret void
180
181 ; CHECK: t2:
182 ; CHECK: movl 8(%esp), %eax
183 ; CHECK-NEXT: movapd (%eax), %xmm0
184 ; CHECK-NEXT: movhpd 12(%esp), %xmm0
185 ; CHECK-NEXT: movl 4(%esp), %eax
186 ; CHECK-NEXT: movapd %xmm0, (%eax)
187 ; CHECK-NEXT: ret
188 }
189
190
191 CHECK-NEXT: directives reject the input unless there is exactly one newline
192 between it an the previous directive. A CHECK-NEXT cannot be the first
193 directive in a file.
194
195
196 The "CHECK-NOT:" directive
197 ~~~~~~~~~~~~~~~~~~~~~~~~~~
198
199
200 The CHECK-NOT: directive is used to verify that a string doesn't occur
201 between two matches (or before the first match, or after the last match). For
202 example, to verify that a load is removed by a transformation, a test like this
203 can be used:
204
205
206 .. code-block:: perl
207
208 define i8 @coerce_offset0(i32 %V, i32* %P) {
209 store i32 %V, i32* %P
210
211 %P2 = bitcast i32* %P to i8*
212 %P3 = getelementptr i8* %P2, i32 2
213
214 %A = load i8* %P3
215 ret i8 %A
216 ; CHECK: @coerce_offset0
217 ; CHECK-NOT: load
218 ; CHECK: ret i8
219 }
220
221
222
223 FileCheck Pattern Matching Syntax
224 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
225
226
227 The CHECK: and CHECK-NOT: directives both take a pattern to match. For most
228 uses of FileCheck, fixed string matching is perfectly sufficient. For some
229 things, a more flexible form of matching is desired. To support this, FileCheck
230 allows you to specify regular expressions in matching strings, surrounded by
231 double braces: **{{yourregex}}**. Because we want to use fixed string
232 matching for a majority of what we do, FileCheck has been designed to support
233 mixing and matching fixed string matching with regular expressions. This allows
234 you to write things like this:
235
236
237 .. code-block:: perl
238
239 ; CHECK: movhpd {{[0-9]+}}(%esp), {{%xmm[0-7]}}
240
241
242 In this case, any offset from the ESP register will be allowed, and any xmm
243 register will be allowed.
244
245 Because regular expressions are enclosed with double braces, they are
246 visually distinct, and you don't need to use escape characters within the double
247 braces like you would in C. In the rare case that you want to match double
248 braces explicitly from the input, you can use something ugly like
249 **{{[{][{]}}** as your pattern.
250
251
252 FileCheck Variables
253 ~~~~~~~~~~~~~~~~~~~
254
255
256 It is often useful to match a pattern and then verify that it occurs again
257 later in the file. For codegen tests, this can be useful to allow any register,
258 but verify that that register is used consistently later. To do this, FileCheck
259 allows named variables to be defined and substituted into patterns. Here is a
260 simple example:
261
262
263 .. code-block:: perl
264
265 ; CHECK: test5:
266 ; CHECK: notw [[REGISTER:%[a-z]+]]
267 ; CHECK: andw {{.*}}[REGISTER]]
268
269
270 The first check line matches a regex (**%[a-z]+**) and captures it into
271 the variable "REGISTER". The second line verifies that whatever is in REGISTER
272 occurs later in the file after an "andw". FileCheck variable references are
273 always contained in **[[ ]]** pairs, are named, and their names can be
274 name, then it is a definition of the variable, if not, it is a use.
275
276 FileCheck variables can be defined multiple times, and uses always get the
277 latest value. Note that variables are all read at the start of a "CHECK" line
278 and are all defined at the end. This means that if you have something like
279 "**CHECK: [[XYZ:.\\*]]x[[XYZ]]**", the check line will read the previous
280 value of the XYZ variable and define a new one after the match is performed. If
281 you need to do something like this you can probably take advantage of the fact
282 that FileCheck is not actually line-oriented when it matches, this allows you to
283 define two separate CHECK lines that match on the same line.
0 bugpoint - automatic test case reduction tool
1 =============================================
2
3
4 SYNOPSIS
5 --------
6
7
8 **bugpoint** [*options*] [*input LLVM ll/bc files*] [*LLVM passes*] **--args**
9 *program arguments*
10
11
12 DESCRIPTION
13 -----------
14
15
16 **bugpoint** narrows down the source of problems in LLVM tools and passes. It
17 can be used to debug three types of failures: optimizer crashes, miscompilations
18 by optimizers, or bad native code generation (including problems in the static
19 and JIT compilers). It aims to reduce large test cases to small, useful ones.
20 For more information on the design and inner workings of **bugpoint**, as well as
21 advice for using bugpoint, see *llvm/docs/Bugpoint.html* in the LLVM
22 distribution.
23
24
25 OPTIONS
26 -------
27
28
29
30 **--additional-so** *library*
31
32 Load the dynamic shared object *library* into the test program whenever it is
33 run. This is useful if you are debugging programs which depend on non-LLVM
34 libraries (such as the X or curses libraries) to run.
35
36
37
38 **--append-exit-code**\ =\ *{true,false}*
39
40 Append the test programs exit code to the output file so that a change in exit
41 code is considered a test failure. Defaults to false.
42
43
44
45 **--args** *program args*
46
47 Pass all arguments specified after -args to the test program whenever it runs.
48 Note that if any of the *program args* start with a '-', you should use:
49
50
51 .. code-block:: perl
52
53 bugpoint [bugpoint args] --args -- [program args]
54
55
56 The "--" right after the **--args** option tells **bugpoint** to consider any
57 options starting with ``-`` to be part of the **--args** option, not as options to
58 **bugpoint** itself.
59
60
61
62 **--tool-args** *tool args*
63
64 Pass all arguments specified after --tool-args to the LLVM tool under test
65 (**llc**, **lli**, etc.) whenever it runs. You should use this option in the
66 following way:
67
68
69 .. code-block:: perl
70
71 bugpoint [bugpoint args] --tool-args -- [tool args]
72
73
74 The "--" right after the **--tool-args** option tells **bugpoint** to consider any
75 options starting with ``-`` to be part of the **--tool-args** option, not as
76 options to **bugpoint** itself. (See **--args**, above.)
77
78
79
80 **--safe-tool-args** *tool args*
81
82 Pass all arguments specified after **--safe-tool-args** to the "safe" execution
83 tool.
84
85
86
87 **--gcc-tool-args** *gcc tool args*
88
89 Pass all arguments specified after **--gcc-tool-args** to the invocation of
90 **gcc**.
91
92
93
94 **--opt-args** *opt args*
95
96 Pass all arguments specified after **--opt-args** to the invocation of **opt**.
97
98
99
100 **--disable-{dce,simplifycfg}**
101
102 Do not run the specified passes to clean up and reduce the size of the test
103 program. By default, **bugpoint** uses these passes internally when attempting to
104 reduce test programs. If you're trying to find a bug in one of these passes,
105 **bugpoint** may crash.
106
107
108
109 **--enable-valgrind**
110
111 Use valgrind to find faults in the optimization phase. This will allow
112 bugpoint to find otherwise asymptomatic problems caused by memory
113 mis-management.
114
115
116
117 **-find-bugs**
118
119 Continually randomize the specified passes and run them on the test program
120 until a bug is found or the user kills **bugpoint**.
121
122
123
124 **-help**
125
126 Print a summary of command line options.
127
128
129
130 **--input** *filename*
131
132 Open *filename* and redirect the standard input of the test program, whenever
133 it runs, to come from that file.
134
135
136
137 **--load** *plugin*
138
139 Load the dynamic object *plugin* into **bugpoint** itself. This object should
140 register new optimization passes. Once loaded, the object will add new command
141 line options to enable various optimizations. To see the new complete list of
142 optimizations, use the **-help** and **--load** options together; for example:
143
144
145 .. code-block:: perl
146
147 bugpoint --load myNewPass.so -help
148
149
150
151
152 **--mlimit** *megabytes*
153
154 Specifies an upper limit on memory usage of the optimization and codegen. Set
155 to zero to disable the limit.
156
157
158
159 **--output** *filename*
160
161 Whenever the test program produces output on its standard output stream, it
162 should match the contents of *filename* (the "reference output"). If you
163 do not use this option, **bugpoint** will attempt to generate a reference output
164 by compiling the program with the "safe" backend and running it.
165
166
167
168 **--profile-info-file** *filename*
169
170 Profile file loaded by **--profile-loader**.
171
172
173
174 **--run-{int,jit,llc,custom}**
175
176 Whenever the test program is compiled, **bugpoint** should generate code for it
177 using the specified code generator. These options allow you to choose the
178 interpreter, the JIT compiler, the static native code compiler, or a
179 custom command (see **--exec-command**) respectively.
180
181
182
183 **--safe-{llc,custom}**
184
185 When debugging a code generator, **bugpoint** should use the specified code
186 generator as the "safe" code generator. This is a known-good code generator
187 used to generate the "reference output" if it has not been provided, and to
188 compile portions of the program that as they are excluded from the testcase.
189 These options allow you to choose the
190 static native code compiler, or a custom command, (see **--exec-command**)
191 respectively. The interpreter and the JIT backends cannot currently
192 be used as the "safe" backends.
193
194
195
196 **--exec-command** *command*
197
198 This option defines the command to use with the **--run-custom** and
199 **--safe-custom** options to execute the bitcode testcase. This can
200 be useful for cross-compilation.
201
202
203
204 **--compile-command** *command*
205
206 This option defines the command to use with the **--compile-custom**
207 option to compile the bitcode testcase. This can be useful for
208 testing compiler output without running any link or execute stages. To
209 generate a reduced unit test, you may add CHECK directives to the
210 testcase and pass the name of an executable compile-command script in this form:
211
212
213 .. code-block:: perl
214
215 #!/bin/sh
216 llc "$@"
217 not FileCheck [bugpoint input file].ll < bugpoint-test-program.s
218
219
220 This script will "fail" as long as FileCheck passes. So the result
221 will be the minimum bitcode that passes FileCheck.
222
223
224
225 **--safe-path** *path*
226
227 This option defines the path to the command to execute with the
228 **--safe-{int,jit,llc,custom}**
229 option.
230
231
232
233
234 EXIT STATUS
235 -----------
236
237
238 If **bugpoint** succeeds in finding a problem, it will exit with 0. Otherwise,
239 if an error occurs, it will exit with a non-zero value.
240
241
242 SEE ALSO
243 --------
244
245
246 opt|opt
0 .. _commands:
1
2 LLVM Command Guide
3 ------------------
4
5 The following documents are command descriptions for all of the LLVM tools.
6 These pages describe how to use the LLVM commands and what their options are.
7 Note that these pages do not describe all of the options available for all
8 tools. To get a complete listing, pass the ``--help`` (general options) or
9 ``--help-hidden`` (general and debugging options) arguments to the tool you are
10 interested in.
11
12 Basic Commands
13 ~~~~~~~~~~~~~~
14
15 .. toctree::
16 :maxdepth: 1
17
18 llvm-as
19 llvm-dis
20 opt
21 llc
22 lli
23 llvm-link
24 llvm-ar
25 llvm-ranlib
26 llvm-nm
27 llvm-prof
28 llvm-config
29 llvm-diff
30 llvm-cov
31 llvm-stress
32
33 Debugging Tools
34 ~~~~~~~~~~~~~~~
35
36 .. toctree::
37 :maxdepth: 1
38
39 bugpoint
40 llvm-extract
41 llvm-bcanalyzer
42
43 Developer Tools
44 ~~~~~~~~~~~~~~~
45
46 .. toctree::
47 :maxdepth: 1
48
49 FileCheck
50 tblgen
51 lit
52 llvm-build
0 lit - LLVM Integrated Tester
1 ============================
2
3
4 SYNOPSIS
5 --------
6
7
8 **lit** [*options*] [*tests*]
9
10
11 DESCRIPTION
12 -----------
13
14
15 **lit** is a portable tool for executing LLVM and Clang style test suites,
16 summarizing their results, and providing indication of failures. **lit** is
17 designed to be a lightweight testing tool with as simple a user interface as
18 possible.
19
20 **lit** should be run with one or more *tests* to run specified on the command
21 line. Tests can be either individual test files or directories to search for
22 tests (see "TEST DISCOVERY").
23
24 Each specified test will be executed (potentially in parallel) and once all
25 tests have been run **lit** will print summary information on the number of tests
26 which passed or failed (see "TEST STATUS RESULTS"). The **lit** program will
27 execute with a non-zero exit code if any tests fail.
28
29 By default **lit** will use a succinct progress display and will only print
30 summary information for test failures. See "OUTPUT OPTIONS" for options
31 controlling the **lit** progress display and output.
32
33 **lit** also includes a number of options for controlling how tests are executed
34 (specific features may depend on the particular test format). See "EXECUTION
35 OPTIONS" for more information.
36
37 Finally, **lit** also supports additional options for only running a subset of
38 the options specified on the command line, see "SELECTION OPTIONS" for
39 more information.
40
41 Users interested in the **lit** architecture or designing a **lit** testing
42 implementation should see "LIT INFRASTRUCTURE"
43
44
45 GENERAL OPTIONS
46 ---------------
47
48
49
50 **-h**, **--help**
51
52 Show the **lit** help message.
53
54
55
56 **-j** *N*, **--threads**\ =\ *N*
57
58 Run *N* tests in parallel. By default, this is automatically chosen to match
59 the number of detected available CPUs.
60
61
62
63 **--config-prefix**\ =\ *NAME*
64
65 Search for *NAME.cfg* and *NAME.site.cfg* when searching for test suites,
66 instead of *lit.cfg* and *lit.site.cfg*.
67
68
69
70 **--param** *NAME*, **--param** *NAME*\ =\ *VALUE*
71
72 Add a user defined parameter *NAME* with the given *VALUE* (or the empty
73 string if not given). The meaning and use of these parameters is test suite
74 dependent.
75
76
77
78
79 OUTPUT OPTIONS
80 --------------
81
82
83
84 **-q**, **--quiet**
85
86 Suppress any output except for test failures.
87
88
89
90 **-s**, **--succinct**
91
92 Show less output, for example don't show information on tests that pass.
93
94
95
96 **-v**, **--verbose**
97
98 Show more information on test failures, for example the entire test output
99 instead of just the test result.
100
101
102
103 **--no-progress-bar**
104
105 Do not use curses based progress bar.
106
107
108
109
110 EXECUTION OPTIONS
111 -----------------
112
113
114
115 **--path**\ =\ *PATH*
116
117 Specify an addition *PATH* to use when searching for executables in tests.
118
119
120
121 **--vg**
122
123 Run individual tests under valgrind (using the memcheck tool). The
124 *--error-exitcode* argument for valgrind is used so that valgrind failures will
125 cause the program to exit with a non-zero status.
126
127
128
129 **--vg-arg**\ =\ *ARG*
130
131 When *--vg* is used, specify an additional argument to pass to valgrind itself.
132
133
134
135 **--time-tests**
136
137 Track the wall time individual tests take to execute and includes the results in
138 the summary output. This is useful for determining which tests in a test suite
139 take the most time to execute. Note that this option is most useful with *-j
140 1*.
141
142
143
144
145 SELECTION OPTIONS
146 -----------------
147
148
149
150 **--max-tests**\ =\ *N*
151
152 Run at most *N* tests and then terminate.
153
154
155
156 **--max-time**\ =\ *N*
157
158 Spend at most *N* seconds (approximately) running tests and then terminate.
159
160
161
162 **--shuffle**
163
164 Run the tests in a random order.
165
166
167
168
169 ADDITIONAL OPTIONS
170 ------------------
171
172
173
174 **--debug**
175
176 Run **lit** in debug mode, for debugging configuration issues and **lit** itself.
177
178
179
180 **--show-suites**
181
182 List the discovered test suites as part of the standard output.
183
184
185
186 **--no-tcl-as-sh**
187
188 Run Tcl scripts internally (instead of converting to shell scripts).
189
190
191
192 **--repeat**\ =\ *N*
193
194 Run each test *N* times. Currently this is primarily useful for timing tests,
195 other results are not collated in any reasonable fashion.
196
197
198
199
200 EXIT STATUS
201 -----------
202
203
204 **lit** will exit with an exit code of 1 if there are any FAIL or XPASS
205 results. Otherwise, it will exit with the status 0. Other exit codes are used
206 for non-test related failures (for example a user error or an internal program
207 error).
208
209
210 TEST DISCOVERY
211 --------------
212
213
214 The inputs passed to **lit** can be either individual tests, or entire
215 directories or hierarchies of tests to run. When **lit** starts up, the first
216 thing it does is convert the inputs into a complete list of tests to run as part
217 of *test discovery*.
218
219 In the **lit** model, every test must exist inside some *test suite*. **lit**
220 resolves the inputs specified on the command line to test suites by searching
221 upwards from the input path until it finds a *lit.cfg* or *lit.site.cfg*
222 file. These files serve as both a marker of test suites and as configuration
223 files which **lit** loads in order to understand how to find and run the tests
224 inside the test suite.
225
226 Once **lit** has mapped the inputs into test suites it traverses the list of
227 inputs adding tests for individual files and recursively searching for tests in
228 directories.
229
230 This behavior makes it easy to specify a subset of tests to run, while still
231 allowing the test suite configuration to control exactly how tests are
232 interpreted. In addition, **lit** always identifies tests by the test suite they
233 are in, and their relative path inside the test suite. For appropriately
234 configured projects, this allows **lit** to provide convenient and flexible
235 support for out-of-tree builds.
236
237
238 TEST STATUS RESULTS
239 -------------------
240
241
242 Each test ultimately produces one of the following six results:
243
244
245 **PASS**
246
247 The test succeeded.
248
249
250
251 **XFAIL**
252
253 The test failed, but that is expected. This is used for test formats which allow
254 specifying that a test does not currently work, but wish to leave it in the test
255 suite.
256
257
258
259 **XPASS**
260
261 The test succeeded, but it was expected to fail. This is used for tests which
262 were specified as expected to fail, but are now succeeding (generally because
263 the feature they test was broken and has been fixed).
264
265
266
267 **FAIL**
268
269 The test failed.
270
271
272
273 **UNRESOLVED**
274
275 The test result could not be determined. For example, this occurs when the test
276 could not be run, the test itself is invalid, or the test was interrupted.
277
278
279
280 **UNSUPPORTED**
281
282 The test is not supported in this environment. This is used by test formats
283 which can report unsupported tests.
284
285
286
287 Depending on the test format tests may produce additional information about
288 their status (generally only for failures). See the Output|"OUTPUT OPTIONS"
289 section for more information.
290
291
292 LIT INFRASTRUCTURE
293 ------------------
294
295
296 This section describes the **lit** testing architecture for users interested in
297 creating a new **lit** testing implementation, or extending an existing one.
298
299 **lit** proper is primarily an infrastructure for discovering and running
300 arbitrary tests, and to expose a single convenient interface to these
301 tests. **lit** itself doesn't know how to run tests, rather this logic is
302 defined by *test suites*.
303
304 TEST SUITES
305 ~~~~~~~~~~~
306
307
308 As described in "TEST DISCOVERY", tests are always located inside a *test
309 suite*. Test suites serve to define the format of the tests they contain, the
310 logic for finding those tests, and any additional information to run the tests.
311
312 **lit** identifies test suites as directories containing *lit.cfg* or
313 *lit.site.cfg* files (see also **--config-prefix**). Test suites are initially
314 discovered by recursively searching up the directory hierarchy for all the input
315 files passed on the command line. You can use **--show-suites** to display the
316 discovered test suites at startup.
317
318 Once a test suite is discovered, its config file is loaded. Config files
319 themselves are Python modules which will be executed. When the config file is
320 executed, two important global variables are predefined:
321
322
323 **lit**
324
325 The global **lit** configuration object (a *LitConfig* instance), which defines
326 the builtin test formats, global configuration parameters, and other helper
327 routines for implementing test configurations.
328
329
330
331 **config**
332
333 This is the config object (a *TestingConfig* instance) for the test suite,
334 which the config file is expected to populate. The following variables are also
335 available on the *config* object, some of which must be set by the config and
336 others are optional or predefined:
337
338 **name** *[required]* The name of the test suite, for use in reports and
339 diagnostics.
340
341 **test_format** *[required]* The test format object which will be used to
342 discover and run tests in the test suite. Generally this will be a builtin test
343 format available from the *lit.formats* module.
344
345 **test_src_root** The filesystem path to the test suite root. For out-of-dir
346 builds this is the directory that will be scanned for tests.
347
348 **test_exec_root** For out-of-dir builds, the path to the test suite root inside
349 the object directory. This is where tests will be run and temporary output files
350 placed.
351
352 **environment** A dictionary representing the environment to use when executing
353 tests in the suite.
354
355 **suffixes** For **lit** test formats which scan directories for tests, this
356 variable is a list of suffixes to identify test files. Used by: *ShTest*,
357 *TclTest*.
358
359 **substitutions** For **lit** test formats which substitute variables into a test
360 script, the list of substitutions to perform. Used by: *ShTest*, *TclTest*.
361
362 **unsupported** Mark an unsupported directory, all tests within it will be
363 reported as unsupported. Used by: *ShTest*, *TclTest*.
364
365 **parent** The parent configuration, this is the config object for the directory
366 containing the test suite, or None.
367
368 **root** The root configuration. This is the top-most **lit** configuration in
369 the project.
370
371 **on_clone** The config is actually cloned for every subdirectory inside a test
372 suite, to allow local configuration on a per-directory basis. The *on_clone*
373 variable can be set to a Python function which will be called whenever a
374 configuration is cloned (for a subdirectory). The function should takes three
375 arguments: (1) the parent configuration, (2) the new configuration (which the
376 *on_clone* function will generally modify), and (3) the test path to the new
377 directory being scanned.
378
379
380
381
382 TEST DISCOVERY
383 ~~~~~~~~~~~~~~
384
385
386 Once test suites are located, **lit** recursively traverses the source directory
387 (following *test_src_root*) looking for tests. When **lit** enters a
388 sub-directory, it first checks to see if a nested test suite is defined in that
389 directory. If so, it loads that test suite recursively, otherwise it
390 instantiates a local test config for the directory (see "LOCAL CONFIGURATION
391 FILES").
392
393 Tests are identified by the test suite they are contained within, and the
394 relative path inside that suite. Note that the relative path may not refer to an
395 actual file on disk; some test formats (such as *GoogleTest*) define "virtual
396 tests" which have a path that contains both the path to the actual test file and
397 a subpath to identify the virtual test.
398
399
400 LOCAL CONFIGURATION FILES
401 ~~~~~~~~~~~~~~~~~~~~~~~~~
402
403
404 When **lit** loads a subdirectory in a test suite, it instantiates a local test
405 configuration by cloning the configuration for the parent direction -- the root
406 of this configuration chain will always be a test suite. Once the test
407 configuration is cloned **lit** checks for a *lit.local.cfg* file in the
408 subdirectory. If present, this file will be loaded and can be used to specialize
409 the configuration for each individual directory. This facility can be used to
410 define subdirectories of optional tests, or to change other configuration
411 parameters -- for example, to change the test format, or the suffixes which
412 identify test files.
413
414
415 TEST RUN OUTPUT FORMAT
416 ~~~~~~~~~~~~~~~~~~~~~~
417
418
419 The b output for a test run conforms to the following schema, in both short
420 and verbose modes (although in short mode no PASS lines will be shown). This
421 schema has been chosen to be relatively easy to reliably parse by a machine (for
422 example in buildbot log scraping), and for other tools to generate.
423
424 Each test result is expected to appear on a line that matches:
425
426 : ()
427
428 where is a standard test result such as PASS, FAIL, XFAIL, XPASS,
429 UNRESOLVED, or UNSUPPORTED. The performance result codes of IMPROVED and
430 REGRESSED are also allowed.
431
432 The field can consist of an arbitrary string containing no newline.
433
434 The field can be used to report progress information such as
435 (1/300) or can be empty, but even when empty the parentheses are required.
436
437 Each test result may include additional (multiline) log information in the
438 following format.
439
440 TEST '()'
441 ... log message ...
442
443
444 where should be the name of a preceeding reported test,
445 delineator> is a string of '\*' characters *at least* four characters long (the
446 recommended length is 20), and is an arbitrary (unparsed)
447 string.
448
449 The following is an example of a test run output which consists of four tests A,
450 B, C, and D, and a log message for the failing test C::
451
452 PASS: A (1 of 4)
453 PASS: B (2 of 4)
454 FAIL: C (3 of 4)
455 \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* TEST 'C' FAILED \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*
456 Test 'C' failed as a result of exit code 1.
457 \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*
458 PASS: D (4 of 4)
459
460
461 LIT EXAMPLE TESTS
462 ~~~~~~~~~~~~~~~~~
463
464
465 The **lit** distribution contains several example implementations of test suites
466 in the *ExampleTests* directory.
467
468
469 SEE ALSO
470 --------
471
472
473 valgrind(1)
0 llc - LLVM static compiler
1 ==========================
2
3
4 SYNOPSIS
5 --------
6
7
8 **llc** [*options*] [*filename*]
9
10
11 DESCRIPTION
12 -----------
13
14
15 The **llc** command compiles LLVM source inputs into assembly language for a
16 specified architecture. The assembly language output can then be passed through
17 a native assembler and linker to generate a native executable.
18
19 The choice of architecture for the output assembly code is automatically
20 determined from the input file, unless the **-march** option is used to override
21 the default.
22
23
24 OPTIONS
25 -------
26
27
28 If *filename* is - or omitted, **llc** reads from standard input. Otherwise, it
29 will from *filename*. Inputs can be in either the LLVM assembly language
30 format (.ll) or the LLVM bitcode format (.bc).
31
32 If the **-o** option is omitted, then **llc** will send its output to standard
33 output if the input is from standard input. If the **-o** option specifies -,
34 then the output will also be sent to standard output.
35
36 If no **-o** option is specified and an input file other than - is specified,
37 then **llc** creates the output filename by taking the input filename,
38 removing any existing *.bc* extension, and adding a *.s* suffix.
39
40 Other **llc** options are as follows:
41
42 End-user Options
43 ~~~~~~~~~~~~~~~~
44
45
46
47 **-help**
48
49 Print a summary of command line options.
50
51
52
53 **-O**\ =\ *uint*
54
55 Generate code at different optimization levels. These correspond to the *-O0*,
56 *-O1*, *-O2*, and *-O3* optimization levels used by **llvm-gcc** and
57 **clang**.
58
59
60
61 **-mtriple**\ =\ *target triple*
62
63 Override the target triple specified in the input file with the specified
64 string.
65
66
67
68 **-march**\ =\ *arch*
69
70 Specify the architecture for which to generate assembly, overriding the target
71 encoded in the input file. See the output of **llc -help** for a list of
72 valid architectures. By default this is inferred from the target triple or
73 autodetected to the current architecture.
74
75
76
77 **-mcpu**\ =\ *cpuname*
78
79 Specify a specific chip in the current architecture to generate code for.
80 By default this is inferred from the target triple and autodetected to
81 the current architecture. For a list of available CPUs, use:
82 **llvm-as < /dev/null | llc -march=xyz -mcpu=help**
83
84
85
86 **-mattr**\ =\ *a1,+a2,-a3,...*
87
88 Override or control specific attributes of the target, such as whether SIMD
89 operations are enabled or not. The default set of attributes is set by the
90 current CPU. For a list of available attributes, use:
91 **llvm-as < /dev/null | llc -march=xyz -mattr=help**
92
93
94
95 **--disable-fp-elim**
96
97 Disable frame pointer elimination optimization.
98
99
100
101 **--disable-excess-fp-precision**
102
103 Disable optimizations that may produce excess precision for floating point.
104 Note that this option can dramatically slow down code on some systems
105 (e.g. X86).
106
107
108
109 **--enable-no-infs-fp-math**
110
111 Enable optimizations that assume no Inf values.
112
113
114
115 **--enable-no-nans-fp-math**
116
117 Enable optimizations that assume no NAN values.
118
119
120
121 **--enable-unsafe-fp-math**
122
123 Enable optimizations that make unsafe assumptions about IEEE math (e.g. that
124 addition is associative) or may not work for all input ranges. These
125 optimizations allow the code generator to make use of some instructions which
126 would otherwise not be usable (such as fsin on X86).
127
128
129
130 **--enable-correct-eh-support**
131
132 Instruct the **lowerinvoke** pass to insert code for correct exception handling
133 support. This is expensive and is by default omitted for efficiency.
134
135
136
137 **--stats**
138
139 Print statistics recorded by code-generation passes.
140
141
142
143 **--time-passes**
144
145 Record the amount of time needed for each pass and print a report to standard
146 error.
147
148
149
150 **--load**\ =\ *dso_path*
151
152 Dynamically load *dso_path* (a path to a dynamically shared object) that
153 implements an LLVM target. This will permit the target name to be used with the
154 **-march** option so that code can be generated for that target.
155
156
157
158
159 Tuning/Configuration Options
160 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
161
162
163
164 **--print-machineinstrs**
165
166 Print generated machine code between compilation phases (useful for debugging).
167
168
169
170 **--regalloc**\ =\ *allocator*
171
172 Specify the register allocator to use. The default *allocator* is *local*.
173 Valid register allocators are:
174
175
176 *simple*
177
178 Very simple "always spill" register allocator
179
180
181
182 *local*
183
184 Local register allocator
185
186
187
188 *linearscan*
189
190 Linear scan global register allocator
191
192
193
194 *iterativescan*
195
196 Iterative scan global register allocator
197
198
199
200
201
202 **--spiller**\ =\ *spiller*
203
204 Specify the spiller to use for register allocators that support it. Currently
205 this option is used only by the linear scan register allocator. The default
206 *spiller* is *local*. Valid spillers are:
207
208
209 *simple*
210
211 Simple spiller
212
213
214
215 *local*
216
217 Local spiller
218
219
220
221
222
223
224 Intel IA-32-specific Options
225 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
226
227
228
229 **--x86-asm-syntax=att|intel**
230
231 Specify whether to emit assembly code in AT&T syntax (the default) or intel
232 syntax.
233
234
235
236
237
238 EXIT STATUS
239 -----------
240
241
242 If **llc** succeeds, it will exit with 0. Otherwise, if an error occurs,
243 it will exit with a non-zero value.
244
245
246 SEE ALSO
247 --------
248
249
250 lli|lli
0 lli - directly execute programs from LLVM bitcode
1 =================================================
2
3
4 SYNOPSIS
5 --------
6
7
8 **lli** [*options*] [*filename*] [*program args*]
9
10
11 DESCRIPTION
12 -----------
13
14
15 **lli** directly executes programs in LLVM bitcode format. It takes a program
16 in LLVM bitcode format and executes it using a just-in-time compiler, if one is
17 available for the current architecture, or an interpreter. **lli** takes all of
18 the same code generator options as llc|llc, but they are only effective when
19 **lli** is using the just-in-time compiler.
20
21 If *filename* is not specified, then **lli** reads the LLVM bitcode for the
22 program from standard input.
23
24 The optional *args* specified on the command line are passed to the program as
25 arguments.
26
27
28 GENERAL OPTIONS
29 ---------------
30
31
32
33 **-fake-argv0**\ =\ *executable*
34
35 Override the ``argv[0]`` value passed into the executing program.
36
37
38
39 **-force-interpreter**\ =\ *{false,true}*
40
41 If set to true, use the interpreter even if a just-in-time compiler is available
42 for this architecture. Defaults to false.
43
44
45
46 **-help**
47
48 Print a summary of command line options.
49
50
51
52 **-load**\ =\ *puginfilename*
53
54 Causes **lli** to load the plugin (shared object) named *pluginfilename* and use
55 it for optimization.
56
57
58
59 **-stats**
60
61 Print statistics from the code-generation passes. This is only meaningful for
62 the just-in-time compiler, at present.
63
64
65
66 **-time-passes**
67
68 Record the amount of time needed for each code-generation pass and print it to
69 standard error.
70
71
72
73 **-version**
74
75 Print out the version of **lli** and exit without doing anything else.
76
77
78
79
80 TARGET OPTIONS
81 --------------
82
83
84
85 **-mtriple**\ =\ *target triple*
86
87 Override the target triple specified in the input bitcode file with the
88 specified string. This may result in a crash if you pick an
89 architecture which is not compatible with the current system.
90
91
92
93 **-march**\ =\ *arch*
94
95 Specify the architecture for which to generate assembly, overriding the target
96 encoded in the bitcode file. See the output of **llc -help** for a list of
97 valid architectures. By default this is inferred from the target triple or
98 autodetected to the current architecture.
99
100
101
102 **-mcpu**\ =\ *cpuname*
103
104 Specify a specific chip in the current architecture to generate code for.
105 By default this is inferred from the target triple and autodetected to
106 the current architecture. For a list of available CPUs, use:
107 **llvm-as < /dev/null | llc -march=xyz -mcpu=help**
108
109
110
111 **-mattr**\ =\ *a1,+a2,-a3,...*
112
113 Override or control specific attributes of the target, such as whether SIMD
114 operations are enabled or not. The default set of attributes is set by the
115 current CPU. For a list of available attributes, use:
116 **llvm-as < /dev/null | llc -march=xyz -mattr=help**
117
118
119
120
121 FLOATING POINT OPTIONS
122 ----------------------
123
124
125
126 **-disable-excess-fp-precision**
127
128 Disable optimizations that may increase floating point precision.
129
130
131
132 **-enable-no-infs-fp-math**
133
134 Enable optimizations that assume no Inf values.
135
136
137
138 **-enable-no-nans-fp-math**
139
140 Enable optimizations that assume no NAN values.
141
142
143
144 **-enable-unsafe-fp-math**
145
146 Causes **lli** to enable optimizations that may decrease floating point
147 precision.
148
149
150
151 **-soft-float**
152
153 Causes **lli** to generate software floating point library calls instead of
154 equivalent hardware instructions.
155
156
157
158
159 CODE GENERATION OPTIONS
160 -----------------------
161
162
163
164 **-code-model**\ =\ *model*
165
166 Choose the code model from:
167
168
169 .. code-block:: perl
170
171 default: Target default code model
172 small: Small code model
173 kernel: Kernel code model
174 medium: Medium code model
175 large: Large code model
176
177
178
179
180 **-disable-post-RA-scheduler**
181
182 Disable scheduling after register allocation.
183
184
185
186 **-disable-spill-fusing**
187
188 Disable fusing of spill code into instructions.
189
190
191
192 **-enable-correct-eh-support**
193
194 Make the -lowerinvoke pass insert expensive, but correct, EH code.
195
196
197
198 **-jit-enable-eh**
199
200 Exception handling should be enabled in the just-in-time compiler.
201
202
203
204 **-join-liveintervals**
205
206 Coalesce copies (default=true).
207
208
209
210 **-nozero-initialized-in-bss** Don't place zero-initialized symbols into the BSS section.
211
212
213
214 **-pre-RA-sched**\ =\ *scheduler*
215
216 Instruction schedulers available (before register allocation):
217
218
219 .. code-block:: perl
220
221 =default: Best scheduler for the target
222 =none: No scheduling: breadth first sequencing
223 =simple: Simple two pass scheduling: minimize critical path and maximize processor utilization
224 =simple-noitin: Simple two pass scheduling: Same as simple except using generic latency
225 =list-burr: Bottom-up register reduction list scheduling
226 =list-tdrr: Top-down register reduction list scheduling
227 =list-td: Top-down list scheduler -print-machineinstrs - Print generated machine code
228
229
230
231
232 **-regalloc**\ =\ *allocator*
233
234 Register allocator to use (default=linearscan)
235
236
237 .. code-block:: perl
238
239 =bigblock: Big-block register allocator
240 =linearscan: linear scan register allocator =local - local register allocator
241 =simple: simple register allocator
242
243
244
245
246 **-relocation-model**\ =\ *model*
247
248 Choose relocation model from:
249
250
251 .. code-block:: perl
252
253 =default: Target default relocation model
254 =static: Non-relocatable code =pic - Fully relocatable, position independent code
255 =dynamic-no-pic: Relocatable external references, non-relocatable code
256
257
258
259
260 **-spiller**
261
262 Spiller to use (default=local)
263
264
265 .. code-block:: perl
266
267 =simple: simple spiller
268 =local: local spiller
269
270
271
272
273 **-x86-asm-syntax**\ =\ *syntax*
274
275 Choose style of code to emit from X86 backend:
276
277
278 .. code-block:: perl
279
280 =att: Emit AT&T-style assembly
281 =intel: Emit Intel-style assembly
282
283
284
285
286
287 EXIT STATUS
288 -----------
289
290
291 If **lli** fails to load the program, it will exit with an exit code of 1.
292 Otherwise, it will return the exit code of the program it executes.
293
294
295 SEE ALSO
296 --------
297
298
299 llc|llc
0 llvm-ar - LLVM archiver
1 =======================
2
3
4 SYNOPSIS
5 --------
6
7
8 **llvm-ar** [-]{dmpqrtx}[Rabfikouz] [relpos] [count] [files...]
9
10
11 DESCRIPTION
12 -----------
13
14
15 The **llvm-ar** command is similar to the common Unix utility, ``ar``. It
16 archives several files together into a single file. The intent for this is
17 to produce archive libraries by LLVM bitcode that can be linked into an
18 LLVM program. However, the archive can contain any kind of file. By default,
19 **llvm-ar** generates a symbol table that makes linking faster because
20 only the symbol table needs to be consulted, not each individual file member
21 of the archive.
22
23 The **llvm-ar** command can be used to *read* both SVR4 and BSD style archive
24 files. However, it cannot be used to write them. While the **llvm-ar** command
25 produces files that are *almost* identical to the format used by other ``ar``
26 implementations, it has two significant departures in order to make the
27 archive appropriate for LLVM. The first departure is that **llvm-ar** only
28 uses BSD4.4 style long path names (stored immediately after the header) and
29 never contains a string table for long names. The second departure is that the
30 symbol table is formated for efficient construction of an in-memory data
31 structure that permits rapid (red-black tree) lookups. Consequently, archives
32 produced with **llvm-ar** usually won't be readable or editable with any
33 ``ar`` implementation or useful for linking. Using the ``f`` modifier to flatten
34 file names will make the archive readable by other ``ar`` implementations
35 but not for linking because the symbol table format for LLVM is unique. If an
36 SVR4 or BSD style archive is used with the ``r`` (replace) or ``q`` (quick
37 update) operations, the archive will be reconstructed in LLVM format. This
38 means that the string table will be dropped (in deference to BSD 4.4 long names)
39 and an LLVM symbol table will be added (by default). The system symbol table
40 will be retained.
41
42 Here's where **llvm-ar** departs from previous ``ar`` implementations:
43
44
45 *Symbol Table*
46
47 Since **llvm-ar** is intended to archive bitcode files, the symbol table
48 won't make much sense to anything but LLVM. Consequently, the symbol table's
49 format has been simplified. It consists simply of a sequence of pairs
50 of a file member index number as an LSB 4byte integer and a null-terminated
51 string.
52
53
54
55 *Long Paths*
56
57 Some ``ar`` implementations (SVR4) use a separate file member to record long
58 path names (> 15 characters). **llvm-ar** takes the BSD 4.4 and Mac OS X
59 approach which is to simply store the full path name immediately preceding
60 the data for the file. The path name is null terminated and may contain the
61 slash (/) character.
62
63
64
65 *Compression*
66
67 **llvm-ar** can compress the members of an archive to save space. The
68 compression used depends on what's available on the platform and what choices
69 the LLVM Compressor utility makes. It generally favors bzip2 but will select
70 between "no compression" or bzip2 depending on what makes sense for the
71 file's content.
72
73
74
75 *Directory Recursion*
76
77 Most ``ar`` implementations do not recurse through directories but simply
78 ignore directories if they are presented to the program in the *files*
79 option. **llvm-ar**, however, can recurse through directory structures and
80 add all the files under a directory, if requested.
81
82
83
84 *TOC Verbose Output*
85
86 When **llvm-ar** prints out the verbose table of contents (``tv`` option), it
87 precedes the usual output with a character indicating the basic kind of
88 content in the file. A blank means the file is a regular file. A 'Z' means
89 the file is compressed. A 'B' means the file is an LLVM bitcode file. An
90 'S' means the file is the symbol table.
91
92
93
94
95 OPTIONS
96 -------
97
98
99 The options to **llvm-ar** are compatible with other ``ar`` implementations.
100 However, there are a few modifiers (*zR*) that are not found in other ``ar``
101 implementations. The options to **llvm-ar** specify a single basic operation to
102 perform on the archive, a variety of modifiers for that operation, the name of
103 the archive file, and an optional list of file names. These options are used to
104 determine how **llvm-ar** should process the archive file.
105
106 The Operations and Modifiers are explained in the sections below. The minimal
107 set of options is at least one operator and the name of the archive. Typically
108 archive files end with a ``.a`` suffix, but this is not required. Following
109 the *archive-name* comes a list of *files* that indicate the specific members
110 of the archive to operate on. If the *files* option is not specified, it
111 generally means either "none" or "all" members, depending on the operation.
112
113 Operations
114 ~~~~~~~~~~
115
116
117
118 d
119
120 Delete files from the archive. No modifiers are applicable to this operation.
121 The *files* options specify which members should be removed from the
122 archive. It is not an error if a specified file does not appear in the archive.
123 If no *files* are specified, the archive is not modified.
124
125
126
127 m[abi]
128
129 Move files from one location in the archive to another. The *a*, *b*, and
130 *i* modifiers apply to this operation. The *files* will all be moved
131 to the location given by the modifiers. If no modifiers are used, the files
132 will be moved to the end of the archive. If no *files* are specified, the
133 archive is not modified.
134
135
136
137 p[k]
138
139 Print files to the standard output. The *k* modifier applies to this
140 operation. This operation simply prints the *files* indicated to the
141 standard output. If no *files* are specified, the entire archive is printed.
142 Printing bitcode files is ill-advised as they might confuse your terminal
143 settings. The *p* operation never modifies the archive.
144
145
146
147 q[Rfz]
148
149 Quickly append files to the end of the archive. The *R*, *f*, and *z*
150 modifiers apply to this operation. This operation quickly adds the
151 *files* to the archive without checking for duplicates that should be
152 removed first. If no *files* are specified, the archive is not modified.
153 Because of the way that **llvm-ar** constructs the archive file, its dubious
154 whether the *q* operation is any faster than the *r* operation.
155
156
157
158 r[Rabfuz]
159
160 Replace or insert file members. The *R*, *a*, *b*, *f*, *u*, and *z*
161 modifiers apply to this operation. This operation will replace existing
162 *files* or insert them at the end of the archive if they do not exist. If no
163 *files* are specified, the archive is not modified.
164
165
166
167 t[v]
168
169 Print the table of contents. Without any modifiers, this operation just prints
170 the names of the members to the standard output. With the *v* modifier,
171 **llvm-ar** also prints out the file type (B=bitcode, Z=compressed, S=symbol
172 table, blank=regular file), the permission mode, the owner and group, the
173 size, and the date. If any *files* are specified, the listing is only for
174 those files. If no *files* are specified, the table of contents for the
175 whole archive is printed.
176
177
178
179 x[oP]
180
181 Extract archive members back to files. The *o* modifier applies to this
182 operation. This operation retrieves the indicated *files* from the archive
183 and writes them back to the operating system's file system. If no
184 *files* are specified, the entire archive is extract.
185
186
187
188
189 Modifiers (operation specific)
190 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
191
192
193 The modifiers below are specific to certain operations. See the Operations
194 section (above) to determine which modifiers are applicable to which operations.
195
196
197 [a]
198
199 When inserting or moving member files, this option specifies the destination of
200 the new files as being after the *relpos* member. If *relpos* is not found,
201 the files are placed at the end of the archive.
202
203
204
205 [b]
206
207 When inserting or moving member files, this option specifies the destination of
208 the new files as being before the *relpos* member. If *relpos* is not
209 found, the files are placed at the end of the archive. This modifier is
210 identical to the the *i* modifier.
211
212
213
214 [f]
215
216 Normally, **llvm-ar** stores the full path name to a file as presented to it on
217 the command line. With this option, truncated (15 characters max) names are
218 used. This ensures name compatibility with older versions of ``ar`` but may also
219 thwart correct extraction of the files (duplicates may overwrite). If used with
220 the *R* option, the directory recursion will be performed but the file names
221 will all be flattened to simple file names.
222
223
224
225 [i]
226
227 A synonym for the *b* option.
228
229
230
231 [k]
232
233 Normally, **llvm-ar** will not print the contents of bitcode files when the
234 *p* operation is used. This modifier defeats the default and allows the
235 bitcode members to be printed.
236
237
238
239 [N]
240
241 This option is ignored by **llvm-ar** but provided for compatibility.
242
243
244
245 [o]
246
247 When extracting files, this option will cause **llvm-ar** to preserve the
248 original modification times of the files it writes.
249
250
251
252 [P]
253
254 use full path names when matching
255
256
257
258 [R]
259
260 This modifier instructions the *r* option to recursively process directories.
261 Without *R*, directories are ignored and only those *files* that refer to
262 files will be added to the archive. When *R* is used, any directories specified
263 with *files* will be scanned (recursively) to find files to be added to the
264 archive. Any file whose name begins with a dot will not be added.
265
266
267
268 [u]
269
270 When replacing existing files in the archive, only replace those files that have
271 a time stamp than the time stamp of the member in the archive.
272
273
274
275 [z]
276
277 When inserting or replacing any file in the archive, compress the file first.
278 This
279 modifier is safe to use when (previously) compressed bitcode files are added to
280 the archive; the compressed bitcode files will not be doubly compressed.
281
282
283
284
285 Modifiers (generic)
286 ~~~~~~~~~~~~~~~~~~~
287
288
289 The modifiers below may be applied to any operation.
290
291
292 [c]
293
294 For all operations, **llvm-ar** will always create the archive if it doesn't
295 exist. Normally, **llvm-ar** will print a warning message indicating that the
296 archive is being created. Using this modifier turns off that warning.
297
298
299
300 [s]
301
302 This modifier requests that an archive index (or symbol table) be added to the
303 archive. This is the default mode of operation. The symbol table will contain
304 all the externally visible functions and global variables defined by all the
305 bitcode files in the archive. Using this modifier is more efficient that using
306 llvm-ranlib|llvm-ranlib which also creates the symbol table.
307
308
309
310 [S]
311
312 This modifier is the opposite of the *s* modifier. It instructs **llvm-ar** to
313 not build the symbol table. If both *s* and *S* are used, the last modifier to
314 occur in the options will prevail.
315
316
317
318 [v]
319
320 This modifier instructs **llvm-ar** to be verbose about what it is doing. Each
321 editing operation taken against the archive will produce a line of output saying
322 what is being done.
323
324
325
326
327
328 STANDARDS
329 ---------
330
331
332 The **llvm-ar** utility is intended to provide a superset of the IEEE Std 1003.2
333 (POSIX.2) functionality for ``ar``. **llvm-ar** can read both SVR4 and BSD4.4 (or
334 Mac OS X) archives. If the ``f`` modifier is given to the ``x`` or ``r`` operations
335 then **llvm-ar** will write SVR4 compatible archives. Without this modifier,
336 **llvm-ar** will write BSD4.4 compatible archives that have long names
337 immediately after the header and indicated using the "#1/ddd" notation for the
338 name in the header.
339
340
341 FILE FORMAT
342 -----------
343
344
345 The file format for LLVM Archive files is similar to that of BSD 4.4 or Mac OSX
346 archive files. In fact, except for the symbol table, the ``ar`` commands on those
347 operating systems should be able to read LLVM archive files. The details of the
348 file format follow.
349
350 Each archive begins with the archive magic number which is the eight printable
351 characters "!\n" where \n represents the newline character (0x0A).
352 Following the magic number, the file is composed of even length members that
353 begin with an archive header and end with a \n padding character if necessary
354 (to make the length even). Each file member is composed of a header (defined
355 below), an optional newline-terminated "long file name" and the contents of
356 the file.
357
358 The fields of the header are described in the items below. All fields of the
359 header contain only ASCII characters, are left justified and are right padded
360 with space characters.
361
362
363 name - char[16]
364
365 This field of the header provides the name of the archive member. If the name is
366 longer than 15 characters or contains a slash (/) character, then this field
367 contains ``#1/nnn`` where ``nnn`` provides the length of the name and the ``#1/``
368 is literal. In this case, the actual name of the file is provided in the ``nnn``
369 bytes immediately following the header. If the name is 15 characters or less, it
370 is contained directly in this field and terminated with a slash (/) character.
371
372
373
374 date - char[12]
375
376 This field provides the date of modification of the file in the form of a
377 decimal encoded number that provides the number of seconds since the epoch
378 (since 00:00:00 Jan 1, 1970) per Posix specifications.
379
380
381
382 uid - char[6]
383
384 This field provides the user id of the file encoded as a decimal ASCII string.
385 This field might not make much sense on non-Unix systems. On Unix, it is the
386 same value as the st_uid field of the stat structure returned by the stat(2)
387 operating system call.
388
389
390
391 gid - char[6]
392
393 This field provides the group id of the file encoded as a decimal ASCII string.
394 This field might not make much sense on non-Unix systems. On Unix, it is the
395 same value as the st_gid field of the stat structure returned by the stat(2)
396 operating system call.
397
398
399
400 mode - char[8]
401
402 This field provides the access mode of the file encoded as an octal ASCII
403 string. This field might not make much sense on non-Unix systems. On Unix, it
404 is the same value as the st_mode field of the stat structure returned by the
405 stat(2) operating system call.
406
407
408
409 size - char[10]
410
411 This field provides the size of the file, in bytes, encoded as a decimal ASCII
412 string. If the size field is negative (starts with a minus sign, 0x02D), then
413 the archive member is stored in compressed form. The first byte of the archive
414 member's data indicates the compression type used. A value of 0 (0x30) indicates
415 that no compression was used. A value of 2 (0x32) indicates that bzip2
416 compression was used.
417
418
419
420 fmag - char[2]
421
422 This field is the archive file member magic number. Its content is always the
423 two characters back tick (0x60) and newline (0x0A). This provides some measure
424 utility in identifying archive files that have been corrupted.
425
426
427
428 The LLVM symbol table has the special name "#_LLVM_SYM_TAB_#". It is presumed
429 that no regular archive member file will want this name. The LLVM symbol table
430 is simply composed of a sequence of triplets: byte offset, length of symbol,
431 and the symbol itself. Symbols are not null or newline terminated. Here are
432 the details on each of these items:
433
434
435 offset - vbr encoded 32-bit integer
436
437 The offset item provides the offset into the archive file where the bitcode
438 member is stored that is associated with the symbol. The offset value is 0
439 based at the start of the first "normal" file member. To derive the actual
440 file offset of the member, you must add the number of bytes occupied by the file
441 signature (8 bytes) and the symbol tables. The value of this item is encoded
442 using variable bit rate encoding to reduce the size of the symbol table.
443 Variable bit rate encoding uses the high bit (0x80) of each byte to indicate
444 if there are more bytes to follow. The remaining 7 bits in each byte carry bits
445 from the value. The final byte does not have the high bit set.
446
447
448
449 length - vbr encoded 32-bit integer
450
451 The length item provides the length of the symbol that follows. Like this
452 *offset* item, the length is variable bit rate encoded.
453
454
455
456 symbol - character array
457
458 The symbol item provides the text of the symbol that is associated with the
459 *offset*. The symbol is not terminated by any character. Its length is provided
460 by the *length* field. Note that is allowed (but unwise) to use non-printing
461 characters (even 0x00) in the symbol. This allows for multiple encodings of
462 symbol names.
463
464
465
466
467 EXIT STATUS
468 -----------
469
470
471 If **llvm-ar** succeeds, it will exit with 0. A usage error, results
472 in an exit code of 1. A hard (file system typically) error results in an
473 exit code of 2. Miscellaneous or unknown errors result in an
474 exit code of 3.
475
476
477 SEE ALSO
478 --------
479
480
481 llvm-ranlib|llvm-ranlib, ar(1)
0 llvm-as - LLVM assembler
1 ========================
2
3
4 SYNOPSIS
5 --------
6
7
8 **llvm-as** [*options*] [*filename*]
9
10
11 DESCRIPTION
12 -----------
13
14
15 **llvm-as** is the LLVM assembler. It reads a file containing human-readable
16 LLVM assembly language, translates it to LLVM bitcode, and writes the result
17 into a file or to standard output.
18
19 If *filename* is omitted or is ``-``, then **llvm-as** reads its input from
20 standard input.
21
22 If an output file is not specified with the **-o** option, then
23 **llvm-as** sends its output to a file or standard output by following
24 these rules:
25
26
27 \*
28
29 If the input is standard input, then the output is standard output.
30
31
32
33 \*
34
35 If the input is a file that ends with ``.ll``, then the output file is of
36 the same name, except that the suffix is changed to ``.bc``.
37
38
39
40 \*
41
42 If the input is a file that does not end with the ``.ll`` suffix, then the
43 output file has the same name as the input file, except that the ``.bc``
44 suffix is appended.
45
46
47
48
49 OPTIONS
50 -------
51
52
53
54 **-f**
55
56 Enable binary output on terminals. Normally, **llvm-as** will refuse to
57 write raw bitcode output if the output stream is a terminal. With this option,
58 **llvm-as** will write raw bitcode regardless of the output device.
59
60
61
62 **-help**
63
64 Print a summary of command line options.
65
66
67
68 **-o** *filename*
69
70 Specify the output file name. If *filename* is ``-``, then **llvm-as**
71 sends its output to standard output.
72
73
74
75
76 EXIT STATUS
77 -----------
78
79
80 If **llvm-as** succeeds, it will exit with 0. Otherwise, if an error
81 occurs, it will exit with a non-zero value.
82
83
84 SEE ALSO
85 --------
86
87
88 llvm-dis|llvm-dis, gccas|gccas
0 llvm-bcanalyzer - LLVM bitcode analyzer
1 =======================================
2
3
4 SYNOPSIS
5 --------
6
7
8 **llvm-bcanalyzer** [*options*] [*filename*]
9
10
11 DESCRIPTION
12 -----------
13
14
15 The **llvm-bcanalyzer** command is a small utility for analyzing bitcode files.
16 The tool reads a bitcode file (such as generated with the **llvm-as** tool) and
17 produces a statistical report on the contents of the bitcode file. The tool
18 can also dump a low level but human readable version of the bitcode file.
19 This tool is probably not of much interest or utility except for those working
20 directly with the bitcode file format. Most LLVM users can just ignore
21 this tool.
22
23 If *filename* is omitted or is ``-``, then **llvm-bcanalyzer** reads its input
24 from standard input. This is useful for combining the tool into a pipeline.
25 Output is written to the standard output.
26
27
28 OPTIONS
29 -------
30
31
32
33 **-nodetails**
34
35 Causes **llvm-bcanalyzer** to abbreviate its output by writing out only a module
36 level summary. The details for individual functions are not displayed.
37
38
39
40 **-dump**
41
42 Causes **llvm-bcanalyzer** to dump the bitcode in a human readable format. This
43 format is significantly different from LLVM assembly and provides details about
44 the encoding of the bitcode file.
45
46
47
48 **-verify**
49
50 Causes **llvm-bcanalyzer** to verify the module produced by reading the
51 bitcode. This ensures that the statistics generated are based on a consistent
52 module.
53
54
55
56 **-help**
57
58 Print a summary of command line options.
59
60
61
62
63 EXIT STATUS
64 -----------
65
66
67 If **llvm-bcanalyzer** succeeds, it will exit with 0. Otherwise, if an error
68 occurs, it will exit with a non-zero value, usually 1.
69
70
71 SUMMARY OUTPUT DEFINITIONS
72 --------------------------
73
74
75 The following items are always printed by llvm-bcanalyzer. They comprize the
76 summary output.
77
78
79 **Bitcode Analysis Of Module**
80
81 This just provides the name of the module for which bitcode analysis is being
82 generated.
83
84
85
86 **Bitcode Version Number**
87
88 The bitcode version (not LLVM version) of the file read by the analyzer.
89
90
91
92 **File Size**
93
94 The size, in bytes, of the entire bitcode file.
95
96
97
98 **Module Bytes**
99
100 The size, in bytes, of the module block. Percentage is relative to File Size.
101
102
103
104 **Function Bytes**
105
106 The size, in bytes, of all the function blocks. Percentage is relative to File
107 Size.
108
109
110
111 **Global Types Bytes**
112
113 The size, in bytes, of the Global Types Pool. Percentage is relative to File
114 Size. This is the size of the definitions of all types in the bitcode file.
115
116
117
118 **Constant Pool Bytes**
119
120 The size, in bytes, of the Constant Pool Blocks Percentage is relative to File
121 Size.
122
123
124
125 **Module Globals Bytes**
126
127 Ths size, in bytes, of the Global Variable Definitions and their initializers.
128 Percentage is relative to File Size.
129
130
131
132 **Instruction List Bytes**
133
134 The size, in bytes, of all the instruction lists in all the functions.
135 Percentage is relative to File Size. Note that this value is also included in
136 the Function Bytes.
137
138
139
140 **Compaction Table Bytes**
141
142 The size, in bytes, of all the compaction tables in all the functions.
143 Percentage is relative to File Size. Note that this value is also included in
144 the Function Bytes.
145
146
147
148 **Symbol Table Bytes**
149
150 The size, in bytes, of all the symbol tables in all the functions. Percentage is
151 relative to File Size. Note that this value is also included in the Function
152 Bytes.
153
154
155
156 **Dependent Libraries Bytes**
157
158 The size, in bytes, of the list of dependent libraries in the module. Percentage
159 is relative to File Size. Note that this value is also included in the Module
160 Global Bytes.
161
162
163
164 **Number Of Bitcode Blocks**
165
166 The total number of blocks of any kind in the bitcode file.
167
168
169
170 **Number Of Functions**
171
172 The total number of function definitions in the bitcode file.
173
174
175
176 **Number Of Types**
177
178 The total number of types defined in the Global Types Pool.
179
180
181
182 **Number Of Constants**
183
184 The total number of constants (of any type) defined in the Constant Pool.
185
186
187
188 **Number Of Basic Blocks**
189
190 The total number of basic blocks defined in all functions in the bitcode file.
191
192
193
194 **Number Of Instructions**
195
196 The total number of instructions defined in all functions in the bitcode file.
197
198
199
200 **Number Of Long Instructions**
201
202 The total number of long instructions defined in all functions in the bitcode
203 file. Long instructions are those taking greater than 4 bytes. Typically long
204 instructions are GetElementPtr with several indices, PHI nodes, and calls to
205 functions with large numbers of arguments.
206
207
208
209 **Number Of Operands**
210
211 The total number of operands used in all instructions in the bitcode file.
212
213
214
215 **Number Of Compaction Tables**
216
217 The total number of compaction tables in all functions in the bitcode file.
218
219
220
221 **Number Of Symbol Tables**
222
223 The total number of symbol tables in all functions in the bitcode file.
224
225
226
227 **Number Of Dependent Libs**
228
229 The total number of dependent libraries found in the bitcode file.
230
231
232
233 **Total Instruction Size**
234
235 The total size of the instructions in all functions in the bitcode file.
236
237
238
239 **Average Instruction Size**
240
241 The average number of bytes per instruction across all functions in the bitcode
242 file. This value is computed by dividing Total Instruction Size by Number Of
243 Instructions.
244
245
246
247 **Maximum Type Slot Number**
248
249 The maximum value used for a type's slot number. Larger slot number values take
250 more bytes to encode.
251
252
253
254 **Maximum Value Slot Number**
255
256 The maximum value used for a value's slot number. Larger slot number values take
257 more bytes to encode.
258
259
260
261 **Bytes Per Value**
262
263 The average size of a Value definition (of any type). This is computed by
264 dividing File Size by the total number of values of any type.
265
266
267
268 **Bytes Per Global**
269
270 The average size of a global definition (constants and global variables).
271
272
273
274 **Bytes Per Function**
275
276 The average number of bytes per function definition. This is computed by
277 dividing Function Bytes by Number Of Functions.
278
279
280
281 **# of VBR 32-bit Integers**
282
283 The total number of 32-bit integers encoded using the Variable Bit Rate
284 encoding scheme.
285
286
287
288 **# of VBR 64-bit Integers**
289
290 The total number of 64-bit integers encoded using the Variable Bit Rate encoding
291 scheme.
292
293
294
295 **# of VBR Compressed Bytes**
296
297 The total number of bytes consumed by the 32-bit and 64-bit integers that use
298 the Variable Bit Rate encoding scheme.
299
300
301
302 **# of VBR Expanded Bytes**
303
304 The total number of bytes that would have been consumed by the 32-bit and 64-bit
305 integers had they not been compressed with the Variable Bit Rage encoding
306 scheme.
307
308
309
310 **Bytes Saved With VBR**
311
312 The total number of bytes saved by using the Variable Bit Rate encoding scheme.
313 The percentage is relative to # of VBR Expanded Bytes.
314
315
316
317
318 DETAILED OUTPUT DEFINITIONS
319 ---------------------------
320
321
322 The following definitions occur only if the -nodetails option was not given.
323 The detailed output provides additional information on a per-function basis.
324
325
326 **Type**
327
328 The type signature of the function.
329
330
331
332 **Byte Size**
333
334 The total number of bytes in the function's block.
335
336
337
338 **Basic Blocks**
339
340 The number of basic blocks defined by the function.
341
342
343
344 **Instructions**
345
346 The number of instructions defined by the function.
347
348
349
350 **Long Instructions**
351
352 The number of instructions using the long instruction format in the function.
353
354
355
356 **Operands**
357
358 The number of operands used by all instructions in the function.
359
360
361
362 **Instruction Size**
363
364 The number of bytes consumed by instructions in the function.
365
366
367
368 **Average Instruction Size**
369
370 The average number of bytes consumed by the instructions in the function. This
371 value is computed by dividing Instruction Size by Instructions.
372
373
374
375 **Bytes Per Instruction**
376
377 The average number of bytes used by the function per instruction. This value is
378 computed by dividing Byte Size by Instructions. Note that this is not the same
379 as Average Instruction Size. It computes a number relative to the total function
380 size not just the size of the instruction list.
381
382
383
384 **Number of VBR 32-bit Integers**
385
386 The total number of 32-bit integers found in this function (for any use).
387
388
389
390 **Number of VBR 64-bit Integers**
391
392 The total number of 64-bit integers found in this function (for any use).
393
394
395
396 **Number of VBR Compressed Bytes**
397
398 The total number of bytes in this function consumed by the 32-bit and 64-bit
399 integers that use the Variable Bit Rate encoding scheme.
400
401
402
403 **Number of VBR Expanded Bytes**
404
405 The total number of bytes in this function that would have been consumed by
406 the 32-bit and 64-bit integers had they not been compressed with the Variable
407 Bit Rate encoding scheme.
408
409
410
411 **Bytes Saved With VBR**
412
413 The total number of bytes saved in this function by using the Variable Bit
414 Rate encoding scheme. The percentage is relative to # of VBR Expanded Bytes.
415
416
417
418
419 SEE ALSO
420 --------
421
422
423 llvm-dis|llvm-dis, `http://llvm.org/docs/BitCodeFormat.html `_
0 llvm-build - LLVM Project Build Utility
1 =======================================
2
3
4 SYNOPSIS
5 --------
6
7
8 **llvm-build** [*options*]
9
10
11 DESCRIPTION
12 -----------
13
14
15 **llvm-build** is a tool for working with LLVM projects that use the LLVMBuild
16 system for describing their components.
17
18 At heart, **llvm-build** is responsible for loading, verifying, and manipulating
19 the project's component data. The tool is primarily designed for use in
20 implementing build systems and tools which need access to the project structure
21 information.
22
23
24 OPTIONS
25 -------
26
27
28
29 **-h**, **--help**
30
31 Print the builtin program help.
32
33
34
35 **--source-root**\ =\ *PATH*
36
37 If given, load the project at the given source root path. If this option is not
38 given, the location of the project sources will be inferred from the location of
39 the **llvm-build** script itself.
40
41
42
43 **--print-tree**
44
45 Print the component tree for the project.
46
47
48
49 **--write-library-table**
50
51 Write out the C++ fragment which defines the components, library names, and
52 required libraries. This C++ fragment is built into llvm-config|llvm-config
53 in order to provide clients with the list of required libraries for arbitrary
54 component combinations.
55
56
57
58 **--write-llvmbuild**
59
60 Write out new *LLVMBuild.txt* files based on the loaded components. This is
61 useful for auto-upgrading the schema of the files. **llvm-build** will try to a
62 limited extent to preserve the comments which were written in the original
63 source file, although at this time it only preserves block comments that preceed
64 the section names in the *LLVMBuild* files.
65
66
67
68 **--write-cmake-fragment**
69
70 Write out the LLVMBuild in the form of a CMake fragment, so it can easily be
71 consumed by the CMake based build system. The exact contents and format of this
72 file are closely tied to how LLVMBuild is integrated with CMake, see LLVM's
73 top-level CMakeLists.txt.
74
75
76
77 **--write-make-fragment**
78
79 Write out the LLVMBuild in the form of a Makefile fragment, so it can easily be
80 consumed by a Make based build system. The exact contents and format of this
81 file are closely tied to how LLVMBuild is integrated with the Makefiles, see
82 LLVM's Makefile.rules.
83
84
85
86 **--llvmbuild-source-root**\ =\ *PATH*
87
88 If given, expect the *LLVMBuild* files for the project to be rooted at the
89 given path, instead of inside the source tree itself. This option is primarily
90 designed for use in conjunction with **--write-llvmbuild** to test changes to
91 *LLVMBuild* schema.
92
93
94
95
96 EXIT STATUS
97 -----------
98
99
100 **llvm-build** exits with 0 if operation was successful. Otherwise, it will exist
101 with a non-zero value.
0 llvm-config - Print LLVM compilation options
1 ============================================
2
3
4 SYNOPSIS
5 --------
6
7
8 **llvm-config** *option* [*components*...]
9
10
11 DESCRIPTION
12 -----------
13
14
15 **llvm-config** makes it easier to build applications that use LLVM. It can
16 print the compiler flags, linker flags and object libraries needed to link
17 against LLVM.
18
19
20 EXAMPLES
21 --------
22
23
24 To link against the JIT:
25
26
27 .. code-block:: perl
28
29 g++ `llvm-config --cxxflags` -o HowToUseJIT.o -c HowToUseJIT.cpp
30 g++ `llvm-config --ldflags` -o HowToUseJIT HowToUseJIT.o \
31 `llvm-config --libs engine bcreader scalaropts`
32
33
34
35 OPTIONS
36 -------
37
38
39
40 **--version**
41
42 Print the version number of LLVM.
43
44
45
46 **-help**
47
48 Print a summary of **llvm-config** arguments.
49
50
51
52 **--prefix**
53
54 Print the installation prefix for LLVM.
55
56
57
58 **--src-root**
59
60 Print the source root from which LLVM was built.
61
62
63
64 **--obj-root**
65
66 Print the object root used to build LLVM.
67
68
69
70 **--bindir**
71
72 Print the installation directory for LLVM binaries.
73
74
75
76 **--includedir**
77
78 Print the installation directory for LLVM headers.
79
80
81
82 **--libdir**
83
84 Print the installation directory for LLVM libraries.
85
86
87
88 **--cxxflags**
89
90 Print the C++ compiler flags needed to use LLVM headers.
91
92
93
94 **--ldflags**
95
96 Print the flags needed to link against LLVM libraries.
97
98
99
100 **--libs**
101
102 Print all the libraries needed to link against the specified LLVM
103 *components*, including any dependencies.
104
105
106
107 **--libnames**
108
109 Similar to **--libs**, but prints the bare filenames of the libraries
110 without **-l** or pathnames. Useful for linking against a not-yet-installed
111 copy of LLVM.
112
113
114
115 **--libfiles**
116
117 Similar to **--libs**, but print the full path to each library file. This is
118 useful when creating makefile dependencies, to ensure that a tool is relinked if
119 any library it uses changes.
120
121
122
123 **--components**
124
125 Print all valid component names.
126
127
128
129 **--targets-built**
130
131 Print the component names for all targets supported by this copy of LLVM.
132
133
134
135 **--build-mode**
136
137 Print the build mode used when LLVM was built (e.g. Debug or Release)
138
139
140
141
142 COMPONENTS
143 ----------
144
145
146 To print a list of all available components, run **llvm-config
147 --components**. In most cases, components correspond directly to LLVM
148 libraries. Useful "virtual" components include:
149
150
151 **all**
152
153 Includes all LLVM libaries. The default if no components are specified.
154
155
156
157 **backend**
158
159 Includes either a native backend or the C backend.
160
161
162
163 **engine**
164
165 Includes either a native JIT or the bitcode interpreter.
166
167
168
169
170 EXIT STATUS
171 -----------
172
173
174 If **llvm-config** succeeds, it will exit with 0. Otherwise, if an error
175 occurs, it will exit with a non-zero value.
0 llvm-cov - emit coverage information
1 ====================================
2
3
4 SYNOPSIS
5 --------
6
7
8 **llvm-cov** [-gcno=filename] [-gcda=filename] [dump]
9
10
11 DESCRIPTION
12 -----------
13
14
15 The experimental **llvm-cov** tool reads in description file generated by compiler
16 and coverage data file generated by instrumented program. This program assumes
17 that the description and data file uses same format as gcov files.
18
19
20 OPTIONS
21 -------
22
23
24
25 **-gcno=filename]**
26
27 This option selects input description file generated by compiler while instrumenting
28 program.
29
30
31
32 **-gcda=filename]**
33
34 This option selects coverage data file generated by instrumented compiler.
35
36
37
38 **-dump**
39
40 This options enables output dump that is suitable for a developer to help debug
41 **llvm-cov** itself.
42
43
44
45
46 EXIT STATUS
47 -----------
48
49
50 **llvm-cov** returns 1 if it cannot read input files. Otherwise, it exits with zero.
0 llvm-diff - LLVM structural 'diff'
1 ==================================
2
3
4 SYNOPSIS
5 --------
6
7
8 **llvm-diff** [*options*] *module 1* *module 2* [*global name ...*]
9
10
11 DESCRIPTION
12 -----------
13
14
15 **llvm-diff** compares the structure of two LLVM modules, primarily
16 focusing on differences in function definitions. Insignificant
17 differences, such as changes in the ordering of globals or in the
18 names of local values, are ignored.
19
20 An input module will be interpreted as an assembly file if its name
21 ends in '.ll'; otherwise it will be read in as a bitcode file.
22
23 If a list of global names is given, just the values with those names
24 are compared; otherwise, all global values are compared, and
25 diagnostics are produced for globals which only appear in one module
26 or the other.
27
28 **llvm-diff** compares two functions by comparing their basic blocks,
29 beginning with the entry blocks. If the terminators seem to match,
30 then the corresponding successors are compared; otherwise they are
31 ignored. This algorithm is very sensitive to changes in control flow,
32 which tend to stop any downstream changes from being detected.
33
34 **llvm-diff** is intended as a debugging tool for writers of LLVM
35 passes and frontends. It does not have a stable output format.
36
37
38 EXIT STATUS
39 -----------
40
41
42 If **llvm-diff** finds no differences between the modules, it will exit
43 with 0 and produce no output. Otherwise it will exit with a non-zero
44 value.
45
46
47 BUGS
48 ----
49
50
51 Many important differences, like changes in linkage or function
52 attributes, are not diagnosed.
53
54 Changes in memory behavior (for example, coalescing loads) can cause
55 massive detected differences in blocks.
0 llvm-dis - LLVM disassembler
1 ============================
2
3
4 SYNOPSIS
5 --------
6
7
8 **llvm-dis** [*options*] [*filename*]
9
10
11 DESCRIPTION
12 -----------
13
14
15 The **llvm-dis** command is the LLVM disassembler. It takes an LLVM
16 bitcode file and converts it into human-readable LLVM assembly language.
17
18 If filename is omitted or specified as ``-``, **llvm-dis** reads its
19 input from standard input.
20
21 If the input is being read from standard input, then **llvm-dis**
22 will send its output to standard output by default. Otherwise, the
23 output will be written to a file named after the input file, with
24 a ``.ll`` suffix added (any existing ``.bc`` suffix will first be
25 removed). You can override the choice of output file using the
26 **-o** option.
27
28
29 OPTIONS
30 -------
31
32
33
34 **-f**
35
36 Enable binary output on terminals. Normally, **llvm-dis** will refuse to
37 write raw bitcode output if the output stream is a terminal. With this option,
38 **llvm-dis** will write raw bitcode regardless of the output device.
39
40
41
42 **-help**
43
44 Print a summary of command line options.
45
46
47
48 **-o** *filename*
49
50 Specify the output file name. If *filename* is -, then the output is sent
51 to standard output.
52
53
54
55
56 EXIT STATUS
57 -----------
58
59
60 If **llvm-dis** succeeds, it will exit with 0. Otherwise, if an error
61 occurs, it will exit with a non-zero value.
62
63
64 SEE ALSO
65 --------
66
67
68 llvm-as|llvm-as
0 llvm-extract - extract a function from an LLVM module
1 =====================================================
2
3
4 SYNOPSIS
5 --------
6
7
8 **llvm-extract** [*options*] **--func** *function-name* [*filename*]
9
10
11 DESCRIPTION
12 -----------
13
14
15 The **llvm-extract** command takes the name of a function and extracts it from
16 the specified LLVM bitcode file. It is primarily used as a debugging tool to
17 reduce test cases from larger programs that are triggering a bug.
18
19 In addition to extracting the bitcode of the specified function,
20 **llvm-extract** will also remove unreachable global variables, prototypes, and
21 unused types.
22
23 The **llvm-extract** command reads its input from standard input if filename is
24 omitted or if filename is -. The output is always written to standard output,
25 unless the **-o** option is specified (see below).
26
27
28 OPTIONS
29 -------
30
31
32
33 **-f**
34
35 Enable binary output on terminals. Normally, **llvm-extract** will refuse to
36 write raw bitcode output if the output stream is a terminal. With this option,
37 **llvm-extract** will write raw bitcode regardless of the output device.
38
39
40
41 **--func** *function-name*
42
43 Extract the function named *function-name* from the LLVM bitcode. May be
44 specified multiple times to extract multiple functions at once.
45
46
47
48 **--rfunc** *function-regular-expr*
49
50 Extract the function(s) matching *function-regular-expr* from the LLVM bitcode.
51 All functions matching the regular expression will be extracted. May be
52 specified multiple times.
53
54
55
56 **--glob** *global-name*
57
58 Extract the global variable named *global-name* from the LLVM bitcode. May be
59 specified multiple times to extract multiple global variables at once.
60
61
62
63 **--rglob** *glob-regular-expr*
64
65 Extract the global variable(s) matching *global-regular-expr* from the LLVM
66 bitcode. All global variables matching the regular expression will be extracted.
67 May be specified multiple times.
68
69
70
71 **-help**
72
73 Print a summary of command line options.
74
75
76
77 **-o** *filename*
78
79 Specify the output filename. If filename is "-" (the default), then
80 **llvm-extract** sends its output to standard output.
81
82
83
84 **-S**
85
86 Write output in LLVM intermediate language (instead of bitcode).
87
88
89
90
91 EXIT STATUS
92 -----------
93
94
95 If **llvm-extract** succeeds, it will exit with 0. Otherwise, if an error
96 occurs, it will exit with a non-zero value.
97
98
99 SEE ALSO
100 --------
101
102
103 bugpoint|bugpoint
0 llvm-link - LLVM linker
1 =======================
2
3
4 SYNOPSIS
5 --------
6
7
8 **llvm-link** [*options*] *filename ...*
9
10
11 DESCRIPTION
12 -----------
13
14
15 **llvm-link** takes several LLVM bitcode files and links them together into a
16 single LLVM bitcode file. It writes the output file to standard output, unless
17 the **-o** option is used to specify a filename.
18
19 **llvm-link** attempts to load the input files from the current directory. If
20 that fails, it looks for each file in each of the directories specified by the
21 **-L** options on the command line. The library search paths are global; each
22 one is searched for every input file if necessary. The directories are searched
23 in the order they were specified on the command line.
24
25
26 OPTIONS
27 -------
28
29
30
31 **-L** *directory*
32
33 Add the specified *directory* to the library search path. When looking for
34 libraries, **llvm-link** will look in path name for libraries. This option can be
35 specified multiple times; **llvm-link** will search inside these directories in
36 the order in which they were specified on the command line.
37
38
39
40 **-f**
41
42 Enable binary output on terminals. Normally, **llvm-link** will refuse to
43 write raw bitcode output if the output stream is a terminal. With this option,
44 **llvm-link** will write raw bitcode regardless of the output device.
45
46
47
48 **-o** *filename*
49
50 Specify the output file name. If *filename* is ``-``, then **llvm-link** will
51 write its output to standard output.
52
53
54
55 **-S**
56
57 Write output in LLVM intermediate language (instead of bitcode).
58
59
60
61 **-d**
62
63 If specified, **llvm-link** prints a human-readable version of the output
64 bitcode file to standard error.
65
66
67
68 **-help**
69
70 Print a summary of command line options.
71
72
73
74 **-v**
75
76 Verbose mode. Print information about what **llvm-link** is doing. This
77 typically includes a message for each bitcode file linked in and for each
78 library found.
79
80
81
82
83 EXIT STATUS
84 -----------
85
86
87 If **llvm-link** succeeds, it will exit with 0. Otherwise, if an error
88 occurs, it will exit with a non-zero value.
89
90
91 SEE ALSO
92 --------
93
94
95 gccld|gccld
0 llvm-nm - list LLVM bitcode file's symbol table
1 ===============================================
2
3
4 SYNOPSIS
5 --------
6
7
8 **llvm-nm** [*options*] [*filenames...*]
9
10
11 DESCRIPTION
12 -----------
13
14
15 The **llvm-nm** utility lists the names of symbols from the LLVM bitcode files,
16 or **ar** archives containing LLVM bitcode files, named on the command line.
17 Each symbol is listed along with some simple information about its provenance.
18 If no file name is specified, or *-* is used as a file name, **llvm-nm** will
19 process a bitcode file on its standard input stream.
20
21 **llvm-nm**'s default output format is the traditional BSD **nm** output format.
22 Each such output record consists of an (optional) 8-digit hexadecimal address,
23 followed by a type code character, followed by a name, for each symbol. One
24 record is printed per line; fields are separated by spaces. When the address is
25 omitted, it is replaced by 8 spaces.
26
27 Type code characters currently supported, and their meanings, are as follows:
28
29
30 U
31
32 Named object is referenced but undefined in this bitcode file
33
34
35
36 C
37
38 Common (multiple definitions link together into one def)
39
40
41
42 W
43
44 Weak reference (multiple definitions link together into zero or one definitions)
45
46
47
48 t
49
50 Local function (text) object
51
52
53
54 T
55
56 Global function (text) object
57
58
59
60 d
61
62 Local data object
63
64
65
66 D
67
68 Global data object
69
70
71
72 ?
73
74 Something unrecognizable
75
76
77
78 Because LLVM bitcode files typically contain objects that are not considered to
79 have addresses until they are linked into an executable image or dynamically
80 compiled "just-in-time", **llvm-nm** does not print an address for any symbol,
81 even symbols which are defined in the bitcode file.
82
83
84 OPTIONS
85 -------
86
87
88
89 **-P**
90
91 Use POSIX.2 output format. Alias for **--format=posix**.
92
93
94
95 **-B** (default)
96
97 Use BSD output format. Alias for **--format=bsd**.
98
99
100
101 **-help**
102
103 Print a summary of command-line options and their meanings.
104
105
106
107 **--defined-only**
108
109 Print only symbols defined in this bitcode file (as opposed to
110 symbols which may be referenced by objects in this file, but not
111 defined in this file.)
112
113
114
115 **--extern-only**, **-g**
116
117 Print only symbols whose definitions are external; that is, accessible
118 from other bitcode files.
119
120
121
122 **--undefined-only**, **-u**
123
124 Print only symbols referenced but not defined in this bitcode file.
125
126
127
128
129 Select an output format; *fmt* may be *sysv*, *posix*, or *bsd*. The
130 default is *bsd*.
131
132
133
134
135 BUGS
136 ----
137
138
139 **llvm-nm** cannot demangle C++ mangled names, like GNU **nm** can.
140
141
142 EXIT STATUS
143 -----------
144
145
146 **llvm-nm** exits with an exit code of zero.
147
148
149 SEE ALSO
150 --------
151
152
153 llvm-dis|llvm-dis, ar(1), nm(1)
0 llvm-prof - print execution profile of LLVM program
1 ===================================================
2
3
4 SYNOPSIS
5 --------
6
7
8 **llvm-prof** [*options*] [*bitcode file*] [*llvmprof.out*]
9
10
11 DESCRIPTION
12 -----------
13
14
15 The **llvm-prof** tool reads in an *llvmprof.out* file (which can
16 optionally use a specific file with the third program argument), a bitcode file
17 for the program, and produces a human readable report, suitable for determining
18 where the program hotspots are.
19
20 This program is often used in conjunction with the *utils/profile.pl*
21 script. This script automatically instruments a program, runs it with the JIT,
22 then runs **llvm-prof** to format a report. To get more information about
23 *utils/profile.pl*, execute it with the **-help** option.
24
25
26 OPTIONS
27 -------
28
29
30
31 **--annotated-llvm** or **-A**
32
33 In addition to the normal report printed, print out the code for the
34 program, annotated with execution frequency information. This can be
35 particularly useful when trying to visualize how frequently basic blocks
36 are executed. This is most useful with basic block profiling
37 information or better.
38
39
40
41 **--print-all-code**
42
43 Using this option enables the **--annotated-llvm** option, but it
44 prints the entire module, instead of just the most commonly executed
45 functions.
46
47
48
49 **--time-passes**
50
51 Record the amount of time needed for each pass and print it to standard
52 error.
53
54
55
56
57 EXIT STATUS
58 -----------
59
60
61 **llvm-prof** returns 1 if it cannot load the bitcode file or the profile
62 information. Otherwise, it exits with zero.
0 llvm-ranlib - Generate index for LLVM archive
1 =============================================
2
3
4 SYNOPSIS
5 --------
6
7
8 **llvm-ranlib** [--version] [-help]
9
10
11 DESCRIPTION
12 -----------
13
14
15 The **llvm-ranlib** command is similar to the common Unix utility, ``ranlib``. It
16 adds or updates the symbol table in an LLVM archive file. Note that using the
17 **llvm-ar** modifier *s* is usually more efficient than running **llvm-ranlib**
18 which is only provided only for completness and compatibility. Unlike other
19 implementations of ``ranlib``, **llvm-ranlib** indexes LLVM bitcode files, not
20 native object modules. You can list the contents of the symbol table with the
21 ``llvm-nm -s`` command.
22
23
24 OPTIONS
25 -------
26
27
28
29 *archive-file*
30
31 Specifies the archive-file to which the symbol table is added or updated.
32
33
34
35 *--version*
36
37 Print the version of **llvm-ranlib** and exit without building a symbol table.
38
39
40
41 *-help*
42
43 Print usage help for **llvm-ranlib** and exit without building a symbol table.
44
45
46
47
48 EXIT STATUS
49 -----------
50
51
52 If **llvm-ranlib** succeeds, it will exit with 0. If an error occurs, a non-zero
53 exit code will be returned.
54
55
56 SEE ALSO
57 --------
58
59
60 llvm-ar|llvm-ar, ranlib(1)
0 llvm-stress - generate random .ll files
1 =======================================
2
3
4 SYNOPSIS
5 --------
6
7
8 **llvm-cov** [-gcno=filename] [-gcda=filename] [dump]
9
10
11 DESCRIPTION
12 -----------
13
14
15 The **llvm-stress** tool is used to generate random .ll files that can be used to
16 test different components of LLVM.
17
18
19 OPTIONS
20 -------
21
22
23
24 **-o** *filename*
25
26 Specify the output filename.
27
28
29
30 **-size** *size*
31
32 Specify the size of the generated .ll file.
33
34
35
36 **-seed** *seed*
37
38 Specify the seed to be used for the randomly generated instructions.
39
40
41
42
43 EXIT STATUS
44 -----------
45
46
47 **llvm-stress** returns 0.
0 opt - LLVM optimizer
1 ====================
2
3
4 SYNOPSIS
5 --------
6
7
8 **opt** [*options*] [*filename*]
9
10
11 DESCRIPTION
12 -----------
13
14
15 The **opt** command is the modular LLVM optimizer and analyzer. It takes LLVM
16 source files as input, runs the specified optimizations or analyses on it, and then
17 outputs the optimized file or the analysis results. The function of
18 **opt** depends on whether the **-analyze** option is given.
19
20 When **-analyze** is specified, **opt** performs various analyses of the input
21 source. It will usually print the results on standard output, but in a few