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 14 15Build framework makefiles 16------------------------- 17 18The build framework consists of 2 Makefiles: 19 20 Build.include 21 Makefile.build 22 23While the 'Build.include' file contains just some generic definitions, the 24'Makefile.build' file is the makefile used from the outside. It's 25interface/usage is following: 26 27 $ make -f tools/build/Makefile.build srctree=$(KSRC) dir=$(DIR) obj=$(OBJECT) 28 29where: 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 35When succefully finished the $(DIR) directory contains the final object file 36called $(OBJECT)-in.o: 37 38 $ ls $(DIR)/$(OBJECT)-in.o 39 40which includes all compiled sources described in 'Build' makefiles. 41 42 43Build makefiles 44--------------- 45 46The user supplies 'Build' makefiles that contains a objects list, and connects 47the build to nested directories. 48 49Assume 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 58Out 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 63The build framework does not create the 'ex' and 'libex.a' binaries for you, it 64only prepares proper objects to be compiled and grouped together. 65 66To 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 81and runs: 82 83 $ make -f tools/build/Makefile.build dir=. obj=ex 84 $ make -f tools/build/Makefile.build dir=. obj=libex 85 86which creates the following objects: 87 88 ex/ex-in.o 89 ex/libex-in.o 90 91that contain request objects names in Build files. 92 93It'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 98You can check the 'ex' example in 'tools/build/tests/ex' for more details. 99 100 101Makefile.include 102---------------- 103 104The tools/build/Makefile.include makefile could be included 105via user makefiles to get usefull definitions. 106 107It 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 116Rules 117----- 118 119The build framework provides standard compilation rules to handle .S and .c 120compilation. 121 122It's possible to include special rule if needed (like we do for flex or bison 123code generation). 124 125 126CFLAGS 127------ 128 129It's possible to alter the standard object C flags in the following way: 130 131 CFLAGS_perf.o += '...' - alters CFLAGS for perf.o object 132 CFLAGS_gtk += '...' - alters CFLAGS for gtk build object 133 134This C flags changes has the scope of the Build makefile they are defined in. 135 136 137Dependencies 138------------ 139 140For each built object file 'a.o' the '.a.cmd' is created and holds: 141 142 - Command line used to built that object 143 (for each object) 144 145 - Dependency rules generated by 'gcc -Wp,-MD,...' 146 (for compiled object) 147 148All existing '.cmd' files are included in the Build process to follow properly 149the dependencies and trigger a rebuild when necessary. 150 151 152Single rules 153------------ 154 155It's possible to build single object file by choice, like: 156 157 $ make util/map.o # objects 158 $ make util/map.i # preprocessor 159 $ make util/map.s # assembly 160