X-Git-Url: http://demsky.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FUsingLibraries.html;h=ded2d812f7d30082e1f401a229ab57bc0755de81;hb=60150a3dc498b78a10cfe9b467f08f1cdec9052d;hp=d6ce8fa4ccc5e89568ea41195eda0f2ec450c4d3;hpb=6175735da4811401116b1e86405b4be5bd9d39ae;p=oota-llvm.git diff --git a/docs/UsingLibraries.html b/docs/UsingLibraries.html index d6ce8fa4ccc..ded2d812f7d 100644 --- a/docs/UsingLibraries.html +++ b/docs/UsingLibraries.html @@ -1,267 +1,411 @@ - +
-Written by Reid Spencer
-+ + -
Warning: This document is out of date, please see llvm-config for more information.
+This document describes the contents of the many objects files and libraries -that are produced by compiling LLVM. To make use of LLVM this information is -needed in order to understand what files should be linked into your program. +
Amongst other things, LLVM is a toolkit for building compilers, linkers, + runtime executives, virtual machines, and other program execution related + tools. In addition to the LLVM tool set, the functionality of LLVM is + available through a set of libraries. To use LLVM as a toolkit for + constructing tools, a developer needs to understand what is contained in the + various libraries, what they depend on, and how to use them. Fortunately, + there is a tool, llvm-config to aid with this. This document + describes the contents of the libraries and how to use llvm-config + to generate command line options.
If you're writing a compiler, virtual machine, or any other utility for - LLVM, you'll need to figure out which of the many .a (archive) and .o - (object) files you will need to link with to be successful. An - understanding of the contents of these files and their inter-relationships - will be useful in coming up with an optimal specification for the objects - and libraries to link with. -
-The purpose of this document is to hopefully reduce some of the trial and - error that the author experienced in using LLVM. -
+If you're writing a compiler, virtual machine, or any other utility based + on LLVM, you'll need to figure out which of the many libraries files you will + need to link with to be successful. An understanding of the contents of these + libraries will be useful in coming up with an optimal specification for the + libraries to link with. The purpose of this document is to reduce some of + the trial and error that the author experienced in using LLVM.
+LLVM produces two types of libraries: archives (ending in .a) and + objects (ending in .o). However, both are libraries. Libraries ending + in .o are known as re-linked libraries because they contain all the + compilation units of the library linked together as a single .o file. + Furthermore, several of the libraries have both forms of library. The + re-linked libraries are used whenever you want to include all symbols from the + library. The archive libraries are used whenever you want to only resolve + outstanding symbols at that point in the link without including everything in + the library.
+If you're using the LLVM Makefile system to link your tools,you will use + the LLVMLIBS make variable. + (see the Makefile Guide for + details). This variable specifies which LLVM libraries to link into your tool + and the order in which they will be linked. You specify re-linked libraries by + naming the library without a suffix. You specify archive libraries by naming + the library with a .a suffix but without the lib prefix. The + order in which the libraries appear in the LLVMLIBS variable + definition is the order in which they will be linked. Getting this order + correct for your tool can sometimes be challenging.
The table below provides a summary of the basic contents of each file.
-Summary Of LLVM Library And Object Files - | -||
Library |
- Description |
-|
libipo.a | -- An archive of all inter-procedural optimizations. - | -|
libscalaropts.a | -- An archive of all scalar optimizations. - | -|
libtransforms.a | -- An archive of all code transformations. - | -|
libtarget.a | -- An archive containing target (machine) specific code. - | -|
libanalysis.a | -- An archive containing analysis code. - | -|
libdatastructure.a | -- An archive containing optimizations for data structures. - | -|
libinstrument.a | -No idea. | -|
libregalloc.a | -Register Allocation code. | -|
libipa.a | -Inter-procedural ?? | -|
libtransformutils.a | -- Utiltities for transformations? - | -|
libsupport.a | -General support utilities | -|
Object File |
- Description |
-|
support.o | -General support utilities | -|
asmparser.o | -Assembler Parser | -|
bcreader.o | -Byte Code Reader | -|
bcwriter.o | -Byte Code Writer | -|
sched.o | -Scheduler? For What? | -|
selectiondag.o | -Selection Directed Acyclic Graph? | -|
transformutils.o | -Utilities for code transformations | -|
ipa.o | -Inter-Procedural Analysis Optimizations | -|
select.o | -Select Statement? | -|
cwriter.o | -"C" Code Writer | -|
profpaths.o | -Profile Paths? | -|
regalloc.o | -Register Allocation | -|
instrument.o | -Instrumentation? Of What? | -|
datastructure.o | -Data Structure Analysis | -|
codegen.o | -Native code generation | -|
livevar.o | -Live Variable Analysis | -|
vmcore.o | -Virtual Machine Core | -|
lli-interpreter.o | -Interpreter for LLVM ByteCode | -|
lli-jit.o | -- Just-In-Time Compiler For LLVM ByteCode - | -|
executionengine.o | -Engine for LLI | -|
debugger.o | -Source Level Debugging Support | -|
analysis.o | -General Framework For Analysis? | -|
sparc.o | -Sun SPARC Processor Specific | -|
target.o | -Target Machine Support? | -|
transforms.o | -Code Transformations | -|
x86.o | -Intel x86 Processor Specific | -|
powerpc.o | -PowerPC Processor Specific | -|
scalaropts.o | -Optimizations For Scalars | -|
ipo.o | -Inter-Procedural Optimization | -|
trace.o | -Support For Tracing/Debugging? | -|
profile_rt.o | -Runtime Library For Profiler | -|
sample.o | -Sample Program ? | -|
stkr_compiler.o | -Stacker Language Compiler Library | -|
stkr_runtime.o | -Stacker Language Runtime Library | -
Library | Forms | Description |
---|---|---|
Core Libraries | ||
LLVMArchive | .a | +LLVM archive reading and writing |
LLVMAsmParser | .a | +LLVM assembly parsing |
LLVMBCReader | .a | +LLVM bitcode reading |
LLVMBCWriter | .a | +LLVM bitcode writing |
LLVMCore | .a | +LLVM core intermediate representation |
LLVMDebugger | .a | +Source level debugging support |
LLVMLinker | .a | +Bitcode and archive linking interface |
LLVMSupport | .a | +General support utilities |
LLVMSystem | .a | +Operating system abstraction layer |
LLVMbzip2 | .a | +BZip2 compression library |
Analysis Libraries | ||
LLVMAnalysis | .a | +Various analysis passes. |
LLVMDataStructure | .o | +Data structure analysis passes. |
LLVMipa | .a | +Inter-procedural analysis passes. |
Transformation Libraries | ||
LLVMInstrumentation | .a | +Instrumentation passes. |
LLVMipo | .a | +All inter-procedural optimization passes. |
LLVMScalarOpts | .a | +All scalar optimization passes. |
LLVMTransformUtils | .a | +Transformation utilities used by many passes. |
Code Generation Libraries | ||
LLVMCodeGen | .o | +Native code generation infrastructure |
LLVMSelectionDAG | .o | +Aggressive instruction selector for directed acyclic graphs |
Target Libraries | ||
LLVMAlpha | .o | +Code generation for Alpha architecture |
LLVMARM | .o | +Code generation for ARM architecture |
LLVMCBackend | .o | +'C' language code generator. |
LLVMIA64 | .o | +Code generation for IA64 architecture |
LLVMPowerPC | .o | +Code generation for PowerPC architecture |
LLVMSparc | .o | +Code generation for Sparc architecture |
LLVMTarget | .a | +Generic code generation utilities. |
LLVMX86 | .o | +Code generation for Intel x86 architecture |
Runtime Libraries | ||
LLVMInterpreter | .o | +Bitcode Interpreter |
LLVMJIT | .o | +Bitcode JIT Compiler |
LLVMExecutionEngine | .o | +Virtual machine engine |
The llvm-config tool is a perl script that produces on its output + various kinds of information. For example, the source or object directories + used to build LLVM can be accessed by passing options to llvm-config. + For complete details on this tool, please see the + manual page.
+To understand the relationships between libraries, the llvm-config + can be very useful. If all you know is that you want certain libraries to + be available, you can generate the complete set of libraries to link with + using one of four options, as below:
+If you wish to delve further into how llvm-config generates the + correct order (based on library dependencies), please see the tool named + GenLibDeps.pl in the utils source directory of LLVM.
+ + + + + + + +This graph shows the dependency of archive libraries on other archive + libraries or objects. Where a library has both archive and object forms, only + the archive form is shown.
+This graph shows the dependency of object files on archive libraries or + other objects. Where a library has both object and archive forms, only the + dependency to the archive form is shown.
+The following list shows the dependency relationships between libraries in + textual form. The information is the same as shown on the graphs but arranged + alphabetically.
+No matter what you do with LLVM, you'll always need to link with vmcore.o - and support.a.
+No matter what you do with LLVM, the last three entries in the value of + your LLVMLIBS make variable should always be: + LLVMCore LLVMSupport.a LLVMSystem.a. There are no LLVM + programs that don't depend on these three.
Need more rules of thumb here.
+There is never any point to linking both the re-linked (.o) and + the archive (.a) versions of a library. Since the re-linked version + includes the entire library, the archive version will not resolve any symbols. + You could even end up with link error if you place the archive version before + the re-linked version on the linker's command line.