X-Git-Url: http://plrg.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FMakefileGuide.html;h=f996144e145372156f5e0d5b7acef8bfecc98864;hb=08d012eba490c4906ec773c39db9f2a18a78c997;hp=c91b14c3737761dbd294bdec0a8178f99bc775de;hpb=7c7e9aa590a10a1bb6e7a7babc1d3769fc41a5ea;p=oota-llvm.git diff --git a/docs/MakefileGuide.html b/docs/MakefileGuide.html index c91b14c3737..f996144e145 100644 --- a/docs/MakefileGuide.html +++ b/docs/MakefileGuide.html @@ -30,7 +30,8 @@
+While this document is rightly part of the LLVM Programmer's Manual, it is treated separately here because of the volume of content and because it is often an @@ -115,10 +117,15 @@ software, but it can build yours too. Built into the system is knowledge of the llvm/projects directory. Any directory under projects that has both a configure script and a Makefile is assumed - to be a project that uses the LLVM Makefile system. This allows your project + to be a project that uses the LLVM Makefile system. Building software that + uses LLVM does not require the LLVM Makefile System nor even placement in the + llvm/projects directory. However, doing so will allow your project to get up and running quickly by utilizing the built-in features that are used to compile LLVM. LLVM compiles itself using the same features of the makefile system as used for projects.
+For complete details on setting up your projects configuration, simply + mimic the llvm/projects/sample project or for further details, + consult the Projects.html page.
@@ -225,17 +232,16 @@ Normally, the makefile system will build all the software into a single libname.o (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: + dissolved. Optionally, you can ask for a shared library (.so) or archive + library (.a) built. Archive libraries are the default. For example:LIBRARYNAME = mylib SHARED_LIBRARY = 1 ARCHIVE_LIBRARY = 1 - DONT_BUILT_RELINKED = 1
says to build a library named "mylib" with both a shared library - (mylib.so) and an archive library (mylib.a) version but - not to build the relinked object (mylib.o). The contents of all the + (mylib.so) and an archive library (mylib.a) version. 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 @@ -253,11 +259,11 @@ -
+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 +
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 MODULE_NAME variable. For example:
@@ -266,13 +272,45 @@ MODULE_NAME = mymod
will build a module named mymod.bc 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.
In some situations, you need to create a loadable module. Loadable modules + can be loaded into programs like opt or llc 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.
+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 MyMod that uses the LLVM libraries + LLVMSupport.a and LLVMSystem.a, you would specify:
++ LIBRARYNAME := MyMod + LOADABLE_MODULE := 1 + LINK_COMPONENTS := support system ++
Use of the LOADABLE_MODULE facility implies several things:
+A loadable module is loaded by LLVM via the facilities of libtool's libltdl + library which is part of lib/System implementation.
+TOOLNAME = mytool USEDLIBS = mylib - LLVMLIBS = LLVMSupport.a LLVMSystem.a + LINK_COMPONENTS = support system
says that we are to build a tool name mytool and that it requires three libraries: mylib, LLVMSupport.a and @@ -311,36 +349,22 @@
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 LLVMLIBS variable:
+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:
TOOLNAME = my_jit_tool USEDLIBS = mylib - LLVMLIBS = JIT + LINK_COMPONENTS = engine-
Using a value of JIT for LLVMLIBS 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 USEDLIBS. To get a full understanding of how - this changes the linker command, it is recommended that you:
+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:
cd examples/Fibonacci make VERBOSE=1-
By default, using LLVMLIBS=JIT 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 Makefile. For example:
-- ENABLE_X86_JIT=1 - ENABLE_SPARCV9_JIT=1 - ENALBE_PPC_JIT=1 --
will cause the tool to be able to generate code for all three platforms. -
This utility target will force a reconfigure of LLVM or your project. It - simply runs $(BUILD_OBJ_ROOT)/config.status --recheck to rerun the + simply runs $(PROJ_OBJ_ROOT)/config.status --recheck to rerun the configuration tests and rebuild the configured files. This isn't generally useful as the makefiles will reconfigure themselves whenever its necessary.
@@ -544,10 +568,10 @@This utility target, only available when $(BUILD_OBJ_ROOT) is not - the same as $(BUILD_SRC_ROOT), will completely clean the - $(BUILD_OBJ_ROOT) directoy by removing its content entirely and - reconfiguring the directory. This returns the $(BUILD_OBJ_ROOT) +
This utility target, only available when $(PROJ_OBJ_ROOT) is not + the same as $(PROJ_SRC_ROOT), will completely clean the + $(PROJ_OBJ_ROOT) directory by removing its content entirely and + reconfiguring the directory. This returns the $(PROJ_OBJ_ROOT) directory to a completely fresh state. All content in the directory except configured files and top-level makefiles will be lost.
Use with caution.