=head1 DESCRIPTION
-The B<llvm-ld> command is similar to the common Unix utility, C<ld>. It
-links together bytecode modules to produce an executable program.
+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
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
=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>
An alias for -link-as-library.
-=item B<-march=>C<target>
-
-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<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.
-Generate a native binary with the C back end and compilation with GCC.
+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<-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
=over
-=item B<-O0>
-
-An alias for the -O1 option.
-
-=item B<-O1>
-
-Optimize for linking speed, not execution speed. The optimizer will attempt to
-reduce the size of the linked program to reduce I/O but will not otherwise
-perform any link-time optimizations.
-
-=item B<-O2>
-
-Perform only the minimal or required set of scalar optimizations.
-
-=item B<-03>
-
-An alias for the -O2 option.
-
-=item B<-04>
-
-Perform the standard link time inter-procedural optimizations. This will
-attempt to optimize the program taking the entire program into consideration.
-
-=item B<-O5>
-
-Perform aggressive link time optimizations. This is the same as -O4 but works
-more aggressively to optimize the program.
-
=item B<-disable-inlining>
Do not run the inlining pass. Functions will not be inlined into other
=item B<-disable-opt>
-Completely disable optimization. The various B<-On> options will be ignored and
-no link time optimization passes will be run.
+Completely disable optimization.
=item B<-disable-internalize>
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<-export-dynamic>
+=item B<-S>
-An alias for -disable-internalize
+An alias for B<-strip-debug>.
-=item B<-load> F<module>
+=item B<-export-dynamic>
-Load an optimization module, F<module>, which is expected to be a dynamic
-library that provides the function name C<RunOptimizations>. This function will
-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<llvm-ld> to be extended.
+An alias for B<-disable-internalize>
=item B<-post-link-opt>F<Path>
-Run post-link optimization program. After linking is completed a bytecode file
+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:
-=over
-
-#!/bin/bash
-cp $1 $2
-
-=back
-
-=back
-
-=head2 Miscellaneous Options
-
-=over
-
-=item B<-v>
-
-Specifies verbose mode. In this mode the linker will print additional
-information about the actions it takes, programs it executes, etc.
+ #!/bin/bash
+ cp $1 $2
=back
=head1 ENVIRONMENT
-The C<LLVM_LIB_SEARCH_PATH> environment variable is used to find bytecode
+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-ar|llvm-ar>
+L<llvm-link|llvm-link>
=head1 AUTHORS
-Maintained by the LLVM Team (L<http://llvm.cs.uiuc.edu>).
+Maintained by the LLVM Team (L<http://llvm.org>).
=cut
projects / oota-llvm.git / blobdiff