+<!-- *********************************************************************** -->
+<div class="doc_section"><a name="tutorial">Tutorial</a></div>
+<!-- *********************************************************************** -->
+<div class="doc_text">
+ <p>This section provides some examples of the different kinds of modules you
+ can build with the LLVM makefile system. In general, each directory you
+ provide will build a single object although that object may be composed of
+ additionally compiled components.</p>
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection"><a name="libraries">Libraries</a></div>
+<div class="doc_text">
+ <p>Only a few variable definitions are needed to build a regular library.
+ Normally, the makefile system will build all the software into a single
+ <tt>libname.o</tt> (pre-linked) object. This means the library is not
+ searchable and that the distinction between compilation units has been
+ dissolved. Optionally, you can ask for a shared library (.so), archive library
+ (.a) or to not have the default (relinked) library built. For example:</p>
+ <pre><tt>
+ LIBRARYNAME = mylib
+ SHARED_LIBRARY = 1
+ ARCHIVE_LIBRARY = 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
+ not to build the relinked object (<tt>mylib.o</tt>). The contents of all the
+ libraries produced will be the same, they are just constructed differently.
+ Note that you normally do not need to specify the sources involved. The LLVM
+ Makefile system will infer the source files from the contents of the source
+ directory.</p>
+ <p>The <tt>LOADABLE_MODULE=1</tt> directive can be used in conjunction with
+ <tt>SHARED_LIBRARY=1</tt> to indicate that the resulting shared library should
+ be openable with the <tt>dlopen</tt> function and searchable with the
+ <tt>dlsym</tt> function (or your operating system's equivalents). While this
+ isn't strictly necessary on Linux and a few other platforms, it is required
+ on systems like HP-UX and Darwin. You should use <tt>LOADABLE_MODULE</tt> for
+ any shared library that you intend to be loaded into an tool via the
+ <tt>-load</tt> option. See the
+ <a href="WritingAnLLVMPass.html#makefile">WritingAnLLVMPass.html</a> document
+ for an example of why you might want to do this.
+</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 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>
+
+<!-- ======================================================================= -->
+<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">
+ <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>
+</div>
+
+<!-- ======================================================================= -->
+<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. 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>
+