aboutsummaryrefslogtreecommitdiffstats
path: root/docs/CommandGuide/llvmc.pod
blob: d237ca4c14fa41261f09ddd1f8e71cf229eb562a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
=pod

=head1 NAME

llvmc - The LLVM Compiler Driver (WIP)

=head1 SYNOPSIS

B<llvmc> [I<options>] I<filenames...>

=head1 DESCRIPTION

B<llvmc> is a configurable driver for invoking other LLVM (and non-LLVM) tools
in order to compile, optimize and link software for multiple languages. For
those familiar with FSF's B<gcc> tool, it is very similar.  Please note that
B<llvmc> is considered an experimental tool.

=head1 OPTIONS

=head2 Built-in Options

LLVMC has some built-in options that can't be overridden in the
configuration libraries.

=over

=item B<-o> I<filename>

Output file name.

=item B<-x> I<language>

Specify the language of the following input files until the next B<-x>
option.

=item B<-load> I<plugin_name>

Load the specified plugin DLL. Example:
S<-load $LLVM_DIR/Release/lib/LLVMCSimple.so>.

=item B<-v> or B<--verbose>

Enable verbose mode, i.e. print out all executed commands.

=item B<--check-graph>

Check the compilation for common errors like mismatched output/input language
names, multiple default edges and cycles. Because of plugins, these checks can't
be performed at compile-time. Exit with code zero if no errors were found, and
return the number of found errors otherwise. Hidden option, useful for debugging
LLVMC plugins.

=item B<--view-graph>

Show a graphical representation of the compilation graph and exit. Requires that
you have I<dot> and I<gv> programs installed. Hidden option, useful for
debugging LLVMC plugins.

=item B<--write-graph>

Write a I<compilation-graph.dot> file in the current directory with the
compilation graph description in Graphviz format (identical to the file used by
the B<--view-graph> option). The B<-o> option can be used to set the output file
name. Hidden option, useful for debugging LLVMC plugins.

=item B<--save-temps>

Write temporary files to the current directory and do not delete them on
exit. This option can also take an argument: the I<--save-temps=obj> switch will
write files into the directory specified with the I<-o> option. The
I<--save-temps=cwd> and I<--save-temps> switches are both synonyms for the
default behaviour.

=item B<--temp-dir> I<directory>

Store temporary files in the given directory. This directory is deleted on exit
unless I<--save-temps> is specified. If I<--save-temps=obj> is also specified,
I<--temp-dir> is given the precedence.

=item B<-help>

Print a summary of command-line options and exit.

=item B<-help-hidden>

Print a summary of command-line options and exit. Print help even for
options intended for developers.

=item B<--version>

Print version information and exit.

=item B<@>I<file>

Read command-line options from I<file>. The options read are inserted
in place of the original @I<file> option. If I<file> does not exist, or
cannot be read, then the option will be treated literally, and not
removed.

Options in I<file> are separated by whitespace. A whitespace character
may be included in an option by surrounding the entire option in
either single or double quotes. Any character (including a backslash)
may be included by prefixing the character to be included with a
backslash. The file may itself contain additional @I<file> options;
any such options will be processed recursively.


=back


=head2 Control Options

By default, LLVMC is built with some standard configuration libraries
that define the following options:

=over

=item B<-clang>

Use Clang instead of llvm-gcc.

=item B<-opt>

Enable optimization passes with B<opt>. To pass options to the B<opt> program
use the B<-Wo,> option.

=item B<-I> I<directory>

Add a directory to the header file search path.

=item B<-L> I<directory>

Add I<directory> to the library search path.

=item B<-F> I<directory>

Add I<directory> to the framework search path.

=item B<-l>I<name>

Link in the library libI<name>.[bc | a | so].  This library should
be a bitcode library.

=item B<-framework> I<name>

Link in the library libI<name>.[bc | a | so].  This library should
be a bitcode library.

=item B<-emit-llvm>

Output LLVM bitcode (with B<-c>) or assembly (with B<-S>) instead of native
object (or assembly).  If B<-emit-llvm> is given without either B<-c> or B<-S>
it has no effect.

=item B<-Wa>

Pass options to assembler.

=item B<-Wl>

Pass options to linker.

=item B<-Wo>

Pass options to opt.

=item B<-Wllc>

Pass options to llc (code generator).

=back

=head1 EXIT STATUS

If B<llvmc> succeeds, it will exit with code 0.  Otherwise, if an
error occurs, it will exit with a non-zero value. If one of the
compilation tools returns a non-zero status, pending actions will be
discarded and B<llvmc> will return the same result code as the failing
compilation tool.

=head1 SEE ALSO

L<llvm-gcc|llvmgcc>, L<llvm-g++|llvmgxx>, L<llvm-as|llvm-as>,
L<llvm-dis|llvm-dis>, L<llc|llc>, L<llvm-link|llvm-link>

=head1 AUTHORS

Maintained by the LLVM Team (L<http://llvm.org>).

=cut