X-Git-Url: http://demsky.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FCommandGuide%2Fllvm-ld.pod;h=d655737674ec3692189c90b768541e03c449b13e;hb=befc9c16fae1719cafe9f54ab2b67219db44dc11;hp=a20222cd59477f00d676ec905edd38600442a725;hpb=28e8e42d371e7c3cfc8366d3dd3416079ad03f5a;p=oota-llvm.git diff --git a/docs/CommandGuide/llvm-ld.pod b/docs/CommandGuide/llvm-ld.pod index a20222cd594..d655737674e 100644 --- a/docs/CommandGuide/llvm-ld.pod +++ b/docs/CommandGuide/llvm-ld.pod @@ -10,11 +10,89 @@ B =head1 DESCRIPTION -The B command is similar to the common Unix utility, C. It -links together bytecode modules to produce an executable program. +The B 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 is able to produce native code executables. + +The B 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 tools attempts to mimic the interface provided by the default +system linker so that it can act as a I replacement. + +=head2 Search Order + +When looking for objects specified on the command line, B will search +for the object first in the current directory and then in the directory +specified by the B environment variable. If it cannot +find the object, it fails. + +When looking for a library specified with the B<-l> option, B first +attempts to load a file with that name from the current directory. If that +fails, it looks for libI.bc, libI.a, or libI.I, 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 looks in the +directory specified by the B environment variable. If it +does not find a library there, it fails. + +The I 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 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 @@ -43,7 +121,7 @@ will not search the paths given by the B<-L> options following it. =item B<-link-as-library> -Link the bytecode files together as a library, not an executable. In this mode, +Link the bitcode files together as a library, not an executable. In this mode, undefined symbols will be permitted. =item B<-r> @@ -56,16 +134,24 @@ Specifies the kind of machine for which code or assembly should be generated. =item B<-native> -Generate a native binary instead of a shell script that runs the JIT from -bytecode. +Generate a native machine code executable. -=item B<-native-cbe> +When generating native executables, B first checks for a bitcode +version of the library and links it in, if necessary. If the library is +missing, B skips it. Then, B links in the same +libraries as native code. -Generate a native binary with the C back end and compilation with GCC. +In this way, B 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<-disable-compression> +=item B<-native-cbe> -Do not compress bytecode files. +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 @@ -115,18 +201,30 @@ no link time optimization passes will be run. Do not mark all symbols as internal. -=item B<-verify> +=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> -Strip symbol info from the executable to make it smaller. +An alias for B<-strip-all>. + +=item B<-S> + +An alias for B<-strip-debug>. =item B<-export-dynamic> -An alias for -disable-internalize +An alias for B<-disable-internalize> =item B<-load> F @@ -136,26 +234,36 @@ be passed the PassManager, and the optimization level (values 0-5 based on the B<-On> option). This function may add passes to the PassManager that should be run. This feature allows the optimization passes of B to be extended. -=back +=item B<-post-link-opt>F -=head2 Miscellaneous Options +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 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: -=item B<-v> + #!/bin/bash + cp $1 $2 -Specifies verbose mode. In this mode the linker will print additional -information about the actions it takes, programs it executes, etc. +=back =head1 EXIT STATUS If B 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 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 +L =head1 AUTHORS -Maintained by the LLVM Team (L). +Maintained by the LLVM Team (L). =cut