[linux-2.6-block.git] / tools / build / Documentation / Build.txt

Build Framework
===============

The perf build framework was adopted from the kernel build system, hence the
idea and the way how objects are built is the same.

Basically the user provides set of 'Build' files that list objects and
directories to nest for specific target to be build.

Unlike the kernel we don't have a single build object 'obj-y' list that where
we setup source objects, but we support more. This allows one 'Build' file to
carry a sources list for multiple build objects.

a) Build framework makefiles
----------------------------

The build framework consists of 2 Makefiles:

  Build.include
  Makefile.build

While the 'Build.include' file contains just some generic definitions, the
'Makefile.build' file is the makefile used from the outside. It's
interface/usage is following:

  $ make -f tools/build/Makefile srctree=$(KSRC) dir=$(DIR) obj=$(OBJECT)

where:

  KSRC   - is the path to kernel sources
  DIR    - is the path to the project to be built
  OBJECT - is the name of the build object

When succefully finished the $(DIR) directory contains the final object file
called $(OBJECT)-in.o:

  $ ls $(DIR)/$(OBJECT)-in.o

which includes all compiled sources described in 'Build' makefiles.

a) Build makefiles
------------------

The user supplies 'Build' makefiles that contains a objects list, and connects
the build to nested directories.

Assume we have the following project structure:

  ex/a.c
    /b.c
    /c.c
    /d.c
    /arch/e.c
    /arch/f.c

Out of which you build the 'ex' binary ' and the 'libex.a' library:

  'ex'      - consists of 'a.o', 'b.o' and libex.a
  'libex.a' - consists of 'c.o', 'd.o', 'e.o' and 'f.o'

The build framework does not create the 'ex' and 'libex.a' binaries for you, it
only prepares proper objects to be compiled and grouped together.

To follow the above example, the user provides following 'Build' files:

  ex/Build:
    ex-y += a.o
    ex-y += b.o

    libex-y += c.o
    libex-y += d.o
    libex-y += arch/

  ex/arch/Build:
    libex-y += e.o
    libex-y += f.o

and runs:

  $ make -f tools/build/Makefile.build dir=. obj=ex
  $ make -f tools/build/Makefile.build dir=. obj=libex

which creates the following objects:

  ex/ex-in.o
  ex/libex-in.o

that contain request objects names in Build files.

It's only a matter of 2 single commands to create the final binaries:

  $ ar  rcs libex.a libex-in.o
  $ gcc -o ex ex-in.o libex.a

You can check the 'ex' example in 'tools/build/tests/ex' for more details.

b) Rules
--------

The build framework provides standard compilation rules to handle .S and .c
compilation.

It's possible to include special rule if needed (like we do for flex or bison
code generation).

c) CFLAGS
---------

It's possible to alter the standard object C flags in the following way:

  CFLAGS_perf.o += '...' - alters CFLAGS for perf.o object
  CFLAGS_gtk += '...'    - alters CFLAGS for gtk build object

This C flags changes has the scope of the Build makefile they are defined in.


d) Dependencies
---------------

For each built object file 'a.o' the '.a.cmd' is created and holds:

  - Command line used to built that object
    (for each object)

  - Dependency rules generated by 'gcc -Wp,-MD,...'
    (for compiled object)

All existing '.cmd' files are included in the Build process to follow properly
the dependencies and trigger a rebuild when necessary.


e) Single rules
---------------

It's possible to build single object file by choice, like:

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