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
|
/* $Id: VBox-MakefileGuidelines.cpp $ */
/** @file
* VBox - Makefile Guidelines.
*/
/*
* Copyright (C) 2009-2022 Oracle and/or its affiliates.
*
* This file is part of VirtualBox base platform packages, as
* available from https://www.virtualbox.org.
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation, in version 3 of the
* License.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, see <https://www.gnu.org/licenses>.
*
* SPDX-License-Identifier: GPL-3.0-only
*/
/** @page pg_vbox_makefile_guidelines VBox Makefile Guidelines
*
* These guidelines apply to all the Makefile.kmk files in the tree.
* No exceptions.
*
* All these makefiles are ultimately the responsiblity of bird. Since there
* are currently more than three hundred files and the number is growing, they
* have to be very kept uniform or it will become very difficult to maintain
* them and impossible do bulk refactoring. Thus these guidelines have no bits
* that are optional unlike the coding guidelines, and should be thought of as
* rules rather than guidelines.
*
* Note! The guidelines do not apply to the non-kBuild makefiles found in the
* source tree, like the ones shipped in the SDK and the ones for the
* linux kernel modules.
*
*
* @section sec_vbox_makefile_guidelines_kbuild kBuild
*
* kBuild is way older than VirtualBox, at least as a concept, but the
* VirtualBox project was a push to get something done about it again. It's
* maintained by bird in his spare time because: "We don't make buildsystems, we
* make virtual machines". So, kBuild makes progress when there is spare time
* or when there is an urgent need for something.
*
* The kBuild docs are in the process of being written. The current items and
* their status per 2018-10-29:
* - kmk Quick Reference [completed]:
* http://svn.netlabs.org/kbuild/wiki/kmk%20Quick%20Reference
* - kBuild Quick Reference [just started]:
* http://svn.netlabs.org/kbuild/wiki/kBuild%20Quick%20Reference
*
* Local copies of the docs can be found in kBuild/docs, just keep in mind that
* they might be slightly behind the online version.
*
*
* @section sec_vbox_makefile_guidelines_example Example Makefiles
*
* Let me point to some good sample makefiles:
* - src/VBox/Additions/common/VBoxService/Makefile.kmk
* - src/VBox/Debugger/Makefile.kmk
* - src/VBox/Disassembler/Makefile.kmk
*
* And some bad ones:
* - src/lib/xpcom18a4/Makefile.kmk
* - src/recompiler/Makefile.kmk
* - src/VBox/Devices/Makefile.kmk
* - src/VBox/Main/Makefile.kmk
* - src/VBox/Runtime/Makefile.kmk
*
*
* @section sec_vbox_makefile_guidelines Guidelines
*
* First one really important fact:
*
* Everything is global because all makefiles
* are virtually one single makefile.
*
* The rules:
*
* - Using bits defined by a sub-makefile is fine, using anything defined
* by a parent, sibling, uncle, cousine, or remoter relatives is not
* Okay. It may break sub-tree building which is not acceptable.
*
* - Template names starts with VBox and are camel cased, no
* underscores or other separators. (Note this used to be all upper
* case, fixing this incomplete.)
*
* - Makefile variables shall be prefixed with VBOX or VB to avoid clashes
* with environment and kBuild variables.
*
* - Makefile variables are all upper cased and uses underscores to
* separate the words.
*
* - All variables are global. Make sure they are globally unique, but try
* not make them incredible long.
*
* - Makefile variables goes after the inclusion of the header and
* usually after including sub-makefiles.
*
* - Variables that are used by more than one makefile usually ends up
* in the monster file, Config.kmk. However, see if there are any
* sub-tree specific Config.kmk files that could do the job first.
*
* - Targets are lower or camel cased and as a rule the same as the
* resulting binary.
*
* - Install targets frequently have a -inst in their name, and a name that
* gives some idea what they install
*
* - Always use templates (mytarget_TEMPLATE = VBoxSomething).
*
* - Comment each target with a 3+ line block as seen in
* src/VBox/Debugger/Makefile.kmk.
*
* - No space between the comment block and the target definition.
*
* - Try fit all the custom recipes after the target they apply to.
*
* - Custom recipes that apply to more than one target should be placed at
* the bottom of the makefile, before the footer inclusion when possible.
*
* - Do NOT use custom recipes to install stuff, use install targets.
* Generate files to inst-target_0_OUTDIR. (Yes, there are a lot places
* where we don't do this yet.)
*
* - Always break SOURCES, LIBS, long target list and other lists the
* manner Debugger_SOURCES is broken into multiple lines in
* src/VBox/Debugger/Makefile.kmk. I.e. exactly one tab, the file name /
* list item, another space, the slash and then the newline.
*
* - Line continuation slashes shall never ever be aligned vertically (that
* always goes crooked sooner or later), but have exactly one space
* before them.
*
* - The last element of an broken list shall not have a slash-newline,
* otherwise we risk getting the next variable into the list.
*
* - When if'ed blocks come into play, we will only indent the conditional
* makefile directives (if, ifeq, ifneq, if1of, ifn1of, ifdef, ifndef,
* else, endif, ++), one space for each level. (Note! We used to indent
* non-directives, which made emacs upset as we'd have both tabs and
* spaces on as indentation on the same line. There are a lot of cases
* of this still around.)
*
* - \$(NO_SUCH_VARIABLE) should be when you need to put nothing somewhere,
* for instance to prevent inherting an attribute.
*
* - Always put the defines in the DEFS properties, never use the FLAGS
* properties for this. Doing so may screw up depenencies and object
* caches.
*
* - Mark each section and target of the file with a 3+ lines comment
* block.
*
* - Document variables that are not immediately obvious using double hash
* comments, doxygen style.
*
* - Each an every Makefile.kmk shall have a file header with Id, file
* description and copyright/license exactly like in the examples. (The
* SCM tool will complain if you don't.)
*
* - Multiple blank lines in a makefile is very seldom there without a
* reason and shall be preserved.
*
* - Inserting blank lines between target properties is all right if the
* target definition is long and/or crooked.
*
* - if1of and ifn1of shall always have a space after the comma, while ifeq
* and ifneq shall not. That way they are easier to tell apart.
*
* - Do a svn diff before committing makefile changes.
*
*
* @section sec_vbox_makefile_guidelines_reminders Helpful reminders
*
* - Do not be afraid to ask for help on IRC or in the defect you're
* working on. There are usually somebody around that know how to best do
* something.
*
* - Watch out for "Heads Up!" bugtracker messages concerning the build
* system.
*
* - To remove bits from a template you're using you have to create a new
* template that extends the existing one and creatively use
* \$(filter-out) or \$(patsubst).
*
* - You can build sub-trees.
*
* - You don't have to cd into sub-trees: kmk -C src/recompiler
*
* - You can build individual targets: kmk VBoxRT
*
* - Even install targets: kmk nobin
*
* - You can compile individual source files: kmk ConsoleImpl.o
*
* - You can tell kmk to continue on failure: kmk -k
*
* - You can tell kmk to run at low priority: kmk --nice
*
* - The --pretty-command-printing option is useful for seeing exactly
* what's passed to the tools.
*
* - You can invoke recipes in the root makefile more efficiently via the
* Maintenance.kmk file: kmk -f Maintenance.kmk incs
*
*/
|
