+<!-- ======================================================================= -->
+<h4><a name="BCModules">Bitcode Modules</a></h4>
+<div>
+ <p>In some situations, it is desirable 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>
+ LIBRARYNAME = mylib
+ BYTECODE_LIBRARY = 1
+ 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 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>
+
+<!-- ======================================================================= -->
+<h4>
+ <a name="LoadableModules">Loadable Modules</a>
+</h4>
+<div>
+ <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>
+ </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>
+
+<!-- ======================================================================= -->
+<h3><a name="tools">Tools</a></h3>
+<div>
+ <p>For building executable programs (tools), you must provide the name of the
+ tool and the names of the libraries you wish to link with the tool. For
+ example:</p>
+ <pre><tt>
+ TOOLNAME = mytool
+ USEDLIBS = mylib
+ 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
+ <tt>LLVMSystem.a</tt>.</p>
+ <p>Note that two different variables are use to indicate which libraries are
+ linked: <tt>USEDLIBS</tt> and <tt>LLVMLIBS</tt>. This distinction is necessary
+ to support projects. <tt>LLVMLIBS</tt> refers to the LLVM libraries found in
+ the LLVM object directory. <tt>USEDLIBS</tt> refers to the libraries built by
+ your project. In the case of building LLVM tools, <tt>USEDLIBS</tt> and
+ <tt>LLVMLIBS</tt> can be used interchangeably since the "project" is LLVM
+ itself and <tt>USEDLIBS</tt> refers to the same place as <tt>LLVMLIBS</tt>.
+ </p>
+ <p>Also note that there are two different ways of specifying a library: with a
+ <tt>.a</tt> suffix and without. Without the suffix, the entry refers to the
+ re-linked (.o) file which will include <em>all</em> symbols of the library.
+ This is useful, for example, to include all passes from a library of passes.
+ If the <tt>.a</tt> suffix is used then the library is linked as a searchable
+ library (with the <tt>-l</tt> option). In this case, only the symbols that are
+ unresolved <em>at that point</em> will be resolved from the library, if they
+ exist. Other (unreferenced) symbols will not be included when the <tt>.a</tt>
+ syntax is used. Note that in order to use the <tt>.a</tt> suffix, the library
+ in question must have been built with the <tt>ARCHIVE_LIBRARY</tt> option set.
+ </p>
+
+<!-- ======================================================================= -->
+<h4><a name="JIT">JIT Tools</a></h4>
+<div>
+ <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
+ LINK_COMPONENTS = engine
+ </tt></pre>
+ <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>
+</div>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="targets">Targets Supported</a></h2>
+<!-- *********************************************************************** -->
+
+<div>