VirtualBox

source: vbox/trunk/doc/VBox-MakefileGuidelines.cpp@ 96562

Last change on this file since 96562 was 96407, checked in by vboxsync, 2 years ago

scm copyright and license note update

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 8.6 KB
Line 
1/* $Id: VBox-MakefileGuidelines.cpp 96407 2022-08-22 17:43:14Z vboxsync $ */
2/** @file
3 * VBox - Makefile Guidelines.
4 */
5
6/*
7 * Copyright (C) 2009-2022 Oracle and/or its affiliates.
8 *
9 * This file is part of VirtualBox base platform packages, as
10 * available from https://www.virtualbox.org.
11 *
12 * This program is free software; you can redistribute it and/or
13 * modify it under the terms of the GNU General Public License
14 * as published by the Free Software Foundation, in version 3 of the
15 * License.
16 *
17 * This program is distributed in the hope that it will be useful, but
18 * WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 * General Public License for more details.
21 *
22 * You should have received a copy of the GNU General Public License
23 * along with this program; if not, see <https://www.gnu.org/licenses>.
24 *
25 * SPDX-License-Identifier: GPL-3.0-only
26 */
27
28/** @page pg_vbox_makefile_guidelines VBox Makefile Guidelines
29 *
30 * These guidelines apply to all the Makefile.kmk files in the tree.
31 * No exceptions.
32 *
33 * All these makefiles are ultimately the responsiblity of bird. Since there
34 * are currently more than three hundred files and the number is growing, they
35 * have to be very kept uniform or it will become very difficult to maintain
36 * them and impossible do bulk refactoring. Thus these guidelines have no bits
37 * that are optional unlike the coding guidelines, and should be thought of as
38 * rules rather than guidelines.
39 *
40 * Note! The guidelines do not apply to the non-kBuild makefiles found in the
41 * source tree, like the ones shipped in the SDK and the ones for the
42 * linux kernel modules.
43 *
44 *
45 * @section sec_vbox_makefile_guidelines_kbuild kBuild
46 *
47 * kBuild is way older than VirtualBox, at least as a concept, but the
48 * VirtualBox project was a push to get something done about it again. It's
49 * maintained by bird in his spare time because: "We don't make buildsystems, we
50 * make virtual machines". So, kBuild makes progress when there is spare time
51 * or when there is an urgent need for something.
52 *
53 * The kBuild docs are in the process of being written. The current items and
54 * their status per 2018-10-29:
55 * - kmk Quick Reference [completed]:
56 * http://svn.netlabs.org/kbuild/wiki/kmk%20Quick%20Reference
57 * - kBuild Quick Reference [just started]:
58 * http://svn.netlabs.org/kbuild/wiki/kBuild%20Quick%20Reference
59 *
60 * Local copies of the docs can be found in kBuild/docs, just keep in mind that
61 * they might be slightly behind the online version.
62 *
63 *
64 * @section sec_vbox_makefile_guidelines_example Example Makefiles
65 *
66 * Let me point to some good sample makefiles:
67 * - src/VBox/Additions/common/VBoxService/Makefile.kmk
68 * - src/VBox/Debugger/Makefile.kmk
69 * - src/VBox/Disassembler/Makefile.kmk
70 *
71 * And some bad ones:
72 * - src/lib/xpcom18a4/Makefile.kmk
73 * - src/recompiler/Makefile.kmk
74 * - src/VBox/Devices/Makefile.kmk
75 * - src/VBox/Main/Makefile.kmk
76 * - src/VBox/Runtime/Makefile.kmk
77 *
78 *
79 * @section sec_vbox_makefile_guidelines Guidelines
80 *
81 * First one really important fact:
82 *
83 * Everything is global because all makefiles
84 * are virtually one single makefile.
85 *
86 * The rules:
87 *
88 * - Using bits defined by a sub-makefile is fine, using anything defined
89 * by a parent, sibling, uncle, cousine, or remoter relatives is not
90 * Okay. It may break sub-tree building which is not acceptable.
91 *
92 * - Template names starts with VBox and are camel cased, no
93 * underscores or other separators. (Note this used to be all upper
94 * case, fixing this incomplete.)
95 *
96 * - Makefile variables shall be prefixed with VBOX or VB to avoid clashes
97 * with environment and kBuild variables.
98 *
99 * - Makefile variables are all upper cased and uses underscores to
100 * separate the words.
101 *
102 * - All variables are global. Make sure they are globally unique, but try
103 * not make them incredible long.
104 *
105 * - Makefile variables goes after the inclusion of the header and
106 * usually after including sub-makefiles.
107 *
108 * - Variables that are used by more than one makefile usually ends up
109 * in the monster file, Config.kmk. However, see if there are any
110 * sub-tree specific Config.kmk files that could do the job first.
111 *
112 * - Targets are lower or camel cased and as a rule the same as the
113 * resulting binary.
114 *
115 * - Install targets frequently have a -inst in their name, and a name that
116 * gives some idea what they install
117 *
118 * - Always use templates (mytarget_TEMPLATE = VBoxSomething).
119 *
120 * - Comment each target with a 3+ line block as seen in
121 * src/VBox/Debugger/Makefile.kmk.
122 *
123 * - No space between the comment block and the target definition.
124 *
125 * - Try fit all the custom recipes after the target they apply to.
126 *
127 * - Custom recipes that apply to more than one target should be placed at
128 * the bottom of the makefile, before the footer inclusion when possible.
129 *
130 * - Do NOT use custom recipes to install stuff, use install targets.
131 * Generate files to inst-target_0_OUTDIR. (Yes, there are a lot places
132 * where we don't do this yet.)
133 *
134 * - Always break SOURCES, LIBS, long target list and other lists the
135 * manner Debugger_SOURCES is broken into multiple lines in
136 * src/VBox/Debugger/Makefile.kmk. I.e. exactly one tab, the file name /
137 * list item, another space, the slash and then the newline.
138 *
139 * - Line continuation slashes shall never ever be aligned vertically (that
140 * always goes crooked sooner or later), but have exactly one space
141 * before them.
142 *
143 * - The last element of an broken list shall not have a slash-newline,
144 * otherwise we risk getting the next variable into the list.
145 *
146 * - When if'ed blocks come into play, we will only indent the conditional
147 * makefile directives (if, ifeq, ifneq, if1of, ifn1of, ifdef, ifndef,
148 * else, endif, ++), one space for each level. (Note! We used to indent
149 * non-directives, which made emacs upset as we'd have both tabs and
150 * spaces on as indentation on the same line. There are a lot of cases
151 * of this still around.)
152 *
153 * - \$(NO_SUCH_VARIABLE) should be when you need to put nothing somewhere,
154 * for instance to prevent inherting an attribute.
155 *
156 * - Always put the defines in the DEFS properties, never use the FLAGS
157 * properties for this. Doing so may screw up depenencies and object
158 * caches.
159 *
160 * - Mark each section and target of the file with a 3+ lines comment
161 * block.
162 *
163 * - Document variables that are not immediately obvious using double hash
164 * comments, doxygen style.
165 *
166 * - Each an every Makefile.kmk shall have a file header with Id, file
167 * description and copyright/license exactly like in the examples. (The
168 * SCM tool will complain if you don't.)
169 *
170 * - Multiple blank lines in a makefile is very seldom there without a
171 * reason and shall be preserved.
172 *
173 * - Inserting blank lines between target properties is all right if the
174 * target definition is long and/or crooked.
175 *
176 * - if1of and ifn1of shall always have a space after the comma, while ifeq
177 * and ifneq shall not. That way they are easier to tell apart.
178 *
179 * - Do a svn diff before committing makefile changes.
180 *
181 *
182 * @section sec_vbox_makefile_guidelines_reminders Helpful reminders
183 *
184 * - Do not be afraid to ask for help on IRC or in the defect you're
185 * working on. There are usually somebody around that know how to best do
186 * something.
187 *
188 * - Watch out for "Heads Up!" bugtracker messages concerning the build
189 * system.
190 *
191 * - To remove bits from a template you're using you have to create a new
192 * template that extends the existing one and creatively use
193 * \$(filter-out) or \$(patsubst).
194 *
195 * - You can build sub-trees.
196 *
197 * - You don't have to cd into sub-trees: kmk -C src/recompiler
198 *
199 * - You can build individual targets: kmk VBoxRT
200 *
201 * - Even install targets: kmk nobin
202 *
203 * - You can compile individual source files: kmk ConsoleImpl.o
204 *
205 * - You can tell kmk to continue on failure: kmk -k
206 *
207 * - You can tell kmk to run at low priority: kmk --nice
208 *
209 * - The --pretty-command-printing option is useful for seeing exactly
210 * what's passed to the tools.
211 *
212 * - You can invoke recipes in the root makefile more efficiently via the
213 * Maintenance.kmk file: kmk -f Maintenance.kmk incs
214 *
215 */
216
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette