<ol>
<li><a href="#libraries">Libraries</a>
<ol>
- <li><a href="#Modules">Bytecode Modules</a></li>
+ <li><a href="#BCModules">Bitcode Modules</a></li>
+ <li><a href="#LoadableModules">Loadable Modules</a></li>
</ol>
</li>
<li><a href="#tools">Tools</a>
Make 3.79, a widely portable makefile processor. LLVM unabashedly makes heavy
use of the features of GNU Make so the dependency on GNU Make is firm. If
you're not familiar with <tt>make</tt>, it is recommended that you read the
- <a href="http://www.gnu.org/software/make/manual/make.html">GNU Makefile Manual
- </a>.</p>
+ <a href="http://www.gnu.org/software/make/manual/make.html">GNU Makefile
+ Manual</a>.</p>
<p>While this document is rightly part of the
<a href="ProgrammersManual.html">LLVM Programmer's Manual</a>, it is treated
separately here because of the volume of content and because it is often an
LIBRARYNAME = mylib
SHARED_LIBRARY = 1
ARCHIVE_LIBRARY = 1
- DONT_BUILT_RELINKED = 1
+ DONT_BUILD_RELINKED = 1
</tt></pre>
<p>says to build a library named "mylib" with both a shared library
(<tt>mylib.so</tt>) and an archive library (<tt>mylib.a</tt>) version but
</div>
<!-- ======================================================================= -->
-<div class="doc_subsubsection"><a name="Modules">Bytecode Modules</a></div>
+<div class="doc_subsubsection"><a name="BCModules">Bitcode Modules</a></div>
<div class="doc_text">
- <p>In some situations, it is desireable to build a single bytecode module from
- a variety of sources, instead of an archive, shared library, or bytecode
- library. Bytecode modules can be specified in addition to any of the other
+ <p>In some situations, it is desireable to build a single bitcode module from
+ a variety of sources, instead of an archive, shared library, or bitcode
+ library. Bitcode modules can be specified in addition to any of the other
types of libraries by defining the <a href="#MODULE_NAME">MODULE_NAME</a>
variable. For example:</p>
<pre><tt>
MODULE_NAME = mymod
</tt></pre>
<p>will build a module named <tt>mymod.bc</tt> from the sources in the
- directory. This module will be an aggregation of all the bytecode modules
- derived from the sources. The example will also build a bytecode archive
- containing a bytecode module for each compiled source file. The difference is
+ directory. This module will be an aggregation of all the bitcode modules
+ derived from the sources. The example will also build a bitcode archive
+ containing a bitcode module for each compiled source file. The difference is
subtle, but important depending on how the module or library is to be linked.
</p>
</div>
+<!-- ======================================================================= -->
+<div class="doc_subsubsection">
+ <a name="LoadableModules">Loadable Modules</a>
+</div>
+<div class="doc_text">
+ <p>In some situations, you need to create a loadable module. Loadable modules
+ can be loaded into programs like <tt>opt</tt> or <tt>llc</tt> to specify
+ additional passes to run or targets to support. Loadable modules are also
+ useful for debugging a pass or providing a pass with another package if that
+ pass can't be included in LLVM.</p>
+ <p>LLVM provides complete support for building such a module. All you need to
+ do is use the LOADABLE_MODULE variable in your Makefile. For example, to
+ build a loadable module named <tt>MyMod</tt> that uses the LLVM libraries
+ <tt>LLVMSupport.a</tt> and <tt>LLVMSystem.a</tt>, you would specify:</p>
+ <pre><tt>
+ LIBRARYNAME := MyMod
+ LOADABLE_MODULE := 1
+ LINK_COMPONENTS := support system
+ </tt></pre>
+ <p>Use of the <tt>LOADABLE_MODULE</tt> facility implies several things:</p>
+ <ol>
+ <li>There will be no "lib" prefix on the module. This differentiates it from
+ a standard shared library of the same name.</li>
+ <li>The <a href="#SHARED_LIBRARY">SHARED_LIBRARY</a> variable is turned
+ on.</li>
+ <li>The <a href="#LINK_LIBS_IN_SHARED">LINK_LIBS_IN_SHARED</a> variable
+ is turned on.</li>
+ <li>The <a href="#DONT_BUILD_RELINKED">DONT_BUILD_RELINKED</a> variable
+ is turned on.</li>
+ </ol>
+ <p>A loadable module is loaded by LLVM via the facilities of libtool's libltdl
+ library which is part of <tt>lib/System</tt> implementation.</p>
+</div>
+
<!-- ======================================================================= -->
<div class="doc_subsection"><a name="tools">Tools</a></div>
<div class="doc_text">
<pre><tt>
TOOLNAME = mytool
USEDLIBS = mylib
- LLVMLIBS = LLVMSupport.a LLVMSystem.a
+ LINK_COMPONENTS = support system
</tt></pre>
<p>says that we are to build a tool name <tt>mytool</tt> and that it requires
three libraries: <tt>mylib</tt>, <tt>LLVMSupport.a</tt> and
<!-- ======================================================================= -->
<div class="doc_subsubsection"><a name="JIT">JIT Tools</a></div>
<div class="doc_text">
- <p>Many tools will want to use the JIT features of LLVM. However, getting the
- right set of libraries to link with is tedious, platform specific, and error
- prone. Additionally, the JIT has special linker switch options that it needs.
- Consequently, to make it easier to build tools that use the JIT, you can
- use a special value for the <tt>LLVMLIBS</tt> variable:</p>
+ <p>Many tools will want to use the JIT features of LLVM. To do this, you
+ simply specify that you want an execution 'engine', and the makefiles will
+ automatically link in the appropriate JIT for the host or an interpreter
+ if none is available:</p>
<pre><tt>
TOOLNAME = my_jit_tool
USEDLIBS = mylib
- LLVMLIBS = JIT
+ LINK_COMPONENTS = engine
</tt></pre>
- <p>Using a value of <tt>JIT</tt> for <tt>LLVMLIBS</tt> tells the makefile
- system to construct a special value for LLVMLIBS that gives the program all
- the LLVM libraries needed to run the JIT. Any additional libraries needed can
- still be specified with <tt>USEDLIBS</tt>. To get a full understanding of how
- this changes the linker command, it is recommended that you:</p>
+ <p>Of course, any additional libraries may be listed as other components. To
+ get a full understanding of how this changes the linker command, it is
+ recommended that you:</p>
<pre><tt>
cd examples/Fibonacci
make VERBOSE=1
</tt></pre>
- <p>By default, using <tt>LLVMLIBS=JIT</tt> will link in enough to support JIT
- code generation for the architecture on which the tool is linked. If you need
- additional target architectures linked in, you may specify them on the command
- line or in your <tt>Makefile</tt>. For example:</p>
- <pre><tt>
- ENABLE_X86_JIT=1
- ENABLE_SPARCV9_JIT=1
- ENALBE_PPC_JIT=1
- </tt></pre>
- <p>will cause the tool to be able to generate code for all three platforms.
- </p>
</div>
<!-- *********************************************************************** -->
<div class="doc_text">
<p>This utility target, only available when <tt>$(PROJ_OBJ_ROOT)</tt> is not
the same as <tt>$(PROJ_SRC_ROOT)</tt>, will completely clean the
- <tt>$(PROJ_OBJ_ROOT)</tt> directoy by removing its content entirely and
+ <tt>$(PROJ_OBJ_ROOT)</tt> directory by removing its content entirely and
reconfiguring the directory. This returns the <tt>$(PROJ_OBJ_ROOT)</tt>
directory to a completely fresh state. All content in the directory except
configured files and top-level makefiles will be lost.</p>
files. These sources will be built before any other target processing to
ensure they are present.</dd>
<dt><a name="BYTECODE_LIBRARY"><tt>BYTECODE_LIBRARY</tt></a></dt>
- <dd>If set to any value, causes a bytecode library (.bc) to be built.</dd>
+ <dd>If set to any value, causes a bitcode library (.bc) to be built.</dd>
<dt><a name="CONFIG_FILES"><tt>CONFIG_FILES</tt></a></dt>
<dd>Specifies a set of configuration files to be installed.</dd>
<dt><a name="DIRS"><tt>DIRS</tt></a></dt>
to the compilers and linkers to ensure that profile data can be collected
from the tools built. Use the <tt>gprof</tt> tool to analyze the output from
the profiled tools (<tt>gmon.out</tt>).</dd>
+ <dt><a name="DISABLE_ASSERTIONS"><tt>DISABLE_ASSERTIONS</tt></a></dt>
+ <dd>If set to any value, causes the build to disable assertions, even if
+ building a release or profile build. This will exclude all assertion check
+ code from the build. LLVM will execute faster, but with little help when
+ things go wrong.</dd>
<dt><a name="EXPERIMENTAL_DIRS"><tt>EXPERIMENTAL_DIRS</tt></a></dt>
<dd>Specify a set of directories that should be built, but if they fail, it
should not cause the build to fail. Note that this should only be used
<dd>Specifies a set of symbols to be exported by the linker.</dd>
<dt><a name="EXTRA_DIST"><tt>EXTRA_DIST</tt></a></dt>
<dd>Specifies additional files that should be distributed with LLVM. All
- source files, all built sources, all Makefiles, and most documentation files
+ source files, all built sources, all Makefiles, and most documentation files
will be automatically distributed. Use this variable to distribute any
files that are not automatically distributed.</dd>
- <dt><a name="FAKE_SOURCES"><tt>FAKE_SOURCES</tt><small>(optional)</small>
- </a></dt>
- <dd>This variable is like <a href="#SOURCES"><tt>SOURCES</tt></a> except that
- the source files don't need to exist. The makefiles only use
- <tt>FAKE_SOURCES</tt> to create the names of derived objects that should be
- included in the directory's result. It is assumed that the project's
- <tt>Makefile</tt> will define how to build the derived objects
- necessary.</dd>
<dt><a name="KEEP_SYMBOLS"><tt>KEEP_SYMBOLS</tt></a></dt>
<dd>If set to any value, specifies that when linking executables the
makefiles should retain debug symbols in the executable. Normally, symbols
<dt><a name="LIBRARYNAME"><tt>LIBRARYNAME</tt></a></dt>
<dd>Specify the name of the library to be built. (Required For
Libraries)</dd>
+ <dt><a name="LINK_COMPONENTS"><tt>LINK_COMPONENTS</tt></a></dt>
+ <dd>When specified for building a tool, the value of this variable will be
+ passed to the <tt>llvm-config</tt> tool to generate a link line for the
+ tool. Unlike <tt>USEDLIBS</tt> and <tt>LLVMLIBS</tt>, not all libraries need
+ to be specified. The <tt>llvm-config</tt> tool will figure out the library
+ dependencies and add any libraries that are needed. The <tt>USEDLIBS</tt>
+ variable can still be used in conjunction with <tt>LINK_COMPONENTS</tt> so
+ that additional project-specific libraries can be linked with the LLVM
+ libraries specified by <tt>LINK_COMPONENTS</tt></dd>
+ <dt><a name="LINK_LIBS_IN_SHARED"><tt>LINK_LIBS_IN_SHARED</tt></a></dt>
+ <dd>By default, shared library linking will ignore any libraries specified
+ with the <a href="LLVMLIBS">LLVMLIBS</a> or <a href="USEDLIBS">USEDLIBS</a>.
+ This prevents shared libs from including things that will be in the LLVM
+ tool the shared library will be loaded into. However, sometimes it is useful
+ to link certain libraries into your shared library and this option enables
+ that feature.</dd>
<dt><a name="LLVMLIBS"><tt>LLVMLIBS</tt></a></dt>
<dd>Specifies the set of libraries from the LLVM $(ObjDir) that will be
linked into the tool or library.</dd>
setting this variable without also setting <tt>SHARED_LIBRARY</tt> will have
no effect.</dd>
<dt><a name="MODULE_NAME"><tt>MODULE_NAME</tt></a></dt>
- <dd>Specifies the name of a bytecode module to be created. A bytecode
+ <dd>Specifies the name of a bitcode module to be created. A bitcode
module can be specified in conjunction with other kinds of library builds
- or by itself. It constructs from the sources a single linked bytecode
+ or by itself. It constructs from the sources a single linked bitcode
file.</dd>
+ <dt><a name="NO_INSTALL"><tt>NO_INSTALL</tt></a></dt>
+ <dd>Specifies that the build products of the directory should not be
+ installed but should be built even if the <tt>install</tt> target is given.
+ This is handy for directories that build libraries or tools that are only
+ used as part of the build process, such as code generators (e.g.
+ <tt>tblgen</tt>).</dd>
<dt><a name="OPTIONAL_DIRS"><tt>OPTIONAL_DIRS</tt></a></dt>
<dd>Specify a set of directories that may be built, if they exist, but its
not an error for them not to exist.</dd>
<dl>
<dt><a name="AR"><tt>AR</tt></a> <small>(defaulted)</small></dt>
<dd>Specifies the path to the <tt>ar</tt> tool.</dd>
- <dt><a name="BISON"><tt>BISON</tt></a><small>(configured)</small></dt>
- <dd>Specifies the path to the <tt>bison</tt> tool.</dd>
<dt><a name="PROJ_OBJ_DIR"><tt>PROJ_OBJ_DIR</tt></a></dt>
<dd>The directory into which the products of build rules will be placed.
This might be the same as
not.</dd>
<dt><a name="PROJ_SRC_DIR"><tt>PROJ_SRC_DIR</tt></a></dt>
<dd>The directory which contains the source files to be built.</dd>
- <dt><a name="BURG"><tt>BURG</tt></a></dt>
- <dd>Specifies the path to the <tt>burg</tt> tool.</dd>
<dt><a name="BZIP2"><tt>BZIP2</tt></a><small>(configured)</small></dt>
<dd>The path to the <tt>bzip2</tt> tool.</dd>
<dt><a name="CC"><tt>CC</tt></a><small>(configured)</small></dt>
isn't one.</dd>
<dt><a name="ECHO"><tt>ECHO</tt></a><small>(configured)</small></dt>
<dd>Specifies the path to the <tt>echo</tt> tool for printing output.</dd>
- <dt><a name="ETAGS"><tt>ETAGS</tt></a><small>(configured)</small></dt>
- <dd>Specifies the path to the <tt>etags</tt> tool.</dd>
- <dt><a name="ETAGSFLAGS"><tt>ETAGSFLAGS</tt></a><small>(configured)</small></dt>
- <dd>Provides flags to be passed to the <tt>etags</tt> tool.</dd>
<dt><a name="EXEEXT"><tt>EXEEXT</tt></a><small>(configured)</small></dt>
<dd>Provides the extension to be used on executables built by the makefiles.
The value may be empty on platforms that do not use file extensions for
executables (e.g. Unix).</dd>
- <dt><a name="FLEX"><tt>FLEX</tt></a><small>(configured)</small></dt>
- <dd>Specifies the path to the <tt>flex</tt> tool.</dd>
- <dt><a name="GCCLD"><tt>GCCLD</tt></a><small>(defaulted)</small></dt>
- <dd>Specifies the path to the <tt>gccld</tt> tool.</dd>
<dt><a name="INSTALL"><tt>INSTALL</tt></a><small>(configured)</small></dt>
<dd>Specifies the path to the <tt>install</tt> tool.</dd>
<dt><a name="LDFLAGS"><tt>LDFLAGS</tt></a><small>(configured)</small></dt>
<dd>Specifies the path to the LLVM version of the GCC 'C' Compiler</dd>
<dt><a name="LLVMGXX"><tt>LLVMGXX</tt></a><small>(defaulted)</small></dt>
<dd>Specifies the path to the LLVM version of the GCC C++ Compiler</dd>
- <dt><a name="LLVM_OBJ_ROOT"><tt>LLVM_OBJ_ROOT</tt></a><small>(configured)</small></dt>
+ <dt><a name="LLVMLD"><tt>LLVMLD</tt></a><small>(defaulted)</small></dt>
+ <dd>Specifies the path to the LLVM bitcode linker tool</dd>
+ <dt><a name="LLVM_OBJ_ROOT"><tt>LLVM_OBJ_ROOT</tt></a><small>(configured)
+ </small></dt>
<dd>Specifies the top directory into which the output of the build is
placed.</dd>
- <dt><a name="LLVM_SRC_ROOT"><tt>LLVM_SRC_ROOT</tt></a><small>(configured)</small></dt>
+ <dt><a name="LLVM_SRC_ROOT"><tt>LLVM_SRC_ROOT</tt></a><small>(configured)
+ </small></dt>
<dd>Specifies the top directory in which the sources are found.</dd>
- <dt><a name="LLVM_TARBALL_NAME"><tt>LLVM_TARBALL_NAME</tt></a><small>(configured)</small></dt>
+ <dt><a name="LLVM_TARBALL_NAME"><tt>LLVM_TARBALL_NAME</tt></a>
+ <small>(configured)</small></dt>
<dd>Specifies the name of the distribution tarball to create. This is
configured from the name of the project and its version number.</dd>
<dt><a name="MKDIR"><tt>MKDIR</tt></a><small>(defaulted)</small></dt>
<dt><a name="BuildMode"><tt>BuildMode</tt></a></dt>
<dd>The name of the type of build being performed: Debug, Release, or
Profile</dd>
- <dt><a name="bytecode_libdir"><tt>bytecode_libdir</tt></a></dt>
- <dd>The directory into which bytecode libraries will ultimately be installed.
- This value is derived from the <tt>--prefix</tt> option given to
+ <dt><a name="bitcode_libdir"><tt>bytecode_libdir</tt></a></dt>
+ <dd>The directory into which bitcode libraries will ultimately be
+ installed. This value is derived from the <tt>--prefix</tt> option given to
<tt>configure</tt>.</dd>
<dt><a name="ConfigureScriptFLAGS"><tt>ConfigureScriptFLAGS</tt></a></dt>
<dd>Additional flags given to the <tt>configure</tt> script when
BCCompile.C
BCCompile.CXX
BCLinkLib
- Burg
C.Flags
Compile.C
CompileCommonOpts
CXX.Flags
DependFiles
DestArchiveLib
- DestBytecodeLib
+ DestBitcodeLib
DestModule
DestRelinkedLib
DestSharedLib
INCFiles
InternalTargets
LD.Flags
- LexFiles
- LexOutput
LibName.A
LibName.BC
LibName.LA
LLVMToolDir
LLVMUsedLibs
LocalTargets
- LTCompile.C
- LTCompile.CXX
- LTInstall
Module
ObjectsBC
ObjectsLO
ToolBuildPath
TopLevelTargets
UserTargets
- YaccFiles
- YaccOutput
</tt></p>
</div>
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
- src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
- src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="mailto:rspencer@x10sys.com">Reid Spencer</a><br>
- <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a><br>
+ <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
Last modified: $Date$
</address>
-
</body>
</html>
-<!-- vim: sw=2 noai
--->
projects / oota-llvm.git / blobdiff