1=pod 2 3=head1 NAME 4 5llvm-ld - LLVM linker 6 7=head1 SYNOPSIS 8 9B<llvm-ld> <options> <files> 10 11=head1 DESCRIPTION 12 13The B<llvm-ld> tool takes a set of LLVM bitcode files and links them 14together into a single LLVM bitcode file. The output bitcode file can be 15another bitcode file or an executable bitcode program. Using additional 16options, B<llvm-ld> is able to produce native code executables. 17 18The B<llvm-ld> tool is the main linker for LLVM. It is used to link together 19the output of LLVM front-end compilers and run "link time" optimizations (mostly 20the inter-procedural kind). 21 22The B<llvm-ld> tools attempts to mimic the interface provided by the default 23system linker so that it can act as a I<drop-in> replacement. 24 25=head2 Search Order 26 27When looking for objects specified on the command line, B<llvm-ld> will search 28for the object first in the current directory and then in the directory 29specified by the B<LLVM_LIB_SEARCH_PATH> environment variable. If it cannot 30find the object, it fails. 31 32When looking for a library specified with the B<-l> option, B<llvm-ld> first 33attempts to load a file with that name from the current directory. If that 34fails, it looks for libI<library>.bc, libI<library>.a, or libI<library>.I<shared 35library extension>, in that order, in each directory added to the library search 36path with the B<-L> option. These directories are searched in the order they 37are specified. If the library cannot be located, then B<llvm-ld> looks in the 38directory specified by the B<LLVM_LIB_SEARCH_PATH> environment variable. If it 39does not find a library there, it fails. 40 41The I<shared library extension> may be I<.so>, I<.dyld>, I<.dll>, or something 42different, depending upon the system. 43 44The B<-L> option is global. It does not matter where it is specified in the 45list of command line arguments; the directory is simply added to the search path 46and is applied to all libraries, preceding or succeeding, in the command line. 47 48=head2 Link order 49 50All object and bitcode files are linked first in the order they were 51specified on the command line. All library files are linked next. 52Some libraries may not be linked into the object program; see below. 53 54=head2 Library Linkage 55 56Object files and static bitcode objects are always linked into the output 57file. Library archives (.a files) load only the objects within the archive 58that define symbols needed by the output file. Hence, libraries should be 59listed after the object files and libraries which need them; otherwise, the 60library may not be linked in, and the dependent library will not have its 61undefined symbols defined. 62 63=head2 Native code generation 64 65The B<llvm-ld> program has limited support for native code generation, when 66using the B<-native> or B<-native-cbe> options. Native code generation is 67performed by converting the linked bitcode into native assembly (.s) or C code 68and running the system compiler (typically gcc) on the result. 69 70=head1 OPTIONS 71 72=head2 General Options 73 74=over 75 76=item B<-help> 77 78Print a summary of command line options. 79 80=item B<-v> 81 82Specifies verbose mode. In this mode the linker will print additional 83information about the actions it takes, programs it executes, etc. 84 85=item B<-stats> 86 87Print statistics. 88 89=item B<-time-passes> 90 91Record the amount of time needed for each pass and print it to standard 92error. 93 94=back 95 96=head2 Input/Output Options 97 98=over 99 100=item B<-o> F<filename> 101 102This overrides the default output file and specifies the name of the file that 103should be generated by the linker. By default, B<llvm-ld> generates a file named 104F<a.out> for compatibility with B<ld>. The output will be written to 105F<filename>. 106 107=item B<-b> F<filename> 108 109This option can be used to override the output bitcode file name. By default, 110the name of the bitcode output file is one more ".bc" suffix added to the name 111specified by B<-o filename> option. 112 113=item B<-l>F<name> 114 115This option specifies the F<name> of a library to search when resolving symbols 116for the program. Only the base name should be specified as F<name>, without a 117F<lib> prefix or any suffix. 118 119=item B<-L>F<Path> 120 121This option tells B<llvm-ld> to look in F<Path> to find any library subsequently 122specified with the B<-l> option. The paths will be searched in the order in 123which they are specified on the command line. If the library is still not found, 124a small set of system specific directories will also be searched. Note that 125libraries specified with the B<-l> option that occur I<before> any B<-L> options 126will not search the paths given by the B<-L> options following it. 127 128=item B<-link-as-library> 129 130Link the bitcode files together as a library, not an executable. In this mode, 131undefined symbols will be permitted. 132 133=item B<-r> 134 135An alias for -link-as-library. 136 137=item B<-native> 138 139Generate a native machine code executable. 140 141When generating native executables, B<llvm-ld> first checks for a bitcode 142version of the library and links it in, if necessary. If the library is 143missing, B<llvm-ld> skips it. Then, B<llvm-ld> links in the same 144libraries as native code. 145 146In this way, B<llvm-ld> should be able to link in optimized bitcode 147subsets of common libraries and then link in any part of the library that 148hasn't been converted to bitcode. 149 150=item B<-native-cbe> 151 152Generate a native machine code executable with the LLVM C backend. 153 154This option is identical to the B<-native> option, but uses the 155C backend to generate code for the program instead of an LLVM native 156code generator. 157 158=back 159 160=head2 Optimization Options 161 162=over 163 164=item B<-disable-inlining> 165 166Do not run the inlining pass. Functions will not be inlined into other 167functions. 168 169=item B<-disable-opt> 170 171Completely disable optimization. 172 173=item B<-disable-internalize> 174 175Do not mark all symbols as internal. 176 177=item B<-verify-each> 178 179Run the verification pass after each of the passes to verify intermediate 180results. 181 182=item B<-strip-all> 183 184Strip all debug and symbol information from the executable to make it smaller. 185 186=item B<-strip-debug> 187 188Strip all debug information from the executable to make it smaller. 189 190=item B<-s> 191 192An alias for B<-strip-all>. 193 194=item B<-S> 195 196An alias for B<-strip-debug>. 197 198=item B<-export-dynamic> 199 200An alias for B<-disable-internalize> 201 202=item B<-post-link-opt>F<Path> 203 204Run post-link optimization program. After linking is completed a bitcode file 205will be generated. It will be passed to the program specified by F<Path> as the 206first argument. The second argument to the program will be the name of a 207temporary file into which the program should place its optimized output. For 208example, the "no-op optimization" would be a simple shell script: 209 210 #!/bin/bash 211 cp $1 $2 212 213=back 214 215=head1 EXIT STATUS 216 217If B<llvm-ld> succeeds, it will exit with 0 return code. If an error occurs, 218it will exit with a non-zero return code. 219 220=head1 ENVIRONMENT 221 222The C<LLVM_LIB_SEARCH_PATH> environment variable is used to find bitcode 223libraries. Any paths specified in this variable will be searched after the C<-L> 224options. 225 226=head1 SEE ALSO 227 228L<llvm-link|llvm-link> 229 230=head1 AUTHORS 231 232Maintained by the LLVM Team (L<http://llvm.org/>). 233 234=cut 235