docs/CommandGuide/gccld.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 gccld - optimizing LLVM linker
   6
   7 =head1 SYNOPSIS
   8
   9 B<gccld> [I<options>] I<filename ...>
  10
  11 =head1 DESCRIPTION
  12
  13 The B<gccld> utility takes a set of LLVM bytecode files and links them
  14 together into a single LLVM bytecode file.  The output bytecode file can be
  15 another bytecode library or an executable bytecode program.  Using additional
  16 options, B<gccld> is able to produce native code executables.
  17
  18 The B<gccld> utility is primarily used by the L<llvmgcc> and
  19 L<llvmg++|llvmgxx> front-ends, and as such, attempts to mimic the interface
  20 provided by the default system linker so that it can act as a ``drop-in''
  21 replacement.
  22
  23 The B<gccld> tool performs a small set of interprocedural, post-link
  24 optimizations on the program.
  25
  26 =head2 Search Order
  27
  28 When looking for objects specified on the command line, B<gccld> will search for
  29 the object first in the current directory and then in the directory specified by
  30 the B<LLVM_LIB_SEARCH_PATH> environment variable.  If it cannot find the object,
  31 it fails.
  32
  33 When looking for a library specified with the B<-l> option, B<gccld> first
  34 attempts to load a file with that name from the current directory.  If that
  35 fails, it looks for libI<library>.bc, libI<library>.a, or libI<library>.I<shared
  36 library extension>, in that order, in each directory added to the library search
  37 path with the B<-L> option.  These directories are searched in the order they
  38 were specified.  If the library cannot be located, then B<gccld> looks in the
  39 directory specified by the B<LLVM_LIB_SEARCH_PATH> environment variable.  If it
  40 does not find a library there, it fails.
  41
  42 The shared library extension may be I<.so>, I<.dyld>, I<.dll>, or something
  43 different, depending upon the system.
  44
  45 The B<-L> option is global.  It does not matter where it is specified in the
  46 list of command line arguments; the directory is simply added to the search path
  47 and is applied to all libraries, preceding or succeeding, in the command line.
  48
  49 =head2 Link order
  50
  51 All object files are linked first in the order they were specified on the
  52 command line.  All library files are linked next.  Some libraries may not be
  53 linked into the object program; see below.
  54
  55 =head2 Library Linkage
  56
  57 Object files and static bytecode objects are always linked into the output
  58 file.  Library archives (.a files) load only the objects within the archive
  59 that define symbols needed by the output file.  Hence, libraries should be
  60 listed after the object files and libraries which need them; otherwise, the
  61 library may not be linked in, and the dependent library will not have its
  62 undefined symbols defined.
  63
  64 =head2 Native code generation
  65
  66 The B<gccld> program has limited support for native code generation, when
  67 using the B<-native> or B<-native-cbe> options.
  68
  69 =head1 OPTIONS
  70
  71 =over
  72
  73 =item B<-help>
  74
  75 Print a summary of command line options.
  76
  77 =item B<-o> I<filename>
  78
  79 Specify the output filename which will hold the linked bytecode.
  80
  81 =item B<-stats>
  82
  83 Print statistics.
  84
  85 =item B<-time-passes>
  86
  87 Record the amount of time needed for each pass and print it to standard
  88 error.
  89
  90 =item B<-verify>
  91
  92 Verify each pass result.
  93
  94 =item B<-disable-opt>
  95
  96 Disable all link-time optimization passes.
  97
  98 =item B<-disable-inlining>
  99
 100 Do not run the inliner pass.
 101
 102 =item B<-L>I<directory>
 103
 104 Add directory to the list of directories to search when looking for
 105 libraries.
 106
 107 =item B<-disable-internalize>
 108
 109 Do not mark all symbols as internal.
 110
 111 =item B<-internalize-public-api-file> I<filename>
 112
 113 Preserve the list of symbol names in the file filename.
 114
 115 =item B<-internalize-public-api-list &lt;list&gt;>
 116
 117 Preserve the symbol names in list.
 118
 119 =item B<-l>I<library>
 120
 121 Specify libraries to include when linking the output file.  When linking,
 122 B<gccld> will first attempt to load a file with the pathname B<library>.  If
 123 that fails, it will then attempt to load libI<library>.bc, libI<library>.a, and
 124 libI<library>.I<shared library extension>, in that order.
 125
 126 =item B<-link-as-library>
 127
 128 Link the .bc files together as a library, not an executable.
 129
 130 =item B<-native>
 131
 132 Generate a native machine code executable.
 133
 134 When generating native executables, B<gccld> first checks for a bytecode
 135 version of the library and links it in, if necessary.  If the library is
 136 missing, B<gccld> skips it.  Then, B<gccld> links in the same
 137 libraries as native code.
 138
 139 In this way, B<gccld> should be able to link in optimized bytecode
 140 subsets of common libraries and then link in any part of the library that
 141 hasn't been converted to bytecode.
 142
 143 =item B<-native-cbe>
 144
 145 Generate a native machine code executable with the LLVM C backend.
 146
 147 This option is identical to the B<-native> option, but uses the
 148 C backend to generate code for the program instead of an LLVM native
 149 code generator.
 150
 151 =item B<-s>
 152
 153 Strip symbol information from the generated executable.
 154
 155 =item B<-v>
 156
 157 Print information about actions taken.
 158
 159 =back
 160
 161 =head1 EXIT STATUS
 162
 163 If B<gccld> succeeds, it will exit with an exit status of 0.
 164 Otherwise, if an error occurs, it will exit with a non-zero exit
 165 status.
 166
 167 =head1 SEE ALSO
 168
 169 L<llvm-link|llvm-link>, L<gccas|gccas>
 170
 171 =head1 AUTHORS
 172
 173 Maintained by the LLVM Team (L<http://llvm.cs.uiuc.edu>).
 174
 175 =cut