summaryrefslogtreecommitdiff
path: root/kBuild/doc/QuickReference-kBuild.txt
blob: 70079c1739e6fd0d05a19fdc3903bbdb7b6efcb2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276

kBuild Quick Reference
======================

This is an attempt at summarizing the magic of kBuild makefiles.


The anatomy of a kBuild Makefile
--------------------------------

A typical makefile::

    # $Id: QuickReference-kBuild.txt 2345 2009-04-19 23:47:42Z bird $
    ## @file
    # Makefile description.
    #

    #
    # Copyright (c) year name
    # License, disclaimer and other legal text.
    #

    SUB_DEPTH = ../..
    include $(KBUILD_PATH)/subheader.kmk

    #
    # Include sub-makefiles.
    #
    include $(PATH_CURRENT)/subdir1/Makefile.kmk
    include $(PATH_CURRENT)/subdir2/Makefile.kmk

    #
    # Global variables.
    #
    MYPREFIX_SOMETHING = or another

    #
    # Target lists.
    #
    DLLS += mydll
    PROGRAMS += myprogs

    #
    # mydll - description.
    #
    mydll_TEMPLATE = MYDLL
    mydll_SOURCES = mydll.c
    mydll_SOURCES.win = $(mydll_0_OUTDIR)/mydll.def

    #
    # myprog - description.
    #
    myprog_TEMPLATE = MYPROG
    myprog_SOURCES = myprog.c

    #
    # Custom rules (optional of course).
    #
    $$(mydll_0_OUTDIR)/mydll.def:
    	$(APPEND) -t $@ LIBRARY mydll.dll
    	$(APPEND)    $@ EXPORTS
    	$(APPEND)    $@ '    myfunction'

    include $(FILE_KBUILD_SUB_FOOTER)


Target lists
------------

+-+-------------------+-------------------------------------------------------+
|#| Name              | Description                                           |
+=+===================+=======================================================+
|1| ``BLDPROGS``      | Build programs, targets the host platform.            |
+-+-------------------+-------------------------------------------------------+
|2| ``LIBRARIES``     | Libraries (not shared).                               |
+-+-------------------+-------------------------------------------------------+
|3| ``IMPORT_LIBS``   | Import libraries or stub shared libraries.            |
+-+-------------------+-------------------------------------------------------+
|4| ``DLLS``          | DLLs, Shared Libraries, DYLIBs, etc.                  |
+-+-------------------+-------------------------------------------------------+
|5| ``PROGRAMS``      | Executable programs.                                  |
+-+-------------------+-------------------------------------------------------+
|6| ``SYSMODS``       | System modules (kexts, kernel modules, drivers, etc). |
+-+-------------------+-------------------------------------------------------+
|7| ``MISCBINS``      | Miscellanceous binaries like BIOS images and such.    |
+-+-------------------+-------------------------------------------------------+
|8| ``INSTALLS``      | Things to install. [1]_                               |
+-+-------------------+-------------------------------------------------------+
|9| ``FETCHES``       | Things to fetch. [1]_                                 |
+-+-------------------+-------------------------------------------------------+
|a| ``OTHERS``        | List of targets made during the others pass.          |
+-+-------------------+-------------------------------------------------------+


Target properties
-----------------

The first column indicates the kind of property, S=Single, D=Deferred,
Ar=Accumlate-Right and Al=Accumulate-Left.

The third column should be cross referenced with the first column in the
target list table above.

+--+-------------------+-------+----------------------------------------------+
|K | Name              | Which | Description                                  |
+==+===================+=======+==============================================+
|S | ``ARLIBSUFF``     | 2     |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``ARTOOL``        | 2     |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``ASOBJSUFF``     | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``ASTOOL``        | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``BINSUFF``       | 7     |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``BLD_TRG``       | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``BLD_TRG_ARCH``  | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``BLD_TRG_CPU``   | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``BLD_TYPE``      | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``COBJSUFF``      | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``CTOOL``         | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``CXXOBJSUFF``    | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``CXXTOOL``       | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``DLLSUFF``       | 34    |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``EXESUFF``       | 15    |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``FETCHDIR``      | 9     |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``FETCHTOOL``     | 9     |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``GID``           | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``INST``          | 1-9   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``LDTOOL``        | 13-7  |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``LIBSUFF``       | 234   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``MODE``          | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``NOINST``        | 1-8   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``OBJCOBJSUFF``   | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``OBJCTOOL``      | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``OBJSUFF``       | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``PATCHTOOL``     | 9     |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``RCOBJSUFF``     | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``RCTOOL``        | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``SYSSUFF``       | 6     |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``TEMPLATE``      | 1-9   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``TOOL``          | 1-9   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``UID``           | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|S | ``UNPACKTOOL``    | 9     |                                              |
+--+-------------------+-------+----------------------------------------------+
|D | ``INSTALLER``     | 1-8   |                                              |
+--+-------------------+-------+----------------------------------------------+
|D | ``INSTFUN``       | 1-8   |                                              |
+--+-------------------+-------+----------------------------------------------+
|D | ``NAME``          | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|D | ``POST_CMDS``     | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|D | ``PRE_CMDS``      | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|D | ``SONAME``        | 13-7  |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``ARFLAGS``       | 2     |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``ASDEFS``        | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``ASFLAGS``       | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``CDEFS``         | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``CFLAGS``        | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``CXXDEFS``       | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``CXXFLAGS``      | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``DEFS``          | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``DEPS``          | 1-8   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``FETCHFLAGS``    | 9     |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``IDFLAGS``       | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``IFDLAGS``       | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``ISFLAGS``       | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``LDFLAGS``       | 13-7  |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``LNK_DEPS``      | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``LNK_ORDERDEPS`` | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``OBJCDEFS``      | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``OBJCFLAGS``     | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``ORDERDEPS``     | 1-8   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``PATCHFLAGS``    | 9     |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``RCDEFS``        | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``RCFLAGS``       | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Ar| ``UNPACKFLAGS``   | 9     |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``ASINCS``        | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``BLDDIRS``       | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``CINCS``         | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``CLEAN``         | 1-9   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``CXXINCS``       | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``DIRS``          | 8     |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``INCS``          | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``INTERMEDIATES`` | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``LIBPATH``       | 13-7  |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``LIBS``          | 13-7  |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``OBJCINCS``      | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``RCINCS``        | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``SDKS``          | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``SOURCES``       | 1-9   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``SRC_HANDLERS``  | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+
|Al| ``USES``          | 1-7   |                                              |
+--+-------------------+-------+----------------------------------------------+


-----

.. [1] Normally not one of the default passes.

-----

:Status: $Id: QuickReference-kBuild.txt 2345 2009-04-19 23:47:42Z bird $
:Copyright: Copyright (c) 2009 knut st. osmundsen