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 | |
| 13 | The B<llvm-ld> command is similar to the common Unix utility, C<ld>. It |
| 14 | links together bytecode modules to produce an executable program. |
| 15 | |
| 16 | =head1 OPTIONS |
| 17 | |
| 18 | =head2 Input/Output Options |
| 19 | |
| 20 | =over |
| 21 | |
| 22 | =item B<-o> F<filename> |
| 23 | |
| 24 | This overrides the default output file and specifies the name of the file that |
| 25 | should be generated by the linker. By default, B<llvm-ld> generates a file named |
| 26 | F<a.out> for compatibility with B<ld>. The output will be written to |
| 27 | F<filename>. |
| 28 | |
| 29 | =item B<-l>F<name> |
| 30 | |
| 31 | This option specifies the F<name> of a library to search when resolving symbols |
| 32 | for the program. Only the base name should be specified as F<name>, without a |
| 33 | F<lib> prefix or any suffix. |
| 34 | |
| 35 | =item B<-L>F<Path> |
| 36 | |
| 37 | This option tells B<llvm-ld> to look in F<Path> to find any library subsequently |
| 38 | specified with the B<-l> option. The paths will be searched in the order in |
| 39 | which they are specified on the command line. If the library is still not found, |
| 40 | a small set of system specific directories will also be searched. Note that |
| 41 | libraries specified with the B<-l> option that occur I<before> any B<-L> options |
| 42 | will not search the paths given by the B<-L> options following it. |
| 43 | |
| 44 | =item B<-link-as-library> |
| 45 | |
| 46 | Link the bytecode files together as a library, not an executable. In this mode, |
| 47 | undefined symbols will be permitted. |
| 48 | |
| 49 | =item B<-r> |
| 50 | |
| 51 | An alias for -link-as-library. |
| 52 | |
| 53 | =item B<-march=>C<target> |
| 54 | |
| 55 | Specifies the kind of machine for which code or assembly should be generated. |
| 56 | |
| 57 | =item B<-native> |
| 58 | |
| 59 | Generate a native binary instead of a shell script that runs the JIT from |
| 60 | bytecode. |
| 61 | |
| 62 | =item B<-native-cbe> |
| 63 | |
| 64 | Generate a native binary with the C back end and compilation with GCC. |
| 65 | |
| 66 | =item B<-disable-compression> |
| 67 | |
| 68 | Do not compress bytecode files. |
| 69 | |
| 70 | =back |
| 71 | |
| 72 | =head2 Optimization Options |
| 73 | |
| 74 | =over |
| 75 | |
| 76 | =item B<-O0> |
| 77 | |
| 78 | An alias for the -O1 option. |
| 79 | |
| 80 | =item B<-O1> |
| 81 | |
| 82 | Optimize for linking speed, not execution speed. The optimizer will attempt to |
| 83 | reduce the size of the linked program to reduce I/O but will not otherwise |
| 84 | perform any link-time optimizations. |
| 85 | |
| 86 | =item B<-O2> |
| 87 | |
| 88 | Perform only the minimal or required set of scalar optimizations. |
| 89 | |
| 90 | =item B<-03> |
| 91 | |
| 92 | An alias for the -O2 option. |
| 93 | |
| 94 | =item B<-04> |
| 95 | |
| 96 | Perform the standard link time inter-procedural optimizations. This will |
| 97 | attempt to optimize the program taking the entire program into consideration. |
| 98 | |
| 99 | =item B<-O5> |
| 100 | |
| 101 | Perform aggressive link time optimizations. This is the same as -O4 but works |
| 102 | more aggressively to optimize the program. |
| 103 | |
| 104 | =item B<-disable-inlining> |
| 105 | |
| 106 | Do not run the inlining pass. Functions will not be inlined into other |
| 107 | functions. |
| 108 | |
| 109 | =item B<-disable-opt> |
| 110 | |
| 111 | Completely disable optimization. The various B<-On> options will be ignored and |
| 112 | no link time optimization passes will be run. |
| 113 | |
| 114 | =item B<-disable-internalize> |
| 115 | |
| 116 | Do not mark all symbols as internal. |
| 117 | |
| 118 | =item B<-verify> |
| 119 | |
| 120 | Run the verification pass after each of the passes to verify intermediate |
| 121 | results. |
| 122 | |
| 123 | =item B<-s> |
| 124 | |
| 125 | Strip symbol info from the executable to make it smaller. |
| 126 | |
| 127 | =item B<-export-dynamic> |
| 128 | |
| 129 | An alias for -disable-internalize |
| 130 | |
| 131 | =item B<-load> F<module> |
| 132 | |
| 133 | Load an optimization module, F<module>, which is expected to be a dynamic |
| 134 | library that provides the function name C<RunOptimizations>. This function will |
| 135 | be passed the PassManager, and the optimization level (values 0-5 based on the |
| 136 | B<-On> option). This function may add passes to the PassManager that should be |
| 137 | run. This feature allows the optimization passes of B<llvm-ld> to be extended. |
| 138 | |
Reid Spencer | fa8dab4 | 2005-12-21 05:13:06 +0000 | [diff] [blame^] | 139 | =item B<-post-link-opt>F<Path> |
| 140 | |
| 141 | Run post-link optimization program. After linking is completed a bytecode file |
| 142 | will be generated. It will be passed to the program specified by F<Path> as the |
| 143 | first argument. The second argument to the program will be the name of a |
| 144 | temporary file into which the program should place its optimized output. For |
| 145 | example, the "no-op optimization" would be a simple shell script: |
| 146 | |
| 147 | =over |
| 148 | |
| 149 | #!/bin/bash |
| 150 | cp $1 $2 |
| 151 | |
| 152 | =back |
| 153 | |
Reid Spencer | 28e8e42 | 2004-11-21 18:20:16 +0000 | [diff] [blame] | 154 | =back |
| 155 | |
| 156 | =head2 Miscellaneous Options |
| 157 | |
Reid Spencer | f8d3e4a | 2004-11-29 03:43:29 +0000 | [diff] [blame] | 158 | =over |
| 159 | |
Reid Spencer | 28e8e42 | 2004-11-21 18:20:16 +0000 | [diff] [blame] | 160 | =item B<-v> |
| 161 | |
| 162 | Specifies verbose mode. In this mode the linker will print additional |
| 163 | information about the actions it takes, programs it executes, etc. |
| 164 | |
Reid Spencer | f8d3e4a | 2004-11-29 03:43:29 +0000 | [diff] [blame] | 165 | =back |
| 166 | |
Reid Spencer | 28e8e42 | 2004-11-21 18:20:16 +0000 | [diff] [blame] | 167 | =head1 EXIT STATUS |
| 168 | |
| 169 | If B<llvm-ld> succeeds, it will exit with 0 return code. If an error occurs, |
| 170 | it will exit with a non-zero return code. |
| 171 | |
Reid Spencer | f8d3e4a | 2004-11-29 03:43:29 +0000 | [diff] [blame] | 172 | =head1 ENVIRONMENT |
| 173 | |
| 174 | The C<LLVM_LIB_SEARCH_PATH> environment variable is used to find bytecode |
| 175 | libraries. Any paths specified in this variable will be searched after the C<-L> |
| 176 | options. |
| 177 | |
Reid Spencer | 28e8e42 | 2004-11-21 18:20:16 +0000 | [diff] [blame] | 178 | =head1 SEE ALSO |
| 179 | |
| 180 | L<llvm-ar|llvm-ar> |
| 181 | |
| 182 | =head1 AUTHORS |
| 183 | |
| 184 | Maintained by the LLVM Team (L<http://llvm.cs.uiuc.edu>). |
| 185 | |
| 186 | =cut |