NAME¶
llvm-ld - LLVM linker
SYNOPSIS¶
llvm-ld <options> <files>
DESCRIPTION¶
The
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,
llvm-ld is able to produce native code executables.
The
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
llvm-ld tools attempts to mimic the interface provided by the default
system linker so that it can act as a
drop-in replacement.
Search Order¶
When looking for objects specified on the command line,
llvm-ld will
search for the object first in the current directory and then in the directory
specified by the
LLVM_LIB_SEARCH_PATH environment variable. If it
cannot find the object, it fails.
When looking for a library specified with the
-l option,
llvm-ld
first attempts to load a file with that name from the current directory. If
that fails, it looks for lib
library.bc, lib
library.a, or
lib
library.
shared library extension, in that order, in
each directory added to the library search path with the
-L option.
These directories are searched in the order they are specified. If the library
cannot be located, then
llvm-ld looks in the directory specified by the
LLVM_LIB_SEARCH_PATH environment variable. If it does not find a
library there, it fails.
The
shared library extension may be
.so,
.dyld,
.dll, or something different, depending upon the system.
The
-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.
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.
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.
Native code generation¶
The
llvm-ld program has limited support for native code generation, when
using the
-native or
-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.
OPTIONS¶
General Options¶
- -help
- Print a summary of command line options.
- -v
- Specifies verbose mode. In this mode the linker will print
additional information about the actions it takes, programs it executes,
etc.
- -stats
- Print statistics.
- -time-passes
- Record the amount of time needed for each pass and print it
to standard error.
- -o filename
- This overrides the default output file and specifies the
name of the file that should be generated by the linker. By default,
llvm-ld generates a file named a.out for compatibility with
ld. The output will be written to filename.
- -b 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 -o filename
option.
- -lname
- This option specifies the name of a library to
search when resolving symbols for the program. Only the base name should
be specified as name, without a lib prefix or any
suffix.
- -LPath
- This option tells llvm-ld to look in Path to
find any library subsequently specified with the -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 -l option that occur before any -L options
will not search the paths given by the -L options following
it.
- -link-as-library
- Link the bitcode files together as a library, not an
executable. In this mode, undefined symbols will be permitted.
- -r
- An alias for -link-as-library.
- -native
- Generate a native machine code executable.
When generating native executables, llvm-ld first checks for a
bitcode version of the library and links it in, if necessary. If the
library is missing, llvm-ld skips it. Then, llvm-ld links in
the same libraries as native code.
In this way, 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.
- -native-cbe
- Generate a native machine code executable with the LLVM C
backend.
This option is identical to the -native option, but uses the C
backend to generate code for the program instead of an LLVM native code
generator.
Optimization Options¶
- -disable-inlining
- Do not run the inlining pass. Functions will not be inlined
into other functions.
- -disable-opt
- Completely disable optimization.
- -disable-internalize
- Do not mark all symbols as internal.
- -verify-each
- Run the verification pass after each of the passes to
verify intermediate results.
- -strip-all
- Strip all debug and symbol information from the executable
to make it smaller.
- -strip-debug
- Strip all debug information from the executable to make it
smaller.
- -s
- An alias for -strip-all.
- -S
- An alias for -strip-debug.
- -export-dynamic
- An alias for -disable-internalize
- -post-link-optPath
- Run post-link optimization program. After linking is
completed a bitcode file will be generated. It will be passed to the
program specified by 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
EXIT STATUS¶
If
llvm-ld succeeds, it will exit with 0 return code. If an error occurs,
it will exit with a non-zero return code.
ENVIRONMENT¶
The "LLVM_LIB_SEARCH_PATH" environment variable is used to find
bitcode libraries. Any paths specified in this variable will be searched after
the "-L" options.
SEE ALSO¶
llvm-link
AUTHORS¶
Maintained by the LLVM Team (<
http://llvm.org/>).