docs/CommandGuide/llvmc.pod

=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.  This option can be
repeated.

=item B<-L> I<directory>

Add I<directory> to the library search path.  This option can be
repeated.

=item B<-l>I<name>

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

=item B<-emit-llvm>

Make the output be 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.

=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