1c819e2cfSJiri OlsaBuild Framework 2c819e2cfSJiri Olsa=============== 3c819e2cfSJiri Olsa 4c819e2cfSJiri OlsaThe perf build framework was adopted from the kernel build system, hence the 5c819e2cfSJiri Olsaidea and the way how objects are built is the same. 6c819e2cfSJiri Olsa 7c819e2cfSJiri OlsaBasically the user provides set of 'Build' files that list objects and 8c819e2cfSJiri Olsadirectories to nest for specific target to be build. 9c819e2cfSJiri Olsa 10c819e2cfSJiri OlsaUnlike the kernel we don't have a single build object 'obj-y' list that where 11c819e2cfSJiri Olsawe setup source objects, but we support more. This allows one 'Build' file to 12c819e2cfSJiri Olsacarry a sources list for multiple build objects. 13c819e2cfSJiri Olsa 14c819e2cfSJiri Olsaa) Build framework makefiles 15c819e2cfSJiri Olsa---------------------------- 16c819e2cfSJiri Olsa 17c819e2cfSJiri OlsaThe build framework consists of 2 Makefiles: 18c819e2cfSJiri Olsa 19c819e2cfSJiri Olsa Build.include 20c819e2cfSJiri Olsa Makefile.build 21c819e2cfSJiri Olsa 22c819e2cfSJiri OlsaWhile the 'Build.include' file contains just some generic definitions, the 23c819e2cfSJiri Olsa'Makefile.build' file is the makefile used from the outside. It's 24c819e2cfSJiri Olsainterface/usage is following: 25c819e2cfSJiri Olsa 26c819e2cfSJiri Olsa $ make -f tools/build/Makefile srctree=$(KSRC) dir=$(DIR) obj=$(OBJECT) 27c819e2cfSJiri Olsa 28c819e2cfSJiri Olsawhere: 29c819e2cfSJiri Olsa 30c819e2cfSJiri Olsa KSRC - is the path to kernel sources 31c819e2cfSJiri Olsa DIR - is the path to the project to be built 32c819e2cfSJiri Olsa OBJECT - is the name of the build object 33c819e2cfSJiri Olsa 34c819e2cfSJiri OlsaWhen succefully finished the $(DIR) directory contains the final object file 35c819e2cfSJiri Olsacalled $(OBJECT)-in.o: 36c819e2cfSJiri Olsa 37c819e2cfSJiri Olsa $ ls $(DIR)/$(OBJECT)-in.o 38c819e2cfSJiri Olsa 39c819e2cfSJiri Olsawhich includes all compiled sources described in 'Build' makefiles. 40c819e2cfSJiri Olsa 41c819e2cfSJiri Olsaa) Build makefiles 42c819e2cfSJiri Olsa------------------ 43c819e2cfSJiri Olsa 44c819e2cfSJiri OlsaThe user supplies 'Build' makefiles that contains a objects list, and connects 45c819e2cfSJiri Olsathe build to nested directories. 46c819e2cfSJiri Olsa 47c819e2cfSJiri OlsaAssume we have the following project structure: 48c819e2cfSJiri Olsa 49c819e2cfSJiri Olsa ex/a.c 50c819e2cfSJiri Olsa /b.c 51c819e2cfSJiri Olsa /c.c 52c819e2cfSJiri Olsa /d.c 53c819e2cfSJiri Olsa /arch/e.c 54c819e2cfSJiri Olsa /arch/f.c 55c819e2cfSJiri Olsa 56c819e2cfSJiri OlsaOut of which you build the 'ex' binary ' and the 'libex.a' library: 57c819e2cfSJiri Olsa 58c819e2cfSJiri Olsa 'ex' - consists of 'a.o', 'b.o' and libex.a 59c819e2cfSJiri Olsa 'libex.a' - consists of 'c.o', 'd.o', 'e.o' and 'f.o' 60c819e2cfSJiri Olsa 61c819e2cfSJiri OlsaThe build framework does not create the 'ex' and 'libex.a' binaries for you, it 62c819e2cfSJiri Olsaonly prepares proper objects to be compiled and grouped together. 63c819e2cfSJiri Olsa 64c819e2cfSJiri OlsaTo follow the above example, the user provides following 'Build' files: 65c819e2cfSJiri Olsa 66c819e2cfSJiri Olsa ex/Build: 67c819e2cfSJiri Olsa ex-y += a.o 68c819e2cfSJiri Olsa ex-y += b.o 69c819e2cfSJiri Olsa 70c819e2cfSJiri Olsa libex-y += c.o 71c819e2cfSJiri Olsa libex-y += d.o 72c819e2cfSJiri Olsa libex-y += arch/ 73c819e2cfSJiri Olsa 74c819e2cfSJiri Olsa ex/arch/Build: 75c819e2cfSJiri Olsa libex-y += e.o 76c819e2cfSJiri Olsa libex-y += f.o 77c819e2cfSJiri Olsa 78c819e2cfSJiri Olsaand runs: 79c819e2cfSJiri Olsa 80c819e2cfSJiri Olsa $ make -f tools/build/Makefile.build dir=. obj=ex 81c819e2cfSJiri Olsa $ make -f tools/build/Makefile.build dir=. obj=libex 82c819e2cfSJiri Olsa 83c819e2cfSJiri Olsawhich creates the following objects: 84c819e2cfSJiri Olsa 85c819e2cfSJiri Olsa ex/ex-in.o 86c819e2cfSJiri Olsa ex/libex-in.o 87c819e2cfSJiri Olsa 88c819e2cfSJiri Olsathat contain request objects names in Build files. 89c819e2cfSJiri Olsa 90c819e2cfSJiri OlsaIt's only a matter of 2 single commands to create the final binaries: 91c819e2cfSJiri Olsa 92c819e2cfSJiri Olsa $ ar rcs libex.a libex-in.o 93c819e2cfSJiri Olsa $ gcc -o ex ex-in.o libex.a 94c819e2cfSJiri Olsa 95c819e2cfSJiri OlsaYou can check the 'ex' example in 'tools/build/tests/ex' for more details. 96c819e2cfSJiri Olsa 97c819e2cfSJiri Olsab) Rules 98c819e2cfSJiri Olsa-------- 99c819e2cfSJiri Olsa 100c819e2cfSJiri OlsaThe build framework provides standard compilation rules to handle .S and .c 101c819e2cfSJiri Olsacompilation. 102c819e2cfSJiri Olsa 103c819e2cfSJiri OlsaIt's possible to include special rule if needed (like we do for flex or bison 104c819e2cfSJiri Olsacode generation). 105c819e2cfSJiri Olsa 106c819e2cfSJiri Olsac) CFLAGS 107c819e2cfSJiri Olsa--------- 108c819e2cfSJiri Olsa 109c819e2cfSJiri OlsaIt's possible to alter the standard object C flags in the following way: 110c819e2cfSJiri Olsa 111c819e2cfSJiri Olsa CFLAGS_perf.o += '...' - alters CFLAGS for perf.o object 112c819e2cfSJiri Olsa CFLAGS_gtk += '...' - alters CFLAGS for gtk build object 113c819e2cfSJiri Olsa 114c819e2cfSJiri OlsaThis C flags changes has the scope of the Build makefile they are defined in. 115c819e2cfSJiri Olsa 116c819e2cfSJiri Olsa 117c819e2cfSJiri Olsad) Dependencies 118c819e2cfSJiri Olsa--------------- 119c819e2cfSJiri Olsa 120c819e2cfSJiri OlsaFor each built object file 'a.o' the '.a.cmd' is created and holds: 121c819e2cfSJiri Olsa 122c819e2cfSJiri Olsa - Command line used to built that object 123c819e2cfSJiri Olsa (for each object) 124c819e2cfSJiri Olsa 125c819e2cfSJiri Olsa - Dependency rules generated by 'gcc -Wp,-MD,...' 126c819e2cfSJiri Olsa (for compiled object) 127c819e2cfSJiri Olsa 128c819e2cfSJiri OlsaAll existing '.cmd' files are included in the Build process to follow properly 129c819e2cfSJiri Olsathe dependencies and trigger a rebuild when necessary. 130c819e2cfSJiri Olsa 131c819e2cfSJiri Olsa 132c819e2cfSJiri Olsae) Single rules 133c819e2cfSJiri Olsa--------------- 134c819e2cfSJiri Olsa 135c819e2cfSJiri OlsaIt's possible to build single object file by choice, like: 136c819e2cfSJiri Olsa 137c819e2cfSJiri Olsa $ make util/map.o # objects 138c819e2cfSJiri Olsa $ make util/map.i # preprocessor 139c819e2cfSJiri Olsa $ make util/map.s # assembly 140