


LLVM-LD(1)              LLVM Command Guide             LLVM-LD(1)


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 liblibrary.bc, liblibrary.a, or
       liblibrary.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



CVS                         2010-05-06                          1





LLVM-LD(1)              LLVM Command Guide             LLVM-LD(1)


       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.

   Input/Output Options
       -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.



CVS                         2010-05-06                          2





LLVM-LD(1)              LLVM Command Guide             LLVM-LD(1)


       -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



CVS                         2010-05-06                          3





LLVM-LD(1)              LLVM Command Guide             LLVM-LD(1)


           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>).




































CVS                         2010-05-06                          4


