tools/build/Documentation/Build.txt

   1 Build Framework
   2 ===============
   3
   4 The perf build framework was adopted from the kernel build system, hence the
   5 idea and the way how objects are built is the same.
   6
   7 Basically the user provides set of 'Build' files that list objects and
   8 directories to nest for specific target to be build.
   9
  10 Unlike the kernel we don't have a single build object 'obj-y' list that where
  11 we setup source objects, but we support more. This allows one 'Build' file to
  12 carry a sources list for multiple build objects.
  13
  14
  15 Build framework makefiles
  16 -------------------------
  17
  18 The build framework consists of 2 Makefiles:
  19
  20   Build.include
  21   Makefile.build
  22
  23 While the 'Build.include' file contains just some generic definitions, the
  24 'Makefile.build' file is the makefile used from the outside. It's
  25 interface/usage is following:
  26
  27   $ make -f tools/build/Makefile.build srctree=$(KSRC) dir=$(DIR) obj=$(OBJECT)
  28
  29 where:
  30
  31   KSRC   - is the path to kernel sources
  32   DIR    - is the path to the project to be built
  33   OBJECT - is the name of the build object
  34
  35 When succefully finished the $(DIR) directory contains the final object file
  36 called $(OBJECT)-in.o:
  37
  38   $ ls $(DIR)/$(OBJECT)-in.o
  39
  40 which includes all compiled sources described in 'Build' makefiles.
  41
  42
  43 Build makefiles
  44 ---------------
  45
  46 The user supplies 'Build' makefiles that contains a objects list, and connects
  47 the build to nested directories.
  48
  49 Assume we have the following project structure:
  50
  51   ex/a.c
  52     /b.c
  53     /c.c
  54     /d.c
  55     /arch/e.c
  56     /arch/f.c
  57
  58 Out of which you build the 'ex' binary ' and the 'libex.a' library:
  59
  60   'ex'      - consists of 'a.o', 'b.o' and libex.a
  61   'libex.a' - consists of 'c.o', 'd.o', 'e.o' and 'f.o'
  62
  63 The build framework does not create the 'ex' and 'libex.a' binaries for you, it
  64 only prepares proper objects to be compiled and grouped together.
  65
  66 To follow the above example, the user provides following 'Build' files:
  67
  68   ex/Build:
  69     ex-y += a.o
  70     ex-y += b.o
  71     ex-y += b.o # duplicates in the lists are allowed
  72
  73     libex-y += c.o
  74     libex-y += d.o
  75     libex-y += arch/
  76
  77   ex/arch/Build:
  78     libex-y += e.o
  79     libex-y += f.o
  80
  81 and runs:
  82
  83   $ make -f tools/build/Makefile.build dir=. obj=ex
  84   $ make -f tools/build/Makefile.build dir=. obj=libex
  85
  86 which creates the following objects:
  87
  88   ex/ex-in.o
  89   ex/libex-in.o
  90
  91 that contain request objects names in Build files.
  92
  93 It's only a matter of 2 single commands to create the final binaries:
  94
  95   $ ar  rcs libex.a libex-in.o
  96   $ gcc -o ex ex-in.o libex.a
  97
  98 You can check the 'ex' example in 'tools/build/tests/ex' for more details.
  99
 100
 101 Makefile.include
 102 ----------------
 103
 104 The tools/build/Makefile.include makefile could be included
 105 via user makefiles to get usefull definitions.
 106
 107 It defines following interface:
 108
 109   - build macro definition:
 110       build := -f $(srctree)/tools/build/Makefile.build dir=. obj
 111
 112     to make it easier to invoke build like:
 113       make $(build)=ex
 114
 115
 116 Fixdep
 117 ------
 118 It is necessary to build the fixdep helper before invoking the build.
 119 The Makefile.include file adds the fixdep target, that could be
 120 invoked by the user.
 121
 122
 123 Rules
 124 -----
 125
 126 The build framework provides standard compilation rules to handle .S and .c
 127 compilation.
 128
 129 It's possible to include special rule if needed (like we do for flex or bison
 130 code generation).
 131
 132
 133 CFLAGS
 134 ------
 135
 136 It's possible to alter the standard object C flags in the following way:
 137
 138   CFLAGS_perf.o += '...' - alters CFLAGS for perf.o object
 139   CFLAGS_gtk += '...'    - alters CFLAGS for gtk build object
 140
 141 This C flags changes has the scope of the Build makefile they are defined in.
 142
 143
 144 Dependencies
 145 ------------
 146
 147 For each built object file 'a.o' the '.a.cmd' is created and holds:
 148
 149   - Command line used to built that object
 150     (for each object)
 151
 152   - Dependency rules generated by 'gcc -Wp,-MD,...'
 153     (for compiled object)
 154
 155 All existing '.cmd' files are included in the Build process to follow properly
 156 the dependencies and trigger a rebuild when necessary.
 157
 158
 159 Single rules
 160 ------------
 161
 162 It's possible to build single object file by choice, like:
 163
 164   $ make util/map.o    # objects
 165   $ make util/map.i    # preprocessor
 166   $ make util/map.s    # assembly