Build.txt 4.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166
  1. Build Framework
  2. ===============
  3. The perf build framework was adopted from the kernel build system, hence the
  4. idea and the way how objects are built is the same.
  5. Basically the user provides set of 'Build' files that list objects and
  6. directories to nest for specific target to be build.
  7. Unlike the kernel we don't have a single build object 'obj-y' list that where
  8. we setup source objects, but we support more. This allows one 'Build' file to
  9. carry a sources list for multiple build objects.
  10. Build framework makefiles
  11. -------------------------
  12. The build framework consists of 2 Makefiles:
  13. Build.include
  14. Makefile.build
  15. While the 'Build.include' file contains just some generic definitions, the
  16. 'Makefile.build' file is the makefile used from the outside. It's
  17. interface/usage is following:
  18. $ make -f tools/build/Makefile.build srctree=$(KSRC) dir=$(DIR) obj=$(OBJECT)
  19. where:
  20. KSRC - is the path to kernel sources
  21. DIR - is the path to the project to be built
  22. OBJECT - is the name of the build object
  23. When succefully finished the $(DIR) directory contains the final object file
  24. called $(OBJECT)-in.o:
  25. $ ls $(DIR)/$(OBJECT)-in.o
  26. which includes all compiled sources described in 'Build' makefiles.
  27. Build makefiles
  28. ---------------
  29. The user supplies 'Build' makefiles that contains a objects list, and connects
  30. the build to nested directories.
  31. Assume we have the following project structure:
  32. ex/a.c
  33. /b.c
  34. /c.c
  35. /d.c
  36. /arch/e.c
  37. /arch/f.c
  38. Out of which you build the 'ex' binary ' and the 'libex.a' library:
  39. 'ex' - consists of 'a.o', 'b.o' and libex.a
  40. 'libex.a' - consists of 'c.o', 'd.o', 'e.o' and 'f.o'
  41. The build framework does not create the 'ex' and 'libex.a' binaries for you, it
  42. only prepares proper objects to be compiled and grouped together.
  43. To follow the above example, the user provides following 'Build' files:
  44. ex/Build:
  45. ex-y += a.o
  46. ex-y += b.o
  47. ex-y += b.o # duplicates in the lists are allowed
  48. libex-y += c.o
  49. libex-y += d.o
  50. libex-y += arch/
  51. ex/arch/Build:
  52. libex-y += e.o
  53. libex-y += f.o
  54. and runs:
  55. $ make -f tools/build/Makefile.build dir=. obj=ex
  56. $ make -f tools/build/Makefile.build dir=. obj=libex
  57. which creates the following objects:
  58. ex/ex-in.o
  59. ex/libex-in.o
  60. that contain request objects names in Build files.
  61. It's only a matter of 2 single commands to create the final binaries:
  62. $ ar rcs libex.a libex-in.o
  63. $ gcc -o ex ex-in.o libex.a
  64. You can check the 'ex' example in 'tools/build/tests/ex' for more details.
  65. Makefile.include
  66. ----------------
  67. The tools/build/Makefile.include makefile could be included
  68. via user makefiles to get usefull definitions.
  69. It defines following interface:
  70. - build macro definition:
  71. build := -f $(srctree)/tools/build/Makefile.build dir=. obj
  72. to make it easier to invoke build like:
  73. make $(build)=ex
  74. Fixdep
  75. ------
  76. It is necessary to build the fixdep helper before invoking the build.
  77. The Makefile.include file adds the fixdep target, that could be
  78. invoked by the user.
  79. Rules
  80. -----
  81. The build framework provides standard compilation rules to handle .S and .c
  82. compilation.
  83. It's possible to include special rule if needed (like we do for flex or bison
  84. code generation).
  85. CFLAGS
  86. ------
  87. It's possible to alter the standard object C flags in the following way:
  88. CFLAGS_perf.o += '...' - alters CFLAGS for perf.o object
  89. CFLAGS_gtk += '...' - alters CFLAGS for gtk build object
  90. This C flags changes has the scope of the Build makefile they are defined in.
  91. Dependencies
  92. ------------
  93. For each built object file 'a.o' the '.a.cmd' is created and holds:
  94. - Command line used to built that object
  95. (for each object)
  96. - Dependency rules generated by 'gcc -Wp,-MD,...'
  97. (for compiled object)
  98. All existing '.cmd' files are included in the Build process to follow properly
  99. the dependencies and trigger a rebuild when necessary.
  100. Single rules
  101. ------------
  102. It's possible to build single object file by choice, like:
  103. $ make util/map.o # objects
  104. $ make util/map.i # preprocessor
  105. $ make util/map.s # assembly