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 690bdede8aSJiri Olsa ex-y += b.o # duplicates in the lists are allowed 70c819e2cfSJiri Olsa 71c819e2cfSJiri Olsa libex-y += c.o 72c819e2cfSJiri Olsa libex-y += d.o 73c819e2cfSJiri Olsa libex-y += arch/ 74c819e2cfSJiri Olsa 75c819e2cfSJiri Olsa ex/arch/Build: 76c819e2cfSJiri Olsa libex-y += e.o 77c819e2cfSJiri Olsa libex-y += f.o 78c819e2cfSJiri Olsa 79c819e2cfSJiri Olsaand runs: 80c819e2cfSJiri Olsa 81c819e2cfSJiri Olsa $ make -f tools/build/Makefile.build dir=. obj=ex 82c819e2cfSJiri Olsa $ make -f tools/build/Makefile.build dir=. obj=libex 83c819e2cfSJiri Olsa 84c819e2cfSJiri Olsawhich creates the following objects: 85c819e2cfSJiri Olsa 86c819e2cfSJiri Olsa ex/ex-in.o 87c819e2cfSJiri Olsa ex/libex-in.o 88c819e2cfSJiri Olsa 89c819e2cfSJiri Olsathat contain request objects names in Build files. 90c819e2cfSJiri Olsa 91c819e2cfSJiri OlsaIt's only a matter of 2 single commands to create the final binaries: 92c819e2cfSJiri Olsa 93c819e2cfSJiri Olsa $ ar rcs libex.a libex-in.o 94c819e2cfSJiri Olsa $ gcc -o ex ex-in.o libex.a 95c819e2cfSJiri Olsa 96c819e2cfSJiri OlsaYou can check the 'ex' example in 'tools/build/tests/ex' for more details. 97c819e2cfSJiri Olsa 98c819e2cfSJiri Olsab) Rules 99c819e2cfSJiri Olsa-------- 100c819e2cfSJiri Olsa 101c819e2cfSJiri OlsaThe build framework provides standard compilation rules to handle .S and .c 102c819e2cfSJiri Olsacompilation. 103c819e2cfSJiri Olsa 104c819e2cfSJiri OlsaIt's possible to include special rule if needed (like we do for flex or bison 105c819e2cfSJiri Olsacode generation). 106c819e2cfSJiri Olsa 107c819e2cfSJiri Olsac) CFLAGS 108c819e2cfSJiri Olsa--------- 109c819e2cfSJiri Olsa 110c819e2cfSJiri OlsaIt's possible to alter the standard object C flags in the following way: 111c819e2cfSJiri Olsa 112c819e2cfSJiri Olsa CFLAGS_perf.o += '...' - alters CFLAGS for perf.o object 113c819e2cfSJiri Olsa CFLAGS_gtk += '...' - alters CFLAGS for gtk build object 114c819e2cfSJiri Olsa 115c819e2cfSJiri OlsaThis C flags changes has the scope of the Build makefile they are defined in. 116c819e2cfSJiri Olsa 117c819e2cfSJiri Olsa 118c819e2cfSJiri Olsad) Dependencies 119c819e2cfSJiri Olsa--------------- 120c819e2cfSJiri Olsa 121c819e2cfSJiri OlsaFor each built object file 'a.o' the '.a.cmd' is created and holds: 122c819e2cfSJiri Olsa 123c819e2cfSJiri Olsa - Command line used to built that object 124c819e2cfSJiri Olsa (for each object) 125c819e2cfSJiri Olsa 126c819e2cfSJiri Olsa - Dependency rules generated by 'gcc -Wp,-MD,...' 127c819e2cfSJiri Olsa (for compiled object) 128c819e2cfSJiri Olsa 129c819e2cfSJiri OlsaAll existing '.cmd' files are included in the Build process to follow properly 130c819e2cfSJiri Olsathe dependencies and trigger a rebuild when necessary. 131c819e2cfSJiri Olsa 132c819e2cfSJiri Olsa 133c819e2cfSJiri Olsae) Single rules 134c819e2cfSJiri Olsa--------------- 135c819e2cfSJiri Olsa 136c819e2cfSJiri OlsaIt's possible to build single object file by choice, like: 137c819e2cfSJiri Olsa 138c819e2cfSJiri Olsa $ make util/map.o # objects 139c819e2cfSJiri Olsa $ make util/map.i # preprocessor 140c819e2cfSJiri Olsa $ make util/map.s # assembly 141