X-Git-Url: http://plrg.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FMakefileGuide.html;h=f996144e145372156f5e0d5b7acef8bfecc98864;hb=ab7c09b6b6f4516a631fd6788918c237c83939af;hp=067d276a5514dfc77cf97303707bbc38eb7a9da6;hpb=5d12bf8684ae508d776b0e0c888378e79782cc86;p=oota-llvm.git diff --git a/docs/MakefileGuide.html b/docs/MakefileGuide.html index 067d276a551..f996144e145 100644 --- a/docs/MakefileGuide.html +++ b/docs/MakefileGuide.html @@ -30,7 +30,8 @@
  1. Libraries
      -
    1. Bytecode Modules
      2. +
    2. Bitcode Modules
      3. +
    3. Loadable Modules
  2. Tools @@ -231,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 @@ -259,11 +259,11 @@ -

    Bytecode Modules
    +
    Bitcode Modules
    -

    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:

    
@@ -272,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.

    + +
    + Loadable Modules +
    +
    +

    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:

    +
      +
    1. There will be no "lib" prefix on the module. This differentiates it from + a standard shared library of the same name.
      2. +
    2. The SHARED_LIBRARY variable is turned + on.
      3. +
    3. The LINK_LIBS_IN_SHARED variable + is turned on.
      4. +
    +

    A loadable module is loaded by LLVM via the facilities of libtool's libltdl + library which is part of lib/System implementation.

    +
    +
    Tools
    @@ -288,7 +320,7 @@ 
    
       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 @@ -317,36 +349,22 @@

    JIT Tools
    -

    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. -

    @@ -605,7 +623,7 @@ files. These sources will be built before any other target processing to ensure they are present.
    BYTECODE_LIBRARY
    -
    If set to any value, causes a bytecode library (.bc) to be built.
    +
    If set to any value, causes a bitcode library (.bc) to be built.
    CONFIG_FILES
    Specifies a set of configuration files to be installed.
    DIRS
    @@ -616,11 +634,6 @@
    If set to any value, causes the makefiles to not automatically generate dependencies when running the compiler. Use of this feature is discouraged and it may be removed at a later date.
    -
    DONT_BUILD_RELINKED
    -
    If set to any value, causes a relinked library (.o) not to be built. By - default, libraries are built as re-linked since most LLVM libraries are - needed in their entirety and re-linked libraries will be linked more quickly - than equivalent archive libraries.
    ENABLE_OPTIMIZED
    If set to any value, causes the build to generate optimized objects, libraries and executables. This alters the flags specified to the compilers @@ -662,6 +675,22 @@
    LIBRARYNAME
    Specify the name of the library to be built. (Required For Libraries)
    +
    LINK_COMPONENTS
    +
    When specified for building a tool, the value of this variable will be + passed to the llvm-config tool to generate a link line for the + tool. Unlike USEDLIBS and LLVMLIBS, not all libraries need + to be specified. The llvm-config tool will figure out the library + dependencies and add any libraries that are needed. The USEDLIBS + variable can still be used in conjunction with LINK_COMPONENTS so + that additional project-specific libraries can be linked with the LLVM + libraries specified by LINK_COMPONENTS
    +
    LINK_LIBS_IN_SHARED
    +
    By default, shared library linking will ignore any libraries specified + with the LLVMLIBS or USEDLIBS. + 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.
    LLVMLIBS
    Specifies the set of libraries from the LLVM $(ObjDir) that will be linked into the tool or library.
    @@ -672,10 +701,16 @@ setting this variable without also setting SHARED_LIBRARY will have no effect.
    MODULE_NAME
    -
    Specifies the name of a bytecode module to be created. A bytecode +
    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.
    +
    NO_INSTALL
    +
    Specifies that the build products of the directory should not be + installed but should be built even if the install 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. + tblgen).
    OPTIONAL_DIRS
    Specify a set of directories that may be built, if they exist, but its not an error for them not to exist.
    @@ -738,8 +773,6 @@
    AR (defaulted)
    Specifies the path to the ar tool.
    -
    BISON(configured)
    -
    Specifies the path to the bison tool.
    PROJ_OBJ_DIR
    The directory into which the products of build rules will be placed. This might be the same as @@ -765,19 +798,10 @@ isn't one.
    ECHO(configured)
    Specifies the path to the echo tool for printing output.
    -
    ETAGS(configured)
    -
    Specifies the path to the etags tool.
    -
    ETAGSFLAGS(configured) -
    -
    Provides flags to be passed to the etags tool.
    EXEEXT(configured)
    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).
    -
    FLEX(configured)
    -
    Specifies the path to the flex tool.
    -
    GCCLD(defaulted)
    -
    Specifies the path to the gccld tool.
    INSTALL(configured)
    Specifies the path to the install tool.
    LDFLAGS(configured)
    @@ -793,6 +817,8 @@
    Specifies the path to the LLVM version of the GCC 'C' Compiler
    LLVMGXX(defaulted)
    Specifies the path to the LLVM version of the GCC C++ Compiler
    +
    LLVMLD(defaulted)
    +
    Specifies the path to the LLVM bitcode linker tool
    LLVM_OBJ_ROOT(configured)
    Specifies the top directory into which the output of the build is @@ -807,6 +833,8 @@
    MKDIR(defaulted)
    Specifies the path to the mkdir tool that creates directories.
    +
    ONLY_TOOLS
    +
    If set, specifies the list of tools to build.
    PLATFORMSTRIPOPTS
    The options to provide to the linker to specify that a stripped (no symbols) executable should be built.
    @@ -841,8 +869,8 @@
    BuildMode
    The name of the type of build being performed: Debug, Release, or Profile
    -
    bytecode_libdir
    -
    The directory into which bytecode libraries will ultimately be +
    bytecode_libdir
    +
    The directory into which bitcode libraries will ultimately be installed. This value is derived from the --prefix option given to configure.
    ConfigureScriptFLAGS
    @@ -911,7 +939,6 @@ BCCompile.C BCCompile.CXX BCLinkLib - Burg C.Flags Compile.C CompileCommonOpts @@ -923,9 +950,8 @@ CXX.Flags DependFiles DestArchiveLib - DestBytecodeLib + DestBitcodeLib DestModule - DestRelinkedLib DestSharedLib DestTool DistAlways @@ -944,8 +970,6 @@ INCFiles InternalTargets LD.Flags - LexFiles - LexOutput LibName.A LibName.BC LibName.LA @@ -959,9 +983,6 @@ LLVMToolDir LLVMUsedLibs LocalTargets - LTCompile.C - LTCompile.CXX - LTInstall Module ObjectsBC ObjectsLO @@ -974,7 +995,6 @@ ProjUsedLibs Ranlib RecursiveTargets - Relink SrcMakefiles Strip StripWarnMsg @@ -983,8 +1003,6 @@ ToolBuildPath TopLevelTargets UserTargets - YaccFiles - YaccOutput

    @@ -992,9 +1010,9 @@
    Valid CSS! + src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"> Valid HTML 4.01! + src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"> Reid Spencer
    The LLVM Compiler Infrastructure