diff options
author | mike-m <mikem.llvm@gmail.com> | 2010-05-07 00:28:04 +0000 |
---|---|---|
committer | mike-m <mikem.llvm@gmail.com> | 2010-05-07 00:28:04 +0000 |
commit | e2c3a49c8029ebd9ef530101cc24c66562e3dff5 (patch) | |
tree | 91bf9600cc8df90cf99751a8f8bafc317cffc91e /docs/CommandGuide/llvm-ld.pod | |
parent | c10b5afbe8138b0fdf3af4ed3e1ddf96cf3cb4cb (diff) | |
download | external_llvm-e2c3a49c8029ebd9ef530101cc24c66562e3dff5.zip external_llvm-e2c3a49c8029ebd9ef530101cc24c66562e3dff5.tar.gz external_llvm-e2c3a49c8029ebd9ef530101cc24c66562e3dff5.tar.bz2 |
Revert r103213. It broke several sections of live website.
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@103219 91177308-0d34-0410-b5e6-96231b3b80d8
Diffstat (limited to 'docs/CommandGuide/llvm-ld.pod')
-rw-r--r-- | docs/CommandGuide/llvm-ld.pod | 234 |
1 files changed, 234 insertions, 0 deletions
diff --git a/docs/CommandGuide/llvm-ld.pod b/docs/CommandGuide/llvm-ld.pod new file mode 100644 index 0000000..536ab0f --- /dev/null +++ b/docs/CommandGuide/llvm-ld.pod @@ -0,0 +1,234 @@ +=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 |