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