| =pod | |
| =head1 NAME | |
| llvm-ld - LLVM linker | |
| =head1 SYNOPSIS | |
| B<llvm-ld> <options> <files> | |
| =head1 DESCRIPTION | |
| The B<llvm-ld> tool takes a set of LLVM bitcode files and links them | |
| together into a single LLVM bitcode file. The output bitcode file can be | |
| another bitcode file or an executable bitcode program. Using additional | |
| options, B<llvm-ld> is able to produce native code executables. | |
| The B<llvm-ld> tool is the main linker for LLVM. It is used to link together | |
| the output of LLVM front-end compilers and run "link time" optimizations (mostly | |
| the inter-procedural kind). | |
| The B<llvm-ld> tools attempts to mimic the interface provided by the default | |
| system linker so that it can act as a I<drop-in> replacement. | |
| =head2 Search Order | |
| When looking for objects specified on the command line, B<llvm-ld> will search | |
| for the object first in the current directory and then in the directory | |
| specified by the B<LLVM_LIB_SEARCH_PATH> environment variable. If it cannot | |
| find the object, it fails. | |
| When looking for a library specified with the B<-l> option, B<llvm-ld> first | |
| attempts to load a file with that name from the current directory. If that | |
| fails, it looks for libI<library>.bc, libI<library>.a, or libI<library>.I<shared | |
| library extension>, in that order, in each directory added to the library search | |
| path with the B<-L> option. These directories are searched in the order they | |
| are specified. If the library cannot be located, then B<llvm-ld> looks in the | |
| directory specified by the B<LLVM_LIB_SEARCH_PATH> environment variable. If it | |
| does not find a library there, it fails. | |
| The I<shared library extension> may be I<.so>, I<.dyld>, I<.dll>, or something | |
| different, depending upon the system. | |
| The B<-L> option is global. It does not matter where it is specified in the | |
| list of command line arguments; the directory is simply added to the search path | |
| and is applied to all libraries, preceding or succeeding, in the command line. | |
| =head2 Link order | |
| All object and bitcode files are linked first in the order they were | |
| specified on the command line. All library files are linked next. | |
| Some libraries may not be linked into the object program; see below. | |
| =head2 Library Linkage | |
| Object files and static bitcode objects are always linked into the output | |
| file. Library archives (.a files) load only the objects within the archive | |
| that define symbols needed by the output file. Hence, libraries should be | |
| listed after the object files and libraries which need them; otherwise, the | |
| library may not be linked in, and the dependent library will not have its | |
| undefined symbols defined. | |
| =head2 Native code generation | |
| The B<llvm-ld> program has limited support for native code generation, when | |
| using the B<-native> or B<-native-cbe> options. Native code generation is | |
| performed by converting the linked bitcode into native assembly (.s) or C code | |
| and running the system compiler (typically gcc) on the result. | |
| =head1 OPTIONS | |
| =head2 General Options | |
| =over | |
| =item B<-help> | |
| Print a summary of command line options. | |
| =item B<-v> | |
| Specifies verbose mode. In this mode the linker will print additional | |
| information about the actions it takes, programs it executes, etc. | |
| =item B<-stats> | |
| Print statistics. | |
| =item B<-time-passes> | |
| Record the amount of time needed for each pass and print it to standard | |
| error. | |
| =back | |
| =head2 Input/Output Options | |
| =over | |
| =item B<-o> F<filename> | |
| This overrides the default output file and specifies the name of the file that | |
| should be generated by the linker. By default, B<llvm-ld> generates a file named | |
| F<a.out> for compatibility with B<ld>. The output will be written to | |
| F<filename>. | |
| =item B<-b> F<filename> | |
| This option can be used to override the output bitcode file name. By default, | |
| the name of the bitcode output file is one more ".bc" suffix added to the name | |
| specified by B<-o filename> option. | |
| =item B<-l>F<name> | |
| This option specifies the F<name> of a library to search when resolving symbols | |
| for the program. Only the base name should be specified as F<name>, without a | |
| F<lib> prefix or any suffix. | |
| =item B<-L>F<Path> | |
| This option tells B<llvm-ld> to look in F<Path> to find any library subsequently | |
| specified with the B<-l> option. The paths will be searched in the order in | |
| which they are specified on the command line. If the library is still not found, | |
| a small set of system specific directories will also be searched. Note that | |
| libraries specified with the B<-l> option that occur I<before> any B<-L> options | |
| will not search the paths given by the B<-L> options following it. | |
| =item B<-link-as-library> | |
| Link the bitcode files together as a library, not an executable. In this mode, | |
| undefined symbols will be permitted. | |
| =item B<-r> | |
| An alias for -link-as-library. | |
| =item B<-native> | |
| Generate a native machine code executable. | |
| When generating native executables, B<llvm-ld> first checks for a bitcode | |
| version of the library and links it in, if necessary. If the library is | |
| missing, B<llvm-ld> skips it. Then, B<llvm-ld> links in the same | |
| libraries as native code. | |
| In this way, B<llvm-ld> should be able to link in optimized bitcode | |
| subsets of common libraries and then link in any part of the library that | |
| hasn't been converted to bitcode. | |
| =item B<-native-cbe> | |
| Generate a native machine code executable with the LLVM C backend. | |
| This option is identical to the B<-native> option, but uses the | |
| C backend to generate code for the program instead of an LLVM native | |
| code generator. | |
| =back | |
| =head2 Optimization Options | |
| =over | |
| =item B<-disable-inlining> | |
| Do not run the inlining pass. Functions will not be inlined into other | |
| functions. | |
| =item B<-disable-opt> | |
| Completely disable optimization. | |
| =item B<-disable-internalize> | |
| Do not mark all symbols as internal. | |
| =item B<-verify-each> | |
| Run the verification pass after each of the passes to verify intermediate | |
| results. | |
| =item B<-strip-all> | |
| Strip all debug and symbol information from the executable to make it smaller. | |
| =item B<-strip-debug> | |
| Strip all debug information from the executable to make it smaller. | |
| =item B<-s> | |
| An alias for B<-strip-all>. | |
| =item B<-S> | |
| An alias for B<-strip-debug>. | |
| =item B<-export-dynamic> | |
| An alias for B<-disable-internalize> | |
| =item B<-post-link-opt>F<Path> | |
| Run post-link optimization program. After linking is completed a bitcode file | |
| will be generated. It will be passed to the program specified by F<Path> as the | |
| first argument. The second argument to the program will be the name of a | |
| temporary file into which the program should place its optimized output. For | |
| example, the "no-op optimization" would be a simple shell script: | |
| #!/bin/bash | |
| cp $1 $2 | |
| =back | |
| =head1 EXIT STATUS | |
| If B<llvm-ld> succeeds, it will exit with 0 return code. If an error occurs, | |
| it will exit with a non-zero return code. | |
| =head1 ENVIRONMENT | |
| The C<LLVM_LIB_SEARCH_PATH> environment variable is used to find bitcode | |
| libraries. Any paths specified in this variable will be searched after the C<-L> | |
| options. | |
| =head1 SEE ALSO | |
| L<llvm-link|llvm-link> | |
| =head1 AUTHORS | |
| Maintained by the LLVM Team (L<http://llvm.org/>). | |
| =cut |