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