Reid Spencer | 28e8e42 | 2004-11-21 18:20:16 +0000 | [diff] [blame] | 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 | |
Gabor Greif | 3bd6e0d | 2007-07-09 11:24:05 +0000 | [diff] [blame] | 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 |
Reid Spencer | 8645f26 | 2007-02-09 04:12:51 +0000 | [diff] [blame] | 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 | |
Reid Spencer | ec5cf81 | 2007-07-09 05:58:08 +0000 | [diff] [blame] | 22 | The B<llvm-ld> tools attempts to mimic the interface provided by the default |
Reid Spencer | 8645f26 | 2007-02-09 04:12:51 +0000 | [diff] [blame] | 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 | |
Gabor Greif | 3bd6e0d | 2007-07-09 11:24:05 +0000 | [diff] [blame] | 50 | All object and bitcode files are linked first in the order they were |
Reid Spencer | 8645f26 | 2007-02-09 04:12:51 +0000 | [diff] [blame] | 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 | |
Gabor Greif | 3bd6e0d | 2007-07-09 11:24:05 +0000 | [diff] [blame] | 56 | Object files and static bitcode objects are always linked into the output |
Reid Spencer | 8645f26 | 2007-02-09 04:12:51 +0000 | [diff] [blame] | 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 |
Gabor Greif | 3bd6e0d | 2007-07-09 11:24:05 +0000 | [diff] [blame] | 67 | performed by converting the linked bitcode into native assembly (.s) or C code |
Reid Spencer | 8645f26 | 2007-02-09 04:12:51 +0000 | [diff] [blame] | 68 | and running the system compiler (typically gcc) on the result. |
Reid Spencer | 28e8e42 | 2004-11-21 18:20:16 +0000 | [diff] [blame] | 69 | |
| 70 | =head1 OPTIONS |
| 71 | |
Reid Spencer | 8645f26 | 2007-02-09 04:12:51 +0000 | [diff] [blame] | 72 | =head2 General Options |
| 73 | |
Reid Spencer | 4d9e7fe | 2007-02-09 04:15:08 +0000 | [diff] [blame] | 74 | =over |
| 75 | |
Reid Spencer | 8645f26 | 2007-02-09 04:12:51 +0000 | [diff] [blame] | 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 | |
Reid Spencer | 4d9e7fe | 2007-02-09 04:15:08 +0000 | [diff] [blame] | 94 | =back |
| 95 | |
Reid Spencer | 28e8e42 | 2004-11-21 18:20:16 +0000 | [diff] [blame] | 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<-l>F<name> |
| 108 | |
| 109 | This option specifies the F<name> of a library to search when resolving symbols |
| 110 | for the program. Only the base name should be specified as F<name>, without a |
| 111 | F<lib> prefix or any suffix. |
| 112 | |
| 113 | =item B<-L>F<Path> |
| 114 | |
| 115 | This option tells B<llvm-ld> to look in F<Path> to find any library subsequently |
| 116 | specified with the B<-l> option. The paths will be searched in the order in |
| 117 | which they are specified on the command line. If the library is still not found, |
| 118 | a small set of system specific directories will also be searched. Note that |
| 119 | libraries specified with the B<-l> option that occur I<before> any B<-L> options |
| 120 | will not search the paths given by the B<-L> options following it. |
| 121 | |
| 122 | =item B<-link-as-library> |
| 123 | |
Gabor Greif | 3bd6e0d | 2007-07-09 11:24:05 +0000 | [diff] [blame] | 124 | Link the bitcode files together as a library, not an executable. In this mode, |
Reid Spencer | 28e8e42 | 2004-11-21 18:20:16 +0000 | [diff] [blame] | 125 | undefined symbols will be permitted. |
| 126 | |
| 127 | =item B<-r> |
| 128 | |
| 129 | An alias for -link-as-library. |
| 130 | |
Reid Spencer | 28e8e42 | 2004-11-21 18:20:16 +0000 | [diff] [blame] | 131 | =item B<-native> |
| 132 | |
Reid Spencer | 8645f26 | 2007-02-09 04:12:51 +0000 | [diff] [blame] | 133 | Generate a native machine code executable. |
| 134 | |
Gabor Greif | 3bd6e0d | 2007-07-09 11:24:05 +0000 | [diff] [blame] | 135 | When generating native executables, B<llvm-ld> first checks for a bitcode |
Reid Spencer | 8645f26 | 2007-02-09 04:12:51 +0000 | [diff] [blame] | 136 | version of the library and links it in, if necessary. If the library is |
| 137 | missing, B<llvm-ld> skips it. Then, B<llvm-ld> links in the same |
| 138 | libraries as native code. |
| 139 | |
Gabor Greif | 3bd6e0d | 2007-07-09 11:24:05 +0000 | [diff] [blame] | 140 | In this way, B<llvm-ld> should be able to link in optimized bitcode |
Reid Spencer | 8645f26 | 2007-02-09 04:12:51 +0000 | [diff] [blame] | 141 | subsets of common libraries and then link in any part of the library that |
Gabor Greif | 3bd6e0d | 2007-07-09 11:24:05 +0000 | [diff] [blame] | 142 | hasn't been converted to bitcode. |
Reid Spencer | 28e8e42 | 2004-11-21 18:20:16 +0000 | [diff] [blame] | 143 | |
| 144 | =item B<-native-cbe> |
| 145 | |
Reid Spencer | 8645f26 | 2007-02-09 04:12:51 +0000 | [diff] [blame] | 146 | Generate a native machine code executable with the LLVM C backend. |
| 147 | |
| 148 | This option is identical to the B<-native> option, but uses the |
| 149 | C backend to generate code for the program instead of an LLVM native |
| 150 | code generator. |
Reid Spencer | 28e8e42 | 2004-11-21 18:20:16 +0000 | [diff] [blame] | 151 | |
Reid Spencer | 28e8e42 | 2004-11-21 18:20:16 +0000 | [diff] [blame] | 152 | =back |
| 153 | |
| 154 | =head2 Optimization Options |
| 155 | |
| 156 | =over |
| 157 | |
Reid Spencer | 28e8e42 | 2004-11-21 18:20:16 +0000 | [diff] [blame] | 158 | =item B<-disable-inlining> |
| 159 | |
| 160 | Do not run the inlining pass. Functions will not be inlined into other |
| 161 | functions. |
| 162 | |
| 163 | =item B<-disable-opt> |
| 164 | |
| 165 | Completely disable optimization. The various B<-On> options will be ignored and |
| 166 | no link time optimization passes will be run. |
| 167 | |
| 168 | =item B<-disable-internalize> |
| 169 | |
| 170 | Do not mark all symbols as internal. |
| 171 | |
Reid Spencer | 8645f26 | 2007-02-09 04:12:51 +0000 | [diff] [blame] | 172 | =item B<-verify-each> |
Reid Spencer | 28e8e42 | 2004-11-21 18:20:16 +0000 | [diff] [blame] | 173 | |
| 174 | Run the verification pass after each of the passes to verify intermediate |
| 175 | results. |
| 176 | |
Reid Spencer | 8645f26 | 2007-02-09 04:12:51 +0000 | [diff] [blame] | 177 | =item B<-strip-all> |
| 178 | |
| 179 | Strip all debug and symbol information from the executable to make it smaller. |
| 180 | |
| 181 | =item B<-strip-debug> |
| 182 | |
| 183 | Strip all debug information from the executable to make it smaller. |
| 184 | |
Reid Spencer | 28e8e42 | 2004-11-21 18:20:16 +0000 | [diff] [blame] | 185 | =item B<-s> |
| 186 | |
Reid Spencer | 8645f26 | 2007-02-09 04:12:51 +0000 | [diff] [blame] | 187 | An alias for B<-strip-all>. |
| 188 | |
| 189 | =item B<-S> |
| 190 | |
| 191 | An alias for B<-strip-debug>. |
Reid Spencer | 28e8e42 | 2004-11-21 18:20:16 +0000 | [diff] [blame] | 192 | |
| 193 | =item B<-export-dynamic> |
| 194 | |
Reid Spencer | 8645f26 | 2007-02-09 04:12:51 +0000 | [diff] [blame] | 195 | An alias for B<-disable-internalize> |
Reid Spencer | 28e8e42 | 2004-11-21 18:20:16 +0000 | [diff] [blame] | 196 | |
| 197 | =item B<-load> F<module> |
| 198 | |
| 199 | Load an optimization module, F<module>, which is expected to be a dynamic |
| 200 | library that provides the function name C<RunOptimizations>. This function will |
| 201 | be passed the PassManager, and the optimization level (values 0-5 based on the |
| 202 | B<-On> option). This function may add passes to the PassManager that should be |
| 203 | run. This feature allows the optimization passes of B<llvm-ld> to be extended. |
| 204 | |
Reid Spencer | fa8dab4 | 2005-12-21 05:13:06 +0000 | [diff] [blame] | 205 | =item B<-post-link-opt>F<Path> |
| 206 | |
Gabor Greif | 3bd6e0d | 2007-07-09 11:24:05 +0000 | [diff] [blame] | 207 | Run post-link optimization program. After linking is completed a bitcode file |
Reid Spencer | fa8dab4 | 2005-12-21 05:13:06 +0000 | [diff] [blame] | 208 | will be generated. It will be passed to the program specified by F<Path> as the |
| 209 | first argument. The second argument to the program will be the name of a |
| 210 | temporary file into which the program should place its optimized output. For |
| 211 | example, the "no-op optimization" would be a simple shell script: |
| 212 | |
Reid Spencer | 4d9e7fe | 2007-02-09 04:15:08 +0000 | [diff] [blame] | 213 | #!/bin/bash |
| 214 | cp $1 $2 |
Reid Spencer | fa8dab4 | 2005-12-21 05:13:06 +0000 | [diff] [blame] | 215 | |
| 216 | =back |
| 217 | |
Reid Spencer | 28e8e42 | 2004-11-21 18:20:16 +0000 | [diff] [blame] | 218 | =head1 EXIT STATUS |
| 219 | |
| 220 | If B<llvm-ld> succeeds, it will exit with 0 return code. If an error occurs, |
| 221 | it will exit with a non-zero return code. |
| 222 | |
Reid Spencer | f8d3e4a | 2004-11-29 03:43:29 +0000 | [diff] [blame] | 223 | =head1 ENVIRONMENT |
| 224 | |
Gabor Greif | 3bd6e0d | 2007-07-09 11:24:05 +0000 | [diff] [blame] | 225 | The C<LLVM_LIB_SEARCH_PATH> environment variable is used to find bitcode |
Reid Spencer | f8d3e4a | 2004-11-29 03:43:29 +0000 | [diff] [blame] | 226 | libraries. Any paths specified in this variable will be searched after the C<-L> |
| 227 | options. |
| 228 | |
Reid Spencer | 28e8e42 | 2004-11-21 18:20:16 +0000 | [diff] [blame] | 229 | =head1 SEE ALSO |
| 230 | |
Reid Spencer | 8645f26 | 2007-02-09 04:12:51 +0000 | [diff] [blame] | 231 | L<llvm-link|llvm-link> |
Reid Spencer | 28e8e42 | 2004-11-21 18:20:16 +0000 | [diff] [blame] | 232 | |
| 233 | =head1 AUTHORS |
| 234 | |
Reid Spencer | cd143fc | 2006-03-14 05:42:07 +0000 | [diff] [blame] | 235 | Maintained by the LLVM Team (L<http://llvm.org>). |
Reid Spencer | 28e8e42 | 2004-11-21 18:20:16 +0000 | [diff] [blame] | 236 | |
| 237 | =cut |