docs/CommandGuide/llvm-ld.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 llvm-ld - LLVM linker
   6
   7 =head1 SYNOPSIS
   8
   9 B<llvm-ld> <options> <files>
  10
  11 =head1 DESCRIPTION
  12
  13 The B<llvm-ld> command is similar to the common Unix utility, C<ld>. It
  14 links together bytecode modules to produce an executable program.
  15
  16 =head1 OPTIONS
  17
  18 =head2 Input/Output Options
  19
  20 =over
  21
  22 =item B<-o> F<filename>
  23
  24 This overrides the default output file and specifies the name of the file that
  25 should be generated by the linker. By default, B<llvm-ld> generates a file named
  26 F<a.out> for compatibility with B<ld>. The output will be written to
  27 F<filename>.
  28
  29 =item B<-l>F<name>
  30
  31 This option specifies the F<name> of a library to search when resolving symbols
  32 for the program. Only the base name should be specified as F<name>, without a
  33 F<lib> prefix or any suffix.
  34
  35 =item B<-L>F<Path>
  36
  37 This option tells B<llvm-ld> to look in F<Path> to find any library subsequently
  38 specified with the B<-l> option. The paths will be searched in the order in
  39 which they are specified on the command line. If the library is still not found,
  40 a small set of system specific directories will also be searched. Note that
  41 libraries specified with the B<-l> option that occur I<before> any B<-L> options
  42 will not search the paths given by the B<-L> options following it.
  43
  44 =item B<-link-as-library>
  45
  46 Link the bytecode files together as a library, not an executable. In this mode,
  47 undefined symbols will be permitted.
  48
  49 =item B<-r>
  50
  51 An alias for -link-as-library.
  52
  53 =item B<-march=>C<target>
  54
  55 Specifies the kind of machine for which code or assembly should be generated.
  56
  57 =item B<-native>
  58
  59 Generate a native binary instead of a shell script that runs the JIT from
  60 bytecode.
  61
  62 =item B<-native-cbe>
  63
  64 Generate a native binary with the C back end and compilation with GCC.
  65
  66 =item B<-disable-compression>
  67
  68 Do not compress bytecode files.
  69
  70 =back
  71
  72 =head2 Optimization Options
  73
  74 =over
  75
  76 =item B<-O0>
  77
  78 An alias for the -O1 option.
  79
  80 =item B<-O1>
  81
  82 Optimize for linking speed, not execution speed. The optimizer will attempt to
  83 reduce the size of the linked program to reduce I/O but will not otherwise
  84 perform any link-time optimizations.
  85
  86 =item B<-O2>
  87
  88 Perform only the minimal or required set of scalar optimizations.
  89
  90 =item B<-03>
  91
  92 An alias for the -O2 option.
  93
  94 =item B<-04>
  95
  96 Perform the standard link time inter-procedural optimizations. This will
  97 attempt to optimize the program taking the entire program into consideration.
  98
  99 =item B<-O5>
 100
 101 Perform aggressive link time optimizations. This is the same as -O4 but works
 102 more aggressively to optimize the program.
 103
 104 =item B<-disable-inlining>
 105
 106 Do not run the inlining pass. Functions will not be inlined into other
 107 functions.
 108
 109 =item B<-disable-opt>
 110
 111 Completely disable optimization. The various B<-On> options will be ignored and
 112 no link time optimization passes will be run.
 113
 114 =item B<-disable-internalize>
 115
 116 Do not mark all symbols as internal.
 117
 118 =item B<-verify>
 119
 120 Run the verification pass after each of the passes to verify intermediate
 121 results.
 122
 123 =item B<-s>
 124
 125 Strip symbol info from the executable to make it smaller.
 126
 127 =item B<-export-dynamic>
 128
 129 An alias for -disable-internalize
 130
 131 =item B<-load> F<module>
 132
 133 Load an optimization module, F<module>, which is expected to be a dynamic
 134 library that provides the function name C<RunOptimizations>. This function will
 135 be passed the PassManager, and the optimization level (values 0-5 based on the
 136 B<-On> option). This function may add passes to the PassManager that should be
 137 run. This feature allows the optimization passes of B<llvm-ld> to be extended.
 138
 139 =item B<-post-link-opt>F<Path>
 140
 141 Run post-link optimization program. After linking is completed a bytecode file
 142 will be generated. It will be passed to the program specified by F<Path> as the
 143 first argument. The second argument to the program will be the name of a
 144 temporary file into which the program should place its optimized output. For
 145 example, the "no-op optimization" would be a simple shell script:
 146
 147 =over
 148
 149 #!/bin/bash
 150 cp $1 $2
 151
 152 =back
 153
 154 =back
 155
 156 =head2 Miscellaneous Options
 157
 158 =over
 159
 160 =item B<-v>
 161
 162 Specifies verbose mode. In this mode the linker will print additional
 163 information about the actions it takes, programs it executes, etc.
 164
 165 =back
 166
 167 =head1 EXIT STATUS
 168
 169 If B<llvm-ld> succeeds, it will exit with 0 return code.  If an error occurs,
 170 it will exit with a non-zero return code.
 171
 172 =head1 ENVIRONMENT
 173
 174 The C<LLVM_LIB_SEARCH_PATH> environment variable is used to find bytecode
 175 libraries. Any paths specified in this variable will be searched after the C<-L>
 176 options.
 177
 178 =head1 SEE ALSO
 179
 180 L<llvm-ar|llvm-ar>
 181
 182 =head1 AUTHORS
 183
 184 Maintained by the LLVM Team (L<http://llvm.org>).
 185
 186 =cut