0001 Build Framework
0002 ===============
0003
0004 The perf build framework was adopted from the kernel build system, hence the
0005 idea and the way how objects are built is the same.
0006
0007 Basically the user provides set of 'Build' files that list objects and
0008 directories to nest for specific target to be build.
0009
0010 Unlike the kernel we don't have a single build object 'obj-y' list that where
0011 we setup source objects, but we support more. This allows one 'Build' file to
0012 carry a sources list for multiple build objects.
0013
0014
0015 Build framework makefiles
0016 -------------------------
0017
0018 The build framework consists of 2 Makefiles:
0019
0020 Build.include
0021 Makefile.build
0022
0023 While the 'Build.include' file contains just some generic definitions, the
0024 'Makefile.build' file is the makefile used from the outside. It's
0025 interface/usage is following:
0026
0027 $ make -f tools/build/Makefile.build srctree=$(KSRC) dir=$(DIR) obj=$(OBJECT)
0028
0029 where:
0030
0031 KSRC - is the path to kernel sources
0032 DIR - is the path to the project to be built
0033 OBJECT - is the name of the build object
0034
0035 When succefully finished the $(DIR) directory contains the final object file
0036 called $(OBJECT)-in.o:
0037
0038 $ ls $(DIR)/$(OBJECT)-in.o
0039
0040 which includes all compiled sources described in 'Build' makefiles.
0041
0042
0043 Build makefiles
0044 ---------------
0045
0046 The user supplies 'Build' makefiles that contains a objects list, and connects
0047 the build to nested directories.
0048
0049 Assume we have the following project structure:
0050
0051 ex/a.c
0052 /b.c
0053 /c.c
0054 /d.c
0055 /arch/e.c
0056 /arch/f.c
0057
0058 Out of which you build the 'ex' binary ' and the 'libex.a' library:
0059
0060 'ex' - consists of 'a.o', 'b.o' and libex.a
0061 'libex.a' - consists of 'c.o', 'd.o', 'e.o' and 'f.o'
0062
0063 The build framework does not create the 'ex' and 'libex.a' binaries for you, it
0064 only prepares proper objects to be compiled and grouped together.
0065
0066 To follow the above example, the user provides following 'Build' files:
0067
0068 ex/Build:
0069 ex-y += a.o
0070 ex-y += b.o
0071 ex-y += b.o # duplicates in the lists are allowed
0072
0073 libex-y += c.o
0074 libex-y += d.o
0075 libex-y += arch/
0076
0077 ex/arch/Build:
0078 libex-y += e.o
0079 libex-y += f.o
0080
0081 and runs:
0082
0083 $ make -f tools/build/Makefile.build dir=. obj=ex
0084 $ make -f tools/build/Makefile.build dir=. obj=libex
0085
0086 which creates the following objects:
0087
0088 ex/ex-in.o
0089 ex/libex-in.o
0090
0091 that contain request objects names in Build files.
0092
0093 It's only a matter of 2 single commands to create the final binaries:
0094
0095 $ ar rcs libex.a libex-in.o
0096 $ gcc -o ex ex-in.o libex.a
0097
0098 You can check the 'ex' example in 'tools/build/tests/ex' for more details.
0099
0100
0101 Makefile.include
0102 ----------------
0103
0104 The tools/build/Makefile.include makefile could be included
0105 via user makefiles to get usefull definitions.
0106
0107 It defines following interface:
0108
0109 - build macro definition:
0110 build := -f $(srctree)/tools/build/Makefile.build dir=. obj
0111
0112 to make it easier to invoke build like:
0113 make $(build)=ex
0114
0115
0116 Fixdep
0117 ------
0118 It is necessary to build the fixdep helper before invoking the build.
0119 The Makefile.include file adds the fixdep target, that could be
0120 invoked by the user.
0121
0122
0123 Rules
0124 -----
0125
0126 The build framework provides standard compilation rules to handle .S and .c
0127 compilation.
0128
0129 It's possible to include special rule if needed (like we do for flex or bison
0130 code generation).
0131
0132
0133 CFLAGS
0134 ------
0135
0136 It's possible to alter the standard object C flags in the following way:
0137
0138 CFLAGS_perf.o += '...' - adds CFLAGS for perf.o object
0139 CFLAGS_gtk += '...' - adds CFLAGS for gtk build object
0140 CFLAGS_REMOVE_perf.o += '...' - removes CFLAGS for perf.o object
0141 CFLAGS_REMOVE_gtk += '...' - removes CFLAGS for gtk build object
0142
0143 This C flags changes has the scope of the Build makefile they are defined in.
0144
0145
0146 Dependencies
0147 ------------
0148
0149 For each built object file 'a.o' the '.a.cmd' is created and holds:
0150
0151 - Command line used to built that object
0152 (for each object)
0153
0154 - Dependency rules generated by 'gcc -Wp,-MD,...'
0155 (for compiled object)
0156
0157 All existing '.cmd' files are included in the Build process to follow properly
0158 the dependencies and trigger a rebuild when necessary.
0159
0160
0161 Single rules
0162 ------------
0163
0164 It's possible to build single object file by choice, like:
0165
0166 $ make util/map.o # objects
0167 $ make util/map.i # preprocessor
0168 $ make util/map.s # assembly
