Misha Brukman | eedba5e | 2004-09-05 02:56:39 +0000 | [diff] [blame] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.1//EN" |
| 2 | "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> |
Chris Lattner | 6175735 | 2004-02-27 06:28:34 +0000 | [diff] [blame] | 3 | <html> |
| 4 | <head> |
Reid Spencer | 341d714 | 2004-10-31 23:00:25 +0000 | [diff] [blame] | 5 | <title>Using The LLVM Libraries</title> |
Chris Lattner | 6175735 | 2004-02-27 06:28:34 +0000 | [diff] [blame] | 6 | <link rel="stylesheet" href="llvm.css" type="text/css"> |
| 7 | </head> |
| 8 | <body> |
Reid Spencer | 341d714 | 2004-10-31 23:00:25 +0000 | [diff] [blame] | 9 | <div class="doc_title">Using The LLVM Libraries</div> |
Chris Lattner | 6175735 | 2004-02-27 06:28:34 +0000 | [diff] [blame] | 10 | <ol> |
| 11 | <li><a href="#abstract">Abstract</a></li> |
| 12 | <li><a href="#introduction">Introduction</a></li> |
Reid Spencer | 341d714 | 2004-10-31 23:00:25 +0000 | [diff] [blame] | 13 | <li><a href="#descriptions">Library Descriptions</a></li> |
Chris Lattner | 6175735 | 2004-02-27 06:28:34 +0000 | [diff] [blame] | 14 | <li><a href="#rot">Linkage Rules Of Thumb</a> |
| 15 | <ol> |
Reid Spencer | 4148266 | 2004-10-31 23:24:31 +0000 | [diff] [blame^] | 16 | <li><a href="#always">Always link LLVMCore, LLVMSupport, LLVMSystem</a> |
| 17 | <li><a href="#onlyone">Never link both archive and re-linked</a> |
Chris Lattner | 6175735 | 2004-02-27 06:28:34 +0000 | [diff] [blame] | 18 | </ol> |
| 19 | </li> |
| 20 | </ol> |
Chris Lattner | 7911ce2 | 2004-05-23 21:07:27 +0000 | [diff] [blame] | 21 | |
| 22 | <div class="doc_author"> |
| 23 | <p>Written by <a href="mailto:rspencer@x10sys.com">Reid Spencer</a></p> |
Chris Lattner | 6175735 | 2004-02-27 06:28:34 +0000 | [diff] [blame] | 24 | </div> |
Chris Lattner | 7911ce2 | 2004-05-23 21:07:27 +0000 | [diff] [blame] | 25 | |
Chris Lattner | 6175735 | 2004-02-27 06:28:34 +0000 | [diff] [blame] | 26 | <!-- ======================================================================= --> |
| 27 | <div class="doc_section"><a name="abstract">Abstract</a></div> |
| 28 | <div class="doc_text"> |
Reid Spencer | 341d714 | 2004-10-31 23:00:25 +0000 | [diff] [blame] | 29 | <p>Amongst other things, LLVM is a toolkit for building compilers, linkers, |
| 30 | runtime executives, virtual machines, and other program execution related |
| 31 | tools. In addition to the LLVM tool set, the functionality of LLVM is |
| 32 | available through a set of libraries. To use LLVM as a toolkit for |
| 33 | constructing tools, a developer needs to understand what is contained in the |
| 34 | various libraries, what they depend on, and how to use them. This document |
| 35 | describes the contents of the libraries and how and when to use them. |
Chris Lattner | 6175735 | 2004-02-27 06:28:34 +0000 | [diff] [blame] | 36 | </p> |
| 37 | </div> |
Reid Spencer | 341d714 | 2004-10-31 23:00:25 +0000 | [diff] [blame] | 38 | |
Chris Lattner | 6175735 | 2004-02-27 06:28:34 +0000 | [diff] [blame] | 39 | <!-- ======================================================================= --> |
| 40 | <div class="doc_section"> <a name="introduction">Introduction</a></div> |
| 41 | <div class="doc_text"> |
Reid Spencer | 341d714 | 2004-10-31 23:00:25 +0000 | [diff] [blame] | 42 | <p>If you're writing a compiler, virtual machine, or any other utility based |
| 43 | on LLVM, you'll need to figure out which of the many libraries files you will |
| 44 | need to link with to be successful. An understanding of the contents of these |
| 45 | files and their inter-relationships will be useful in coming up with an optimal |
| 46 | specification for the libraries to link with. The purpose of this document is |
| 47 | to reduce some of the trial and error that the author experienced in using |
| 48 | LLVM.</p> |
| 49 | <p>LLVM produces two types of libraries: archives (ending in <tt>.a</tt>) and |
| 50 | objects (ending in <tt>.o</tt>). However, both are libraries. Libraries ending |
| 51 | in <tt>.o</tt> are known as re-linked libraries because they contain all the |
| 52 | compilation units of the library linked together as a single <tt>.o</tt> file. |
| 53 | Furthermore, many of the libraries have <em>both</em> forms of library. The |
| 54 | re-linked libraries are used whenever you want to include all symbols from the |
| 55 | library. The archive libraries are used whenever you want to only resolve |
| 56 | outstanding symbols at that point in the link without including everything in |
| 57 | the library. </p> |
| 58 | <p>When linking your tools, you will use the <tt>LLVMLIBS</tt> make variable. |
| 59 | (see the <a href="MakefileGuide.html#LLVMLIBS">Makefile Guide</a> for |
| 60 | details). This variable specifies which LLVM libraries to link into your tool |
| 61 | and the order in which they will be linked. You specify re-linked libraries by |
| 62 | naming the library without a suffix. You specify archive libraries by naming |
| 63 | the library with a <tt>.a</tt> suffix but without the <tt>lib</tt> prefix. The |
| 64 | order in which the libraries appear in the <tt>LLVMLIBS</tt> variable |
| 65 | definition is the order in which they will be linked. Getting this order |
| 66 | correct for your tool can sometimes be challenging. |
Chris Lattner | 6175735 | 2004-02-27 06:28:34 +0000 | [diff] [blame] | 67 | </div> |
| 68 | <!-- ======================================================================= --> |
Reid Spencer | 341d714 | 2004-10-31 23:00:25 +0000 | [diff] [blame] | 69 | <div class="doc_section"><a name="descriptions"></a>Library Descriptions</div> |
Chris Lattner | 6175735 | 2004-02-27 06:28:34 +0000 | [diff] [blame] | 70 | <div class="doc_text"> |
Reid Spencer | 341d714 | 2004-10-31 23:00:25 +0000 | [diff] [blame] | 71 | <p>The table below categorizes each library |
| 72 | <table style="text-align:left"> |
| 73 | <tr><th>Library</th><th>Forms</th><th>Description</th></tr> |
| 74 | <tr><th colspan=3">Core Libraries</th></tr> |
Reid Spencer | 4148266 | 2004-10-31 23:24:31 +0000 | [diff] [blame^] | 75 | <tr><td>LLVMAsmParser</td><td><tt>.o</tt></td> |
| 76 | <td>LLVM Assembly Parsing</td></tr> |
| 77 | <tr><td>LLVMBCReader</td><td><tt>.o</tt></td> |
| 78 | <td>LLVM Bytecode Reading</td></tr> |
| 79 | <tr><td>LLVMBCWriter</td><td><tt>.o</tt></td> |
| 80 | <td>LLVM Bytecode Writing</td></tr> |
| 81 | <tr><td>LLVMDebugger</td><td><tt>.o</tt></td> |
| 82 | <td>Source Level Debugging Support</td></tr> |
| 83 | <tr><td>LLVMSupport</td><td><tt>.a .o</tt></td> |
| 84 | <td>General support utilities</td></tr> |
| 85 | <tr><td>LLVMSystem</td><td><tt>.a .o</tt></td> |
| 86 | <td>Operating system abstraction</td></tr> |
| 87 | <tr><td>LLVMCore</td><td><tt>.o</tt></td> |
| 88 | <td>LLVM Core IR</td></tr> |
Reid Spencer | 341d714 | 2004-10-31 23:00:25 +0000 | [diff] [blame] | 89 | |
| 90 | <tr><th colspan=3">Analysis Libraries</th></tr> |
Reid Spencer | 4148266 | 2004-10-31 23:24:31 +0000 | [diff] [blame^] | 91 | <tr><td>LLVMAnalysis</td><td><tt>.a .o</tt></td> |
| 92 | <td>Various analysis passes.</td></tr> |
| 93 | <tr><td>LLVMDataStructure</td><td><tt>.a .o</tt></td> |
| 94 | <td>Data structure analysis passes.</td></tr> |
| 95 | <tr><td>LLVMipa</td><td><tt>.a .o</tt></td> |
| 96 | <td>Inter-procedural analysis passes.</td></tr> |
Reid Spencer | 341d714 | 2004-10-31 23:00:25 +0000 | [diff] [blame] | 97 | |
Reid Spencer | 4148266 | 2004-10-31 23:24:31 +0000 | [diff] [blame^] | 98 | <tr><th colspan=3">Transformation Libraries</th></tr> |
| 99 | <tr><td>LLVMInstrumentation</td><td><tt>.a .o</tt></td> |
| 100 | <td>Instrumentation passes.</td></tr> |
| 101 | <tr><td>LLVMipo</td><td><tt>.a .o</tt></td> |
| 102 | <td>All inter-procedural optimization passes.</td></tr> |
| 103 | <tr><td>LLVMScalarOpts</td><td><tt>.a .o</tt></td> |
| 104 | <td>All scalar optimization passes.</td></tr> |
| 105 | <tr><td>LLVMTransforms</td><td><tt>.a .o</tt></td> |
| 106 | <td>Uncategorized transformation passes.</td></tr> |
| 107 | <tr><td>LLVMTransformUtils</td><td><tt>.a .o</tt></td> |
| 108 | <td>Transformation utilities.</td></tr> |
| 109 | <tr><td>LLVMProfilePaths</td><td><tt>.o</tt></td> |
| 110 | <td>Profile paths for instrumentation.</td></tr> |
Reid Spencer | 341d714 | 2004-10-31 23:00:25 +0000 | [diff] [blame] | 111 | |
| 112 | <tr><th colspan=3">Code Generation Libraries </th></tr> |
Reid Spencer | 4148266 | 2004-10-31 23:24:31 +0000 | [diff] [blame^] | 113 | <tr><td>LLVMCodeGen</td><td><tt>.o</tt></td> |
| 114 | <td>Native code generation infrastructure</td></tr> |
Reid Spencer | 341d714 | 2004-10-31 23:00:25 +0000 | [diff] [blame] | 115 | |
| 116 | <tr><th colspan=3">Target Libraries</th></tr> |
Reid Spencer | 4148266 | 2004-10-31 23:24:31 +0000 | [diff] [blame^] | 117 | <tr><td>LLVMCBackend</td><td><tt>.o</tt></td> |
| 118 | <td>'C' language code generator.</td></tr> |
| 119 | <tr><td>LLVMPowerPC</td><td><tt>.o</tt></td> |
| 120 | <td>PowerPC code generation backend</td></tr> |
| 121 | <tr><td>LLVMSelectionDAG</td><td><tt>.o</tt></td> |
| 122 | <td>Aggressive instruction selector for Directed Acyclic Graphs.</td></tr> |
| 123 | <tr><td>LLVMSkeleton</td><td><tt>.a .o</tt></td> |
| 124 | <td>Skeleton for a code generation backend.</td></tr> |
| 125 | <tr><td>LLVMSparcV9</td><td><tt>.o</tt></td> |
| 126 | <td>Code generation for SparcV9.</td></tr> |
| 127 | <tr><td>LLVMSparcV9RegAlloc</td><td><tt>.a .o</tt></td> |
| 128 | <td>Graph-coloring register allocator for SparcV9.</td></tr> |
| 129 | <tr><td>LLVMSparcV9InstrSched</td><td><tt>.o</tt></td> |
| 130 | <td>Instruction scheduling for SparcV9.</td></tr> |
| 131 | <tr><td>LLVMSparcV9LiveVar</td><td><tt>.o</tt></td> |
| 132 | <td>Live variable analysis SparcV9.</td></tr> |
| 133 | <tr><td>LLVMSparcV9ModuloSched</td><td><tt>.o</tt></td> |
| 134 | <td>Modulo scheduling for SparcV9.</td></tr> |
| 135 | <tr><td>LLVMTarget</td><td><tt>.a .o</tt></td> |
| 136 | <td>Generic code generation utilities.</td></tr> |
| 137 | <tr><td>LLVMX86</td><td><tt>.o</tt></td> |
| 138 | <td>Intel x86 code generation backend</td></tr> |
Reid Spencer | 341d714 | 2004-10-31 23:00:25 +0000 | [diff] [blame] | 139 | |
| 140 | <tr><th colspan=3">Runtime Libraries</th></tr> |
Reid Spencer | 4148266 | 2004-10-31 23:24:31 +0000 | [diff] [blame^] | 141 | <tr><td>LLVMInterpreter</td><td><tt>.o</tt></td> |
| 142 | <td>Bytecode Interpreter</td></tr> |
| 143 | <tr><td>LLVMJIT</td><td><tt>.o</tt></td> |
| 144 | <td>Bytecode JIT Compiler</td></tr> |
| 145 | <tr><td>LLVMExecutionEngine</td><td><tt>.o</tt></td> |
| 146 | <td>Virtual machine engine</td></tr> |
| 147 | <tr><td>LLVMexecve</td><td><tt>.o</tt></td> |
| 148 | <td>execve(2) replacement for llee</td></tr> |
Chris Lattner | 6175735 | 2004-02-27 06:28:34 +0000 | [diff] [blame] | 149 | </table> |
| 150 | </div> |
Reid Spencer | 341d714 | 2004-10-31 23:00:25 +0000 | [diff] [blame] | 151 | |
Chris Lattner | 6175735 | 2004-02-27 06:28:34 +0000 | [diff] [blame] | 152 | <!-- ======================================================================= --> |
| 153 | <div class="doc_section"><a name="rot">Linkage Rules Of Thumb</a></div> |
| 154 | <div class="doc_text"> |
| 155 | <p>This section contains various "rules of thumb" about what files you |
| 156 | should link into your programs.</p> |
| 157 | </div> |
| 158 | <!-- ======================================================================= --> |
Reid Spencer | 341d714 | 2004-10-31 23:00:25 +0000 | [diff] [blame] | 159 | <div class="doc_subsection"><a name="always">Always Link LLVMCore LLVMSupport |
| 160 | LLVMSystem</a></div> |
Chris Lattner | 6175735 | 2004-02-27 06:28:34 +0000 | [diff] [blame] | 161 | <div class="doc_text"> |
Reid Spencer | 341d714 | 2004-10-31 23:00:25 +0000 | [diff] [blame] | 162 | <p>No matter what you do with LLVM, the last three entries in your linke line |
| 163 | should always be: <tt>LLVMCore LLVMSupport.a LLVMSystem.a</tt>.</p> |
Chris Lattner | 6175735 | 2004-02-27 06:28:34 +0000 | [diff] [blame] | 164 | </div> |
| 165 | <!-- ======================================================================= --> |
Reid Spencer | 341d714 | 2004-10-31 23:00:25 +0000 | [diff] [blame] | 166 | <div class="doc_subsection"><a name="onlyone">Never link both archive and |
| 167 | re-linked library</a></div> |
Chris Lattner | 6175735 | 2004-02-27 06:28:34 +0000 | [diff] [blame] | 168 | <div class="doc_text"> |
Reid Spencer | 341d714 | 2004-10-31 23:00:25 +0000 | [diff] [blame] | 169 | <p>There is never any point to linking both the re-linked (<tt>.o</tt>) and |
| 170 | the archive (<tt>.a</tt>) versions of a library. Since the re-linked version |
| 171 | includes the entire library, the archive version will not resolve any symbols. |
| 172 | You could even end up with link error is you place the archive version before |
| 173 | the re-linked version on the linker's command line.</p> |
Chris Lattner | 6175735 | 2004-02-27 06:28:34 +0000 | [diff] [blame] | 174 | </div> |
| 175 | <!-- ======================================================================= --> |
| 176 | <hr> |
| 177 | <div class="doc_footer"> |
| 178 | <address><a href="mailto:rspencer@x10sys.com">Reid Spencer</a></address> |
| 179 | <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a> |
| 180 | <br>Last modified: $Date$ </div> |
| 181 | </body> |
| 182 | </html> |
| 183 | <!-- vim: sw=2 ts=2 ai |
| 184 | --> |