From 2734bf754ac62150a8385f9a9a74860a09bd18ba Mon Sep 17 00:00:00 2001 From: Reid Spencer Date: Sun, 31 Oct 2004 17:51:38 +0000 Subject: [PATCH] Add a tutorial and some more general concepts. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@17369 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/MakefileGuide.html | 153 +++++++++++++++++++++++++++++++++------- 1 file changed, 127 insertions(+), 26 deletions(-) diff --git a/docs/MakefileGuide.html b/docs/MakefileGuide.html index 4d7e1c4a2cd..af06d757120 100644 --- a/docs/MakefileGuide.html +++ b/docs/MakefileGuide.html @@ -14,13 +14,23 @@
  • General Concepts
    1. Projects
      2. -
    2. Makefile
      3. -
    3. Makefile.common
      4. -
    4. Makefile.config
      5. -
    5. Makefile.rules
      6. +
    6. Variable Values
      7. +
    7. Including Makefiles
      8. +
        +
      1. Makefile
        2. +
      2. Makefile.common
        3. +
      3. Makefile.config
        4. +
      4. Makefile.rules
        5. +
    8. Comments
    • +
  • Tutorial +
      +
    1. Libraries
      2. +
    2. Tools
      3. +
    +
  • Targets Supported
    1. all
      2. @@ -60,15 +70,14 @@

      This document provides usage information about the LLVM makefile system. While loosely patterned after the BSD makefile system, LLVM has taken a departure from BSD in order to implement additional features needed by LLVM. -

      -

      Although makefile systems such as automake were attempted at one point, it - has become clear that the differences between the LLVM way of doing things and - the Makefile norm are too great to use a more limited tool. Consequently, LLVM requires - simply GNU Make 3.79, a widely portably makefile processor. LLVM unabashedly - makes heavy use of the features of GNU Make so the dependency on GNU Make is - firm. If you're not familiar with make, it is recommended that you - read the - GNU Makefile Manual.

      + Although makefile systems such as automake were attempted at one point, it + has become clear that the features needed by LLVM and the Makefile norm are + too great to use a more limited tool. Consequently, LLVM requires simply GNU + Make 3.79, a widely portable makefile processor. LLVM unabashedly makes heavy + use of the features of GNU Make so the dependency on GNU Make is firm. If + you're not familiar with make, it is recommended that you read the + GNU Makefile Manual + .

      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 @@ -80,9 +89,11 @@

      -

      The LLVM makefile system is the component of LLVM that is responsible for - building the software, testing it, generating distributions, rpms and other - packages, installing and uninstalling, etc.

      +

      The LLVM Makefile System is the component of LLVM that is responsible for + building the software, testing it, generating distributions, checking those + distributions, installing and uninstalling, etc. It consists of a several + files throughout the source tree. These files and other general concepts are + described in this section.

      @@ -94,11 +105,30 @@ 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 get up and running quickly by utilizing the built-in features that are used - to compile LLVM.

      + to compile LLVM. LLVM compiles itself using the same features of the makefile + system as used for projects.

      + + + +
      Variable Values
      +
      +

      To use the makefile system, you simply create a file named + Makefile in your directory and declare values for certain variables. + The variables and values that you select determine what the makefile system + will do. These variables enable rules and processing in the makefile system + that automatically Do The Right Thing™.

      -
      Makefile
      +
      Including Makefiles
      +
      +

      Setting variables alone is not enough. You must include into your Makefile + additional files that provide the rules of the LLVM Makefile system. The + various files involved are described in the sections that follow.

      +
      + + +
      Makefile

      Each directory to participate in the build needs to have a file named Makefile. This is the file first read by make. It has three @@ -108,13 +138,14 @@ first.

    2. include $(LEVEL)/Makefile.common - include the LLVM Makefile system. -
    3. Overridable Variables - Override variables set by +
    4. Override Variables - Override variables set by the LLVM Makefile system.
    -
    Makefile.common
    +
    Makefile.common +

    Every project must have a Makefile.common file at its top source directory. This file serves three purposes:

    @@ -125,14 +156,15 @@
  • It specifies any other (static) values that are needed throughout the project. Only values that are used in all or a large proportion of the project's directories should be placed here.
    • -
  • It include's the standard rules for the LLVM Makefile system, +
  • It includes the standard rules for the LLVM Makefile system, $(LLVM_SRC_ROOT)/Makefile.rules. This file is the "guts" of the LLVM Makefile system.
    • -
    Makefile.config
    +
    Makefile.config +

    Every project must have a Makefile.config at the top of its build directory. This file is generated by the @@ -145,7 +177,7 @@

    -
    Makefile.rules
    +
    Makefile.rules

    This file, located at $(LLVM_SRC_ROOT)/Makefile.rules is the heart of the LLVM Makefile System. It provides all the logic, dependencies, and @@ -164,6 +196,75 @@ by make.

    + +
    Tutorial
    + +
    +

    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.

    +
    + + +
    Libraries
    +
    +

    Only a few variable definitions are needed to build a regular library. + 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:

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

    +
    + + +
    Tools
    +
    +

    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:

    + 
    
+      TOOLNAME = mytool
+      USEDLIBS = mylib
+      LLVMLIBS = LLVMSupport.a LLVMSystem.a
+
    +

    says that we are to build a tool name mytool and that it requires + three libraries: mylib, LLVMSupport.a and + LLVMSystem.a.

    +

    Note that two different variables are use to indicate which libraries are + linked: USEDLIBS and LLVMLIBS. This distinction is necessary + to support projects. LLVMLIBS refers to the LLVM libraries found in + the LLVM object directory. USEDLIBS refers to the libraries built by + your project. In the case of building LLVM tools, USEDLIBS and + LLVMLIBS can be used interchangeably since the "project" is LLVM + itself and USEDLIBS refers to the same place as LLVMLIBS. +

    +

    Also note that there are two different ways of specifying a library: with a + .a suffix and without. Without the suffix, the entry refers to the + re-linked (.o) file which will include all symbols of the library. + This is useful, for example, to include all passes from a library of passes. + If the .a suffix is used then the library is linked as a searchable + library (with the -l option). In this case, only the symbols that are + unresolved at that point will be resolved from the library, if they + exist. Other (unreferenced) symbols will not be included when the .a + syntax is used. Note that in order to use the .a suffix, the library + in question must have been built with the ARCHIVE_LIBRARY option set. +

    +
    +
    Targets Supported
    @@ -378,7 +479,7 @@
    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 equival archive libraries.
    + 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 @@ -456,9 +557,9 @@ -
    Overridable Variables
    +
    Override Variables
    -

    Overridable variables can be used to override the default +

    Override variables can be used to override the default values provided by the LLVM makefile system. These variables can be set in several ways:

      -- 2.34.1