| .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14 |
| .\" |
| .\" Standard preamble: |
| .\" ======================================================================== |
| .de Sh \" Subsection heading |
| .br |
| .if t .Sp |
| .ne 5 |
| .PP |
| \fB\\$1\fR |
| .PP |
| .. |
| .de Sp \" Vertical space (when we can't use .PP) |
| .if t .sp .5v |
| .if n .sp |
| .. |
| .de Vb \" Begin verbatim text |
| .ft CW |
| .nf |
| .ne \\$1 |
| .. |
| .de Ve \" End verbatim text |
| .ft R |
| .fi |
| .. |
| .\" Set up some character translations and predefined strings. \*(-- will |
| .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left |
| .\" double quote, and \*(R" will give a right double quote. | will give a |
| .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to |
| .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' |
| .\" expand to `' in nroff, nothing in troff, for use with C<>. |
| .tr \(*W-|\(bv\*(Tr |
| .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
| .ie n \{\ |
| . ds -- \(*W- |
| . ds PI pi |
| . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
| . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch |
| . ds L" "" |
| . ds R" "" |
| . ds C` "" |
| . ds C' "" |
| 'br\} |
| .el\{\ |
| . ds -- \|\(em\| |
| . ds PI \(*p |
| . ds L" `` |
| . ds R" '' |
| 'br\} |
| .\" |
| .\" If the F register is turned on, we'll generate index entries on stderr for |
| .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index |
| .\" entries marked with X<> in POD. Of course, you'll have to process the |
| .\" output yourself in some meaningful fashion. |
| .if \nF \{\ |
| . de IX |
| . tm Index:\\$1\t\\n%\t"\\$2" |
| .. |
| . nr % 0 |
| . rr F |
| .\} |
| .\" |
| .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| .\" way too many mistakes in technical documents. |
| .hy 0 |
| .if n .na |
| .\" |
| .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). |
| .\" Fear. Run. Save yourself. No user-serviceable parts. |
| . \" fudge factors for nroff and troff |
| .if n \{\ |
| . ds #H 0 |
| . ds #V .8m |
| . ds #F .3m |
| . ds #[ \f1 |
| . ds #] \fP |
| .\} |
| .if t \{\ |
| . ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
| . ds #V .6m |
| . ds #F 0 |
| . ds #[ \& |
| . ds #] \& |
| .\} |
| . \" simple accents for nroff and troff |
| .if n \{\ |
| . ds ' \& |
| . ds ` \& |
| . ds ^ \& |
| . ds , \& |
| . ds ~ ~ |
| . ds / |
| .\} |
| .if t \{\ |
| . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
| . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' |
| . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' |
| . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' |
| . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' |
| . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' |
| .\} |
| . \" troff and (daisy-wheel) nroff accents |
| .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
| .ds 8 \h'\*(#H'\(*b\h'-\*(#H' |
| .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] |
| .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' |
| .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' |
| .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] |
| .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] |
| .ds ae a\h'-(\w'a'u*4/10)'e |
| .ds Ae A\h'-(\w'A'u*4/10)'E |
| . \" corrections for vroff |
| .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
| .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' |
| . \" for low resolution devices (crt and lpr) |
| .if \n(.H>23 .if \n(.V>19 \ |
| \{\ |
| . ds : e |
| . ds 8 ss |
| . ds o a |
| . ds d- d\h'-1'\(ga |
| . ds D- D\h'-1'\(hy |
| . ds th \o'bp' |
| . ds Th \o'LP' |
| . ds ae ae |
| . ds Ae AE |
| .\} |
| .rm #[ #] #H #V #F C |
| .\" ======================================================================== |
| .\" |
| .IX Title "LLVM-LD 1" |
| .TH LLVM-LD 1 "2007-05-06" "CVS" "LLVM Command Guide" |
| .SH "NAME" |
| llvm\-ld \- LLVM linker |
| .SH "SYNOPSIS" |
| .IX Header "SYNOPSIS" |
| \&\fBllvm-ld\fR <options> <files> |
| .SH "DESCRIPTION" |
| .IX Header "DESCRIPTION" |
| The \fBllvm-ld\fR tool takes a set of \s-1LLVM\s0 bytecode files and links them |
| together into a single \s-1LLVM\s0 bytecode file. The output bytecode file can be |
| another bytecode file or an executable bytecode program. Using additional |
| options, \fBllvm-ld\fR is able to produce native code executables. |
| .PP |
| The \fBllvm-ld\fR tool is the main linker for \s-1LLVM\s0. It is used to link together |
| the output of \s-1LLVM\s0 front-end compilers and run \*(L"link time\*(R" optimizations (mostly |
| the inter-procedural kind). |
| .PP |
| The \fBllvm-ld\fR tools attemps to mimic the interface provided by the default |
| system linker so that it can act as a \fIdrop-in\fR replacement. |
| .Sh "Search Order" |
| .IX Subsection "Search Order" |
| When looking for objects specified on the command line, \fBllvm-ld\fR will search |
| for the object first in the current directory and then in the directory |
| specified by the \fB\s-1LLVM_LIB_SEARCH_PATH\s0\fR environment variable. If it cannot |
| find the object, it fails. |
| .PP |
| When looking for a library specified with the \fB\-l\fR option, \fBllvm-ld\fR first |
| attempts to load a file with that name from the current directory. If that |
| fails, it looks for lib\fIlibrary\fR.bc, lib\fIlibrary\fR.a, or lib\fIlibrary\fR.\fIshared |
| library extension\fR, in that order, in each directory added to the library search |
| path with the \fB\-L\fR option. These directories are searched in the order they |
| are specified. If the library cannot be located, then \fBllvm-ld\fR looks in the |
| directory specified by the \fB\s-1LLVM_LIB_SEARCH_PATH\s0\fR environment variable. If it |
| does not find a library there, it fails. |
| .PP |
| The \fIshared library extension\fR may be \fI.so\fR, \fI.dyld\fR, \fI.dll\fR, or something |
| different, depending upon the system. |
| .PP |
| The \fB\-L\fR 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. |
| .Sh "Link order" |
| .IX Subsection "Link order" |
| All object and bytecode 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. |
| .Sh "Library Linkage" |
| .IX Subsection "Library Linkage" |
| Object files and static bytecode 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. |
| .Sh "Native code generation" |
| .IX Subsection "Native code generation" |
| The \fBllvm-ld\fR program has limited support for native code generation, when |
| using the \fB\-native\fR or \fB\-native\-cbe\fR options. Native code generation is |
| perfomed by converting the linked bytecode into native assembly (.s) or C code |
| and running the system compiler (typically gcc) on the result. |
| .SH "OPTIONS" |
| .IX Header "OPTIONS" |
| .Sh "General Options" |
| .IX Subsection "General Options" |
| .IP "\fB\-help\fR" 4 |
| .IX Item "-help" |
| Print a summary of command line options. |
| .IP "\fB\-v\fR" 4 |
| .IX Item "-v" |
| Specifies verbose mode. In this mode the linker will print additional |
| information about the actions it takes, programs it executes, etc. |
| .IP "\fB\-stats\fR" 4 |
| .IX Item "-stats" |
| Print statistics. |
| .IP "\fB\-time\-passes\fR" 4 |
| .IX Item "-time-passes" |
| Record the amount of time needed for each pass and print it to standard |
| error. |
| .Sh "Input/Output Options" |
| .IX Subsection "Input/Output Options" |
| .IP "\fB\-o\fR \fIfilename\fR" 4 |
| .IX Item "-o filename" |
| This overrides the default output file and specifies the name of the file that |
| should be generated by the linker. By default, \fBllvm-ld\fR generates a file named |
| \&\fIa.out\fR for compatibility with \fBld\fR. The output will be written to |
| \&\fIfilename\fR. |
| .IP "\fB\-l\fR\fIname\fR" 4 |
| .IX Item "-lname" |
| This option specifies the \fIname\fR of a library to search when resolving symbols |
| for the program. Only the base name should be specified as \fIname\fR, without a |
| \&\fIlib\fR prefix or any suffix. |
| .IP "\fB\-L\fR\fIPath\fR" 4 |
| .IX Item "-LPath" |
| This option tells \fBllvm-ld\fR to look in \fIPath\fR to find any library subsequently |
| specified with the \fB\-l\fR 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 \fB\-l\fR option that occur \fIbefore\fR any \fB\-L\fR options |
| will not search the paths given by the \fB\-L\fR options following it. |
| .IP "\fB\-link\-as\-library\fR" 4 |
| .IX Item "-link-as-library" |
| Link the bytecode files together as a library, not an executable. In this mode, |
| undefined symbols will be permitted. |
| .IP "\fB\-r\fR" 4 |
| .IX Item "-r" |
| An alias for \-link\-as\-library. |
| .ie n .IP "\fB\-march=\fR""target""" 4 |
| .el .IP "\fB\-march=\fR\f(CWtarget\fR" 4 |
| .IX Item "-march=target" |
| Specifies the kind of machine for which code or assembly should be generated. |
| .IP "\fB\-native\fR" 4 |
| .IX Item "-native" |
| Generate a native machine code executable. |
| .Sp |
| When generating native executables, \fBllvm-ld\fR first checks for a bytecode |
| version of the library and links it in, if necessary. If the library is |
| missing, \fBllvm-ld\fR skips it. Then, \fBllvm-ld\fR links in the same |
| libraries as native code. |
| .Sp |
| In this way, \fBllvm-ld\fR should be able to link in optimized bytecode |
| subsets of common libraries and then link in any part of the library that |
| hasn't been converted to bytecode. |
| .IP "\fB\-native\-cbe\fR" 4 |
| .IX Item "-native-cbe" |
| Generate a native machine code executable with the \s-1LLVM\s0 C backend. |
| .Sp |
| This option is identical to the \fB\-native\fR option, but uses the |
| C backend to generate code for the program instead of an \s-1LLVM\s0 native |
| code generator. |
| .Sh "Optimization Options" |
| .IX Subsection "Optimization Options" |
| .IP "\fB\-O0\fR" 4 |
| .IX Item "-O0" |
| An alias for the \-O1 option. |
| .IP "\fB\-O1\fR" 4 |
| .IX Item "-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. |
| .IP "\fB\-O2\fR" 4 |
| .IX Item "-O2" |
| Perform only the minimal or required set of scalar optimizations. |
| .IP "\fB\-03\fR" 4 |
| .IX Item "-03" |
| An alias for the \-O2 option. |
| .IP "\fB\-04\fR" 4 |
| .IX Item "-04" |
| Perform the standard link time inter-procedural optimizations. This will |
| attempt to optimize the program taking the entire program into consideration. |
| .IP "\fB\-O5\fR" 4 |
| .IX Item "-O5" |
| Perform aggressive link time optimizations. This is the same as \-O4 but works |
| more aggressively to optimize the program. |
| .IP "\fB\-disable\-inlining\fR" 4 |
| .IX Item "-disable-inlining" |
| Do not run the inlining pass. Functions will not be inlined into other |
| functions. |
| .IP "\fB\-disable\-opt\fR" 4 |
| .IX Item "-disable-opt" |
| Completely disable optimization. The various \fB\-On\fR options will be ignored and |
| no link time optimization passes will be run. |
| .IP "\fB\-disable\-internalize\fR" 4 |
| .IX Item "-disable-internalize" |
| Do not mark all symbols as internal. |
| .IP "\fB\-verify\-each\fR" 4 |
| .IX Item "-verify-each" |
| Run the verification pass after each of the passes to verify intermediate |
| results. |
| .IP "\fB\-strip\-all\fR" 4 |
| .IX Item "-strip-all" |
| Strip all debug and symbol information from the executable to make it smaller. |
| .IP "\fB\-strip\-debug\fR" 4 |
| .IX Item "-strip-debug" |
| Strip all debug information from the executable to make it smaller. |
| .IP "\fB\-s\fR" 4 |
| .IX Item "-s" |
| An alias for \fB\-strip\-all\fR. |
| .IP "\fB\-S\fR" 4 |
| .IX Item "-S" |
| An alias for \fB\-strip\-debug\fR. |
| .IP "\fB\-export\-dynamic\fR" 4 |
| .IX Item "-export-dynamic" |
| An alias for \fB\-disable\-internalize\fR |
| .IP "\fB\-load\fR \fImodule\fR" 4 |
| .IX Item "-load module" |
| Load an optimization module, \fImodule\fR, which is expected to be a dynamic |
| library that provides the function name \f(CW\*(C`RunOptimizations\*(C'\fR. This function will |
| be passed the PassManager, and the optimization level (values 0\-5 based on the |
| \&\fB\-On\fR option). This function may add passes to the PassManager that should be |
| run. This feature allows the optimization passes of \fBllvm-ld\fR to be extended. |
| .IP "\fB\-post\-link\-opt\fR\fIPath\fR" 4 |
| .IX Item "-post-link-optPath" |
| Run post-link optimization program. After linking is completed a bytecode file |
| will be generated. It will be passed to the program specified by \fIPath\fR 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 \*(L"no\-op optimization\*(R" would be a simple shell script: |
| .Sp |
| .Vb 2 |
| \& #!/bin/bash |
| \& cp $1 $2 |
| .Ve |
| .SH "EXIT STATUS" |
| .IX Header "EXIT STATUS" |
| If \fBllvm-ld\fR succeeds, it will exit with 0 return code. If an error occurs, |
| it will exit with a non-zero return code. |
| .SH "ENVIRONMENT" |
| .IX Header "ENVIRONMENT" |
| The \f(CW\*(C`LLVM_LIB_SEARCH_PATH\*(C'\fR environment variable is used to find bytecode |
| libraries. Any paths specified in this variable will be searched after the \f(CW\*(C`\-L\*(C'\fR |
| options. |
| .SH "SEE ALSO" |
| .IX Header "SEE ALSO" |
| llvm-link |
| .SH "AUTHORS" |
| .IX Header "AUTHORS" |
| Maintained by the \s-1LLVM\s0 Team (<http://llvm.org>). |
