usr.bin/clang/llvm-ld/llvm-ld.1

   1 .\" $FreeBSD$
   2 .\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
   3 .\"
   4 .\" Standard preamble:
   5 .\" ========================================================================
   6 .de Sp \" Vertical space (when we can't use .PP)
   7 .if t .sp .5v
   8 .if n .sp
   9 ..
  10 .de Vb \" Begin verbatim text
  11 .ft CW
  12 .nf
  13 .ne \\$1
  14 ..
  15 .de Ve \" End verbatim text
  16 .ft R
  17 .fi
  18 ..
  19 .\" Set up some character translations and predefined strings.  \*(-- will
  20 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  21 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  22 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  23 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  24 .\" nothing in troff, for use with C<>.
  25 .tr \(*W-
  26 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  27 .ie n \{\
  28 .    ds -- \(*W-
  29 .    ds PI pi
  30 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  31 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  32 .    ds L" ""
  33 .    ds R" ""
  34 .    ds C` ""
  35 .    ds C' ""
  36 'br\}
  37 .el\{\
  38 .    ds -- \|\(em\|
  39 .    ds PI \(*p
  40 .    ds L" ``
  41 .    ds R" ''
  42 'br\}
  43 .\"
  44 .\" Escape single quotes in literal strings from groff's Unicode transform.
  45 .ie \n(.g .ds Aq \(aq
  46 .el       .ds Aq '
  47 .\"
  48 .\" If the F register is turned on, we'll generate index entries on stderr for
  49 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  50 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  51 .\" output yourself in some meaningful fashion.
  52 .ie \nF \{\
  53 .    de IX
  54 .    tm Index:\\$1\t\\n%\t"\\$2"
  55 ..
  56 .    nr % 0
  57 .    rr F
  58 .\}
  59 .el \{\
  60 .    de IX
  61 ..
  62 .\}
  63 .\"
  64 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  65 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  66 .    \" fudge factors for nroff and troff
  67 .if n \{\
  68 .    ds #H 0
  69 .    ds #V .8m
  70 .    ds #F .3m
  71 .    ds #[ \f1
  72 .    ds #] \fP
  73 .\}
  74 .if t \{\
  75 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  76 .    ds #V .6m
  77 .    ds #F 0
  78 .    ds #[ \&
  79 .    ds #] \&
  80 .\}
  81 .    \" simple accents for nroff and troff
  82 .if n \{\
  83 .    ds ' \&
  84 .    ds ` \&
  85 .    ds ^ \&
  86 .    ds , \&
  87 .    ds ~ ~
  88 .    ds /
  89 .\}
  90 .if t \{\
  91 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  92 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  93 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  94 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  95 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  96 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  97 .\}
  98 .    \" troff and (daisy-wheel) nroff accents
  99 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 100 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 101 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 102 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 103 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 104 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 105 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 106 .ds ae a\h'-(\w'a'u*4/10)'e
 107 .ds Ae A\h'-(\w'A'u*4/10)'E
 108 .    \" corrections for vroff
 109 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 110 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 111 .    \" for low resolution devices (crt and lpr)
 112 .if \n(.H>23 .if \n(.V>19 \
 113 \{\
 114 .    ds : e
 115 .    ds 8 ss
 116 .    ds o a
 117 .    ds d- d\h'-1'\(ga
 118 .    ds D- D\h'-1'\(hy
 119 .    ds th \o'bp'
 120 .    ds Th \o'LP'
 121 .    ds ae ae
 122 .    ds Ae AE
 123 .\}
 124 .rm #[ #] #H #V #F C
 125 .\" ========================================================================
 126 .\"
 127 .IX Title "LLVM-LD 1"
 128 .TH LLVM-LD 1 "2012-04-05" "LLVM 3.1" "LLVM Command Guide"
 129 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 130 .\" way too many mistakes in technical documents.
 131 .if n .ad l
 132 .nh
 133 .SH "NAME"
 134 llvm\-ld \- LLVM linker
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 \&\fBllvm-ld\fR <options> <files>
 138 .SH "DESCRIPTION"
 139 .IX Header "DESCRIPTION"
 140 The \fBllvm-ld\fR tool takes a set of \s-1LLVM\s0 bitcode files and links them
 141 together into a single \s-1LLVM\s0 bitcode file.  The output bitcode file can be
 142 another bitcode file or an executable bitcode program.  Using additional
 143 options, \fBllvm-ld\fR is able to produce native code executables.
 144 .PP
 145 The \fBllvm-ld\fR tool is the main linker for \s-1LLVM\s0. It is used to link together
 146 the output of \s-1LLVM\s0 front-end compilers and run \*(L"link time\*(R" optimizations (mostly
 147 the inter-procedural kind).
 148 .PP
 149 The \fBllvm-ld\fR tools attempts to mimic the interface provided by the default
 150 system linker so that it can act as a \fIdrop-in\fR replacement.
 151 .SS "Search Order"
 152 .IX Subsection "Search Order"
 153 When looking for objects specified on the command line, \fBllvm-ld\fR will search
 154 for the object first in the current directory and then in the directory
 155 specified by the \fB\s-1LLVM_LIB_SEARCH_PATH\s0\fR environment variable.  If it cannot
 156 find the object, it fails.
 157 .PP
 158 When looking for a library specified with the \fB\-l\fR option, \fBllvm-ld\fR first
 159 attempts to load a file with that name from the current directory.  If that
 160 fails, it looks for lib\fIlibrary\fR.bc, lib\fIlibrary\fR.a, or lib\fIlibrary\fR.\fIshared
 161 library extension\fR, in that order, in each directory added to the library search
 162 path with the \fB\-L\fR option.  These directories are searched in the order they
 163 are specified.  If the library cannot be located, then \fBllvm-ld\fR looks in the
 164 directory specified by the \fB\s-1LLVM_LIB_SEARCH_PATH\s0\fR environment variable.  If it
 165 does not find a library there, it fails.
 166 .PP
 167 The \fIshared library extension\fR may be \fI.so\fR, \fI.dyld\fR, \fI.dll\fR, or something
 168 different, depending upon the system.
 169 .PP
 170 The \fB\-L\fR option is global.  It does not matter where it is specified in the
 171 list of command line arguments; the directory is simply added to the search path
 172 and is applied to all libraries, preceding or succeeding, in the command line.
 173 .SS "Link order"
 174 .IX Subsection "Link order"
 175 All object and bitcode files are linked first in the order they were
 176 specified on the command line.  All library files are linked next.
 177 Some libraries may not be linked into the object program; see below.
 178 .SS "Library Linkage"
 179 .IX Subsection "Library Linkage"
 180 Object files and static bitcode objects are always linked into the output
 181 file.  Library archives (.a files) load only the objects within the archive
 182 that define symbols needed by the output file.  Hence, libraries should be
 183 listed after the object files and libraries which need them; otherwise, the
 184 library may not be linked in, and the dependent library will not have its
 185 undefined symbols defined.
 186 .SS "Native code generation"
 187 .IX Subsection "Native code generation"
 188 The \fBllvm-ld\fR program has limited support for native code generation, when
 189 using the \fB\-native\fR or \fB\-native\-cbe\fR options. Native code generation is
 190 performed by converting the linked bitcode into native assembly (.s) or C code
 191 and running the system compiler (typically gcc) on the result.
 192 .SH "OPTIONS"
 193 .IX Header "OPTIONS"
 194 .SS "General Options"
 195 .IX Subsection "General Options"
 196 .IP "\fB\-help\fR" 4
 197 .IX Item "-help"
 198 Print a summary of command line options.
 199 .IP "\fB\-v\fR" 4
 200 .IX Item "-v"
 201 Specifies verbose mode. In this mode the linker will print additional
 202 information about the actions it takes, programs it executes, etc.
 203 .IP "\fB\-stats\fR" 4
 204 .IX Item "-stats"
 205 Print statistics.
 206 .IP "\fB\-time\-passes\fR" 4
 207 .IX Item "-time-passes"
 208 Record the amount of time needed for each pass and print it to standard
 209 error.
 210 .SS "Input/Output Options"
 211 .IX Subsection "Input/Output Options"
 212 .IP "\fB\-o\fR \fIfilename\fR" 4
 213 .IX Item "-o filename"
 214 This overrides the default output file and specifies the name of the file that
 215 should be generated by the linker. By default, \fBllvm-ld\fR generates a file named
 216 \&\fIa.out\fR for compatibility with \fBld\fR. The output will be written to
 217 \&\fIfilename\fR.
 218 .IP "\fB\-b\fR \fIfilename\fR" 4
 219 .IX Item "-b filename"
 220 This option can be used to override the output bitcode file name. By default,
 221 the name of the bitcode output file is one more \*(L".bc\*(R" suffix added to the name
 222 specified by \fB\-o filename\fR option.
 223 .IP "\fB\-l\fR\fIname\fR" 4
 224 .IX Item "-lname"
 225 This option specifies the \fIname\fR of a library to search when resolving symbols
 226 for the program. Only the base name should be specified as \fIname\fR, without a
 227 \&\fIlib\fR prefix or any suffix.
 228 .IP "\fB\-L\fR\fIPath\fR" 4
 229 .IX Item "-LPath"
 230 This option tells \fBllvm-ld\fR to look in \fIPath\fR to find any library subsequently
 231 specified with the \fB\-l\fR option. The paths will be searched in the order in
 232 which they are specified on the command line. If the library is still not found,
 233 a small set of system specific directories will also be searched. Note that
 234 libraries specified with the \fB\-l\fR option that occur \fIbefore\fR any \fB\-L\fR options
 235 will not search the paths given by the \fB\-L\fR options following it.
 236 .IP "\fB\-link\-as\-library\fR" 4
 237 .IX Item "-link-as-library"
 238 Link the bitcode files together as a library, not an executable. In this mode,
 239 undefined symbols will be permitted.
 240 .IP "\fB\-r\fR" 4
 241 .IX Item "-r"
 242 An alias for \-link\-as\-library.
 243 .IP "\fB\-native\fR" 4
 244 .IX Item "-native"
 245 Generate a native machine code executable.
 246 .Sp
 247 When generating native executables, \fBllvm-ld\fR first checks for a bitcode
 248 version of the library and links it in, if necessary.  If the library is
 249 missing, \fBllvm-ld\fR skips it.  Then, \fBllvm-ld\fR links in the same
 250 libraries as native code.
 251 .Sp
 252 In this way, \fBllvm-ld\fR should be able to link in optimized bitcode
 253 subsets of common libraries and then link in any part of the library that
 254 hasn't been converted to bitcode.
 255 .IP "\fB\-native\-cbe\fR" 4
 256 .IX Item "-native-cbe"
 257 Generate a native machine code executable with the \s-1LLVM\s0 C backend.
 258 .Sp
 259 This option is identical to the \fB\-native\fR option, but uses the
 260 C backend to generate code for the program instead of an \s-1LLVM\s0 native
 261 code generator.
 262 .SS "Optimization Options"
 263 .IX Subsection "Optimization Options"
 264 .IP "\fB\-disable\-inlining\fR" 4
 265 .IX Item "-disable-inlining"
 266 Do not run the inlining pass. Functions will not be inlined into other
 267 functions.
 268 .IP "\fB\-disable\-opt\fR" 4
 269 .IX Item "-disable-opt"
 270 Completely disable optimization.
 271 .IP "\fB\-disable\-internalize\fR" 4
 272 .IX Item "-disable-internalize"
 273 Do not mark all symbols as internal.
 274 .IP "\fB\-verify\-each\fR" 4
 275 .IX Item "-verify-each"
 276 Run the verification pass after each of the passes to verify intermediate
 277 results.
 278 .IP "\fB\-strip\-all\fR" 4
 279 .IX Item "-strip-all"
 280 Strip all debug and symbol information from the executable to make it smaller.
 281 .IP "\fB\-strip\-debug\fR" 4
 282 .IX Item "-strip-debug"
 283 Strip all debug information from the executable to make it smaller.
 284 .IP "\fB\-s\fR" 4
 285 .IX Item "-s"
 286 An alias for \fB\-strip\-all\fR.
 287 .IP "\fB\-S\fR" 4
 288 .IX Item "-S"
 289 An alias for \fB\-strip\-debug\fR.
 290 .IP "\fB\-export\-dynamic\fR" 4
 291 .IX Item "-export-dynamic"
 292 An alias for \fB\-disable\-internalize\fR
 293 .IP "\fB\-post\-link\-opt\fR\fIPath\fR" 4
 294 .IX Item "-post-link-optPath"
 295 Run post-link optimization program. After linking is completed a bitcode file
 296 will be generated. It will be passed to the program specified by \fIPath\fR as the
 297 first argument. The second argument to the program will be the name of a
 298 temporary file into which the program should place its optimized output. For
 299 example, the \*(L"no-op optimization\*(R" would be a simple shell script:
 300 .Sp
 301 .Vb 2
 302 \&    #!/bin/bash
 303 \&    cp $1 $2
 304 .Ve
 305 .SH "EXIT STATUS"
 306 .IX Header "EXIT STATUS"
 307 If \fBllvm-ld\fR succeeds, it will exit with 0 return code.  If an error occurs,
 308 it will exit with a non-zero return code.
 309 .SH "ENVIRONMENT"
 310 .IX Header "ENVIRONMENT"
 311 The \f(CW\*(C`LLVM_LIB_SEARCH_PATH\*(C'\fR environment variable is used to find bitcode
 312 libraries. Any paths specified in this variable will be searched after the \f(CW\*(C`\-L\*(C'\fR
 313 options.
 314 .SH "SEE ALSO"
 315 .IX Header "SEE ALSO"
 316 llvm-link
 317 .SH "AUTHORS"
 318 .IX Header "AUTHORS"
 319 Maintained by the \s-1LLVM\s0 Team (<http://llvm.org/>).