=head1 NAME
-llvmc - The LLVM Compiler Driver
+llvmc - The LLVM Compiler Driver (experimental)
=head1 SYNOPSIS
=head1 DESCRIPTION
-The B<llvmc> command 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 the GNU Compiler
-Collection's B<gcc> tool, it is very similar. This tool has the
-following main goals or purposes:
+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. B<llvmc> has the following goals:
=over
-=item * A Single point of access to the LLVM tool set.
+=item * provide a single point of access to the LLVM tool set,
-=item * Hide the complexities of the LLVM tools through a single interface.
+=item * hide the complexities of the LLVM tools through a single interface,
-=item * Make integration of existing non-LLVM tools simple.
+=item * make integration of existing non-LLVM tools simple,
-=item * Extend the capabilities of minimal front ends.
+=item * extend the capabilities of minimal front ends, and
-=item * Make the interface for compiling consistent for all languages.
+=item * make the interface for compiling consistent for all languages.
=back
=item * Pre-processing: gathering/filtering compiler input (optional).
-=item * Translation: source language to bytecode conversion.
+=item * Translation: source language to bitcode conversion.
-=item * Assembly: bytecode to native code conversion.
+=item * Assembly: bitcode to native code conversion.
-=item * Optimization: conversion of bytecode to something that runs faster.
+=item * Optimization: conversion of bitcode to something that runs faster.
-=item * Linking: combining multiple bytecodes to produce executable program.
+=item * Linking: combining multiple bitcode files to produce executable program.
=back
This option specifies that the linking phase is not to be run. All
previous phases, if applicable will run. This is generally how a given
-bytecode file is compiled and optimized for a source language module.
+bitcode file is compiled and optimized for a source language module.
=item B<-k> or B<--link> or default
specified on the command line will be compiled and linked with objects and
libraries also specified.
-=item B<-S> or B<--assemble>
+=item B<-S>
This option specifies that compilation should end in the creation of
an LLVM assembly file that can be later converted to an LLVM object
file.
-=item B<-E> or B<--preprocess>
+=item B<-E>
This option specifies that no compilation or linking should be
performed. Only pre-processing, if applicable to the language being
This level of optimization specifies a balance between generating good code
that will execute reasonably quickly and not spending too much time optimizing
the code to get there. For example, this level of optimization may include
-things like global common subexpression elimination, aggressive dead code
+things like global common sub-expression elimination, aggressive dead code
elimination, and scalar replication.
=item B<-O3> (aggressive optimization)
This is the same as B<-O5> except that it employs profile-guided
re-optimization of the program after it has executed. Note that this implies
-a single level of re-optimization based on runtime profile analysis. Once
+a single level of re-optimization based on run time profile analysis. Once
the re-optimization has completed, the profiling instrumentation is
removed and final optimizations are employed.
=item B<--native>
-Normally, B<llvmc> produces bytecode files at most stages of compilation.
+Normally, B<llvmc> produces bitcode files at most stages of compilation.
With this option, B<llvmc> will arrange for native object files to be
generated with the B<-c> option, native assembly files to be generated
with the B<-S> option, and native executables to be generated with the
=over
-=item B<-T,pp>=I<options>
+=item B<-T,pre>=I<options>
Pass an arbitrary option to the pre-processor.
Pass an arbitrary option to the optimizer.
-=item B<-T,link>=I<options>
+=item B<-T,lnk>=I<options>
Pass an arbitrary option to the linker.
=back
-=head3 C/C++ Specific Options
+=head2 C/C++ Specific Options
=over
This option is just passed through to a C or C++ front end compiler to tell it
where include files can be found.
+=item B<-D>F<symbol>
+
+This option is just passed through to a C or C++ front end compiler to tell it
+to define a symbol.
+
=back
=head2 Miscellaneous Options
=over
+=item B<--config-dir> F<dirname>
+
+This option tells B<llvmc> to read configuration data from the I<directory>
+named F<dirname>. Data from such directories will be read in the order
+specified on the command line after all other standard configuration files have
+been read. This allows users or groups of users to conveniently create
+their own configuration directories in addition to the standard ones to which
+they may not have write access.
+
+=back
+
+
+=head2 Unimplemented Options
+
+The options below are not currently implemented in B<llvmc> but will be
+eventually. They are documented here as "future design".
+
+=over
+
=item B<--show-config> I<[suffixes...]>
When this option is given, the only action taken by B<llvmc> is to show its
a configuration item on the command line without resorting to changing the
configuration files.
-=item B<--config-dir> F<dirname>
-
-This option tells B<llvmc> to read configuration data from the I<directory>
-named F<dirname>. Data from such directories will be read in the order
-specified on the command line after all other standard configuration files have
-been read. This allows users or groups of users to conveniently create
-their own configuration directories in addition to the standard ones to which
-they may not have write access.
-
=item B<--config-only-from> F<dirname>
This option tells B<llvmc> to skip the normal processing of configuration
status, pending actions will be discarded and B<llvmc> will return the
same result code as the failing compilation tool.
+=head1 DEFICIENCIES
+
+B<llvmc> is considered an experimental LLVM tool because it has these
+deficiencies:
+
+=over
+
+=item Insufficient support for native linking
+
+Because B<llvm-ld> doesn't handle native linking, neither can B<llvmc>
+
+=item Poor configuration support
+
+The support for configuring new languages, etc. is weak. There are many
+command line configurations that cannot be achieved with the current
+support. Furthermore the grammar is cumbersome for configuration files.
+Please see L<http://llvm.org/PR686> for further details.
+
+=item Does not handle target specific configurations
+
+This is one of the major deficiencies, also addressed in
+L<http://llvm.org/PR686>
+
+=back
+
=head1 SEE ALSO
-L<gccas|gccas>, L<gccld|gccld>, L<llvm-as|llvm-as>, L<llvm-dis|llvm-dis>,
-L<llc|llc>, L<llvm-link|llvm-link>
+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.cs.uiuc.edu>).
+Maintained by the LLVM Team (L<http://llvm.org>).
=cut
projects / oota-llvm.git / blobdiff