1Build Framework
2===============
3
4The perf build framework was adopted from the kernel build system, hence the
5idea and the way how objects are built is the same.
6
7Basically the user provides set of 'Build' files that list objects and
8directories to nest for specific target to be build.
9
10Unlike the kernel we don't have a single build object 'obj-y' list that where
11we setup source objects, but we support more. This allows one 'Build' file to
12carry a sources list for multiple build objects.
13
14a) Build framework makefiles
15----------------------------
16
17The build framework consists of 2 Makefiles:
18
19  Build.include
20  Makefile.build
21
22While the 'Build.include' file contains just some generic definitions, the
23'Makefile.build' file is the makefile used from the outside. It's
24interface/usage is following:
25
26  $ make -f tools/build/Makefile srctree=$(KSRC) dir=$(DIR) obj=$(OBJECT)
27
28where:
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
34When succefully finished the $(DIR) directory contains the final object file
35called $(OBJECT)-in.o:
36
37  $ ls $(DIR)/$(OBJECT)-in.o
38
39which includes all compiled sources described in 'Build' makefiles.
40
41a) Build makefiles
42------------------
43
44The user supplies 'Build' makefiles that contains a objects list, and connects
45the build to nested directories.
46
47Assume 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
56Out 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
61The build framework does not create the 'ex' and 'libex.a' binaries for you, it
62only prepares proper objects to be compiled and grouped together.
63
64To 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
78and runs:
79
80  $ make -f tools/build/Makefile.build dir=. obj=ex
81  $ make -f tools/build/Makefile.build dir=. obj=libex
82
83which creates the following objects:
84
85  ex/ex-in.o
86  ex/libex-in.o
87
88that contain request objects names in Build files.
89
90It'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
95You can check the 'ex' example in 'tools/build/tests/ex' for more details.
96
97b) Rules
98--------
99
100The build framework provides standard compilation rules to handle .S and .c
101compilation.
102
103It's possible to include special rule if needed (like we do for flex or bison
104code generation).
105
106c) CFLAGS
107---------
108
109It'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
114This C flags changes has the scope of the Build makefile they are defined in.
115
116
117d) Dependencies
118---------------
119
120For 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
128All existing '.cmd' files are included in the Build process to follow properly
129the dependencies and trigger a rebuild when necessary.
130
131
132e) Single rules
133---------------
134
135It'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
140