docs/CommandGuide/llvmc.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 llvmc - The LLVM Compiler Driver (WIP)
   6
   7 =head1 SYNOPSIS
   8
   9 B<llvmc> [I<options>] I<filenames...>
  10
  11 =head1 DESCRIPTION
  12
  13 B<llvmc> is a configurable driver for invoking other LLVM (and non-LLVM) tools
  14 in order to compile, optimize and link software for multiple languages. For
  15 those familiar with FSF's B<gcc> tool, it is very similar.  Please note that
  16 B<llvmc> is considered an experimental tool.
  17
  18 =head1 OPTIONS
  19
  20 =head2 Built-in Options
  21
  22 LLVMC has some built-in options that can't be overridden in the
  23 configuration libraries.
  24
  25 =over
  26
  27 =item B<-o> I<filename>
  28
  29 Output file name.
  30
  31 =item B<-x> I<language>
  32
  33 Specify the language of the following input files until the next B<-x>
  34 option.
  35
  36 =item B<-load> I<plugin_name>
  37
  38 Load the specified plugin DLL. Example:
  39 S<-load $LLVM_DIR/Release/lib/LLVMCSimple.so>.
  40
  41 =item B<-v> or B<--verbose>
  42
  43 Enable verbose mode, i.e. print out all executed commands.
  44
  45 =item B<--check-graph>
  46
  47 Check the compilation for common errors like mismatched output/input language
  48 names, multiple default edges and cycles. Because of plugins, these checks can't
  49 be performed at compile-time. Exit with code zero if no errors were found, and
  50 return the number of found errors otherwise. Hidden option, useful for debugging
  51 LLVMC plugins.
  52
  53 =item B<--view-graph>
  54
  55 Show a graphical representation of the compilation graph and exit. Requires that
  56 you have I<dot> and I<gv> programs installed. Hidden option, useful for
  57 debugging LLVMC plugins.
  58
  59 =item B<--write-graph>
  60
  61 Write a I<compilation-graph.dot> file in the current directory with the
  62 compilation graph description in Graphviz format (identical to the file used by
  63 the B<--view-graph> option). The B<-o> option can be used to set the output file
  64 name. Hidden option, useful for debugging LLVMC plugins.
  65
  66 =item B<--save-temps>
  67
  68 Write temporary files to the current directory and do not delete them on
  69 exit. This option can also take an argument: the I<--save-temps=obj> switch will
  70 write files into the directory specified with the I<-o> option. The
  71 I<--save-temps=cwd> and I<--save-temps> switches are both synonyms for the
  72 default behaviour.
  73
  74 =item B<--temp-dir> I<directory>
  75
  76 Store temporary files in the given directory. This directory is deleted on exit
  77 unless I<--save-temps> is specified. If I<--save-temps=obj> is also specified,
  78 I<--temp-dir> is given the precedence.
  79
  80 =item B<-help>
  81
  82 Print a summary of command-line options and exit.
  83
  84 =item B<-help-hidden>
  85
  86 Print a summary of command-line options and exit. Print help even for
  87 options intended for developers.
  88
  89 =item B<--version>
  90
  91 Print version information and exit.
  92
  93 =item B<@>I<file>
  94
  95 Read command-line options from I<file>. The options read are inserted
  96 in place of the original @I<file> option. If I<file> does not exist, or
  97 cannot be read, then the option will be treated literally, and not
  98 removed.
  99
 100 Options in I<file> are separated by whitespace. A whitespace character
 101 may be included in an option by surrounding the entire option in
 102 either single or double quotes. Any character (including a backslash)
 103 may be included by prefixing the character to be included with a
 104 backslash. The file may itself contain additional @I<file> options;
 105 any such options will be processed recursively.
 106
 107
 108 =back
 109
 110
 111 =head2 Control Options
 112
 113 By default, LLVMC is built with some standard configuration libraries
 114 that define the following options:
 115
 116 =over
 117
 118 =item B<-clang>
 119
 120 Use Clang instead of llvm-gcc.
 121
 122 =item B<-opt>
 123
 124 Enable optimization passes with B<opt>. To pass options to the B<opt> program
 125 use the B<-Wo,> option.
 126
 127 =item B<-I> I<directory>
 128
 129 Add a directory to the header file search path.
 130
 131 =item B<-L> I<directory>
 132
 133 Add I<directory> to the library search path.
 134
 135 =item B<-F> I<directory>
 136
 137 Add I<directory> to the framework search path.
 138
 139 =item B<-l>I<name>
 140
 141 Link in the library libI<name>.[bc | a | so].  This library should
 142 be a bitcode library.
 143
 144 =item B<-framework> I<name>
 145
 146 Link in the library libI<name>.[bc | a | so].  This library should
 147 be a bitcode library.
 148
 149 =item B<-emit-llvm>
 150
 151 Output LLVM bitcode (with B<-c>) or assembly (with B<-S>) instead of native
 152 object (or assembly).  If B<-emit-llvm> is given without either B<-c> or B<-S>
 153 it has no effect.
 154
 155 =item B<-Wa>
 156
 157 Pass options to assembler.
 158
 159 =item B<-Wl>
 160
 161 Pass options to linker.
 162
 163 =item B<-Wo>
 164
 165 Pass options to opt.
 166
 167 =item B<-Wllc>
 168
 169 Pass options to llc (code generator).
 170
 171 =back
 172
 173 =head1 EXIT STATUS
 174
 175 If B<llvmc> succeeds, it will exit with code 0.  Otherwise, if an
 176 error occurs, it will exit with a non-zero value. If one of the
 177 compilation tools returns a non-zero status, pending actions will be
 178 discarded and B<llvmc> will return the same result code as the failing
 179 compilation tool.
 180
 181 =head1 SEE ALSO
 182
 183 L<llvm-gcc|llvmgcc>, L<llvm-g++|llvmgxx>, L<llvm-as|llvm-as>,
 184 L<llvm-dis|llvm-dis>, L<llc|llc>, L<llvm-link|llvm-link>
 185
 186 =head1 AUTHORS
 187
 188 Maintained by the LLVM Team (L<http://llvm.org>).
 189
 190 =cut