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 a) Build framework makefiles
  15 ----------------------------
  16
  17 The build framework consists of 2 Makefiles:
  18
  19   Build.include
  20   Makefile.build
  21
  22 While the 'Build.include' file contains just some generic definitions, the
  23 'Makefile.build' file is the makefile used from the outside. It's
  24 interface/usage is following:
  25
  26   $ make -f tools/build/Makefile srctree=$(KSRC) dir=$(DIR) obj=$(OBJECT)
  27
  28 where:
  29
  30   KSRC   - is the path to kernel sources
  31   DIR    - is the path to the project to be built
  32   OBJECT - is the name of the build object
  33
  34 When succefully finished the $(DIR) directory contains the final object file
  35 called $(OBJECT)-in.o:
  36
  37   $ ls $(DIR)/$(OBJECT)-in.o
  38
  39 which includes all compiled sources described in 'Build' makefiles.
  40
  41 a) Build makefiles
  42 ------------------
  43
  44 The user supplies 'Build' makefiles that contains a objects list, and connects
  45 the build to nested directories.
  46
  47 Assume we have the following project structure:
  48
  49   ex/a.c
  50     /b.c
  51     /c.c
  52     /d.c
  53     /arch/e.c
  54     /arch/f.c
  55
  56 Out of which you build the 'ex' binary ' and the 'libex.a' library:
  57
  58   'ex'      - consists of 'a.o', 'b.o' and libex.a
  59   'libex.a' - consists of 'c.o', 'd.o', 'e.o' and 'f.o'
  60
  61 The build framework does not create the 'ex' and 'libex.a' binaries for you, it
  62 only prepares proper objects to be compiled and grouped together.
  63
  64 To follow the above example, the user provides following 'Build' files:
  65
  66   ex/Build:
  67     ex-y += a.o
  68     ex-y += b.o
  69
  70     libex-y += c.o
  71     libex-y += d.o
  72     libex-y += arch/
  73
  74   ex/arch/Build:
  75     libex-y += e.o
  76     libex-y += f.o
  77
  78 and runs:
  79
  80   $ make -f tools/build/Makefile.build dir=. obj=ex
  81   $ make -f tools/build/Makefile.build dir=. obj=libex
  82
  83 which creates the following objects:
  84
  85   ex/ex-in.o
  86   ex/libex-in.o
  87
  88 that contain request objects names in Build files.
  89
  90 It's only a matter of 2 single commands to create the final binaries:
  91
  92   $ ar  rcs libex.a libex-in.o
  93   $ gcc -o ex ex-in.o libex.a
  94
  95 You can check the 'ex' example in 'tools/build/tests/ex' for more details.
  96
  97 b) Rules
  98 --------
  99
 100 The build framework provides standard compilation rules to handle .S and .c
 101 compilation.
 102
 103 It's possible to include special rule if needed (like we do for flex or bison
 104 code generation).
 105
 106 c) CFLAGS
 107 ---------
 108
 109 It's possible to alter the standard object C flags in the following way:
 110
 111   CFLAGS_perf.o += '...' - alters CFLAGS for perf.o object
 112   CFLAGS_gtk += '...'    - alters CFLAGS for gtk build object
 113
 114 This C flags changes has the scope of the Build makefile they are defined in.
 115
 116
 117 d) Dependencies
 118 ---------------
 119
 120 For each built object file 'a.o' the '.a.cmd' is created and holds:
 121
 122   - Command line used to built that object
 123     (for each object)
 124
 125   - Dependency rules generated by 'gcc -Wp,-MD,...'
 126     (for compiled object)
 127
 128 All existing '.cmd' files are included in the Build process to follow properly
 129 the dependencies and trigger a rebuild when necessary.
 130
 131
 132 e) Single rules
 133 ---------------
 134
 135 It's possible to build single object file by choice, like:
 136
 137   $ make util/map.o    # objects
 138   $ make util/map.i    # preprocessor
 139   $ make util/map.s    # assembly