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 @@ -113,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.
@@ -229,7 +238,7 @@ LIBRARYNAME = mylib SHARED_LIBRARY = 1 ARCHIVE_LIBRARY = 1 - DONT_BUILT_RELINKED = 1 + DONT_BUILD_RELINKED = 1says to build a library named "mylib" with both a shared library (mylib.so) and an archive library (mylib.a) version but @@ -238,15 +247,25 @@ 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.
+The LOADABLE_MODULE=1 directive can be used in conjunction with + SHARED_LIBRARY=1 to indicate that the resulting shared library should + be openable with the dlopen function and searchable with the + dlsym 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 LOADABLE_MODULE for + any shared library that you intend to be loaded into an tool via the + -load option. See the + WritingAnLLVMPass.html document + for an example of why you might want to do this. -
+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 - types of libraries by defining the MODULE_NAME +
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:
LIBRARYNAME = mylib
@@ -254,13 +273,47 @@
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 @@ -299,36 +352,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 target can be invoked from anywhere within a project's directories - but always invokes the check-local target + but always invokes the check-local target in the project's test directory, if it exists and has a Makefile. A warning is produced otherwise. If - TESTSUITE is defined on the make + TESTSUITE is defined on the make command line, it will be passed down to the invocation of make check-local in the test directory. The intended usage for this is to assist in running specific suites of tests. If @@ -519,6 +558,28 @@ the makefile variables so that you can double check how things are set.
This utility target will force a reconfigure of LLVM or your project. It + 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. +
+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.