VirtualBox

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

Last change on this file since 31670 was 28800, checked in by vboxsync, 15 years ago

Automated rebranding to Oracle copyright/license strings via filemuncher

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 7.6 KB
Line 
1/* $Id: VBox-MakefileGuidelines.cpp 28800 2010-04-27 08:22:32Z vboxsync $ */
2/** @file
3 * VBox - Makefile Guidelines.
4 */
5
6/*
7 * Copyright (C) 2009 Oracle Corporation
8 *
9 * This file is part of VirtualBox Open Source Edition (OSE), as
10 * available from http://www.virtualbox.org. This file is free software;
11 * you can redistribute it and/or modify it under the terms of the GNU
12 * General Public License (GPL) as published by the Free Software
13 * Foundation, in version 2 as it comes in the "COPYING" file of the
14 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 */
17
18/** @page pg_vbox_makefile_guidelines VBox Makefile Guidelines
19 *
20 * These guidelines apply to all the Makefile.kmk files in the tree.
21 * No exceptions.
22 *
23 * All these makefiles are ultimately the responsiblity of bird. Since there are
24 * currently more than two hundred files and the number is growing, they have to
25 * be very kept uniform or it will become very difficult to maintain them and
26 * impossible do bulk refactoring. Thus these guidelines have no bits that are
27 * optional unlike the coding guidelines, and should be thought of as rules
28 * rather than guidelines.
29 *
30 * Note! The guidelines do not apply to the other makefiles found in the source
31 * tree, like the ones shipped in the SDK and the ones for the linux kernel
32 * modules.
33 *
34 *
35 * @section sec_vbox_makefile_guidelines_kbuild kBuild
36 *
37 * kBuild is way older than VirtualBox, at least as a concept, but the
38 * VirtualBox project was a push to get something done about it again. It's
39 * maintained by bird in his spare time because: "We don't make buildsystems, we
40 * make virtual machines". So, kBuild makes progress when there is spare time or
41 * when there is an urgent need for something.
42 *
43 * The kBuild docs are in the process of being written. The current items and
44 * their status per 2009-04-19:
45 * - kmk Quick Reference [completed]:
46 * http://svn.netlabs.org/kbuild/wiki/kmk%20Quick%20Reference
47 * - kBuild Quick Reference [just started]:
48 * http://svn.netlabs.org/kbuild/wiki/kBuild%20Quick%20Reference
49 *
50 * Local copies of the docs can be found in kBuild/docs, just keep in mind that
51 * they might be slightly behind the online version.
52 *
53 *
54 * @section sec_vbox_makefile_guidelines_example Example Makefiles
55 *
56 * Let me point to some good sample makefiles:
57 * - src/VBox/Additions/common/VBoxService/Makefile.kmk
58 * - src/VBox/Debugger/Makefile.kmk
59 * - src/VBox/Disassembler/Makefile.kmk
60 *
61 * And some bad ones:
62 * - src/lib/xpcom18a4/Makefile.kmk
63 * - src/recompiler/Makefile.kmk
64 * - src/VBox/Devices/Makefile.kmk
65 * - src/VBox/Main/Makefile.kmk
66 * - src/VBox/Runtime/Makefile.kmk
67 *
68 *
69 * @section sec_vbox_makefile_guidelines Guidelines
70 *
71 * First one really important fact:
72 *
73 * Everything is global because all makefiles
74 * are virtually one single makefile.
75 *
76 * The rules:
77 *
78 * - Using bits defined by a sub-makefile is fine, using anything defined
79 * by a parent, sibling, uncle, cousine, or remoter relatives is not
80 * Okay. It may break sub-tree building and possibly also
81 * VBOX_SINGLE_MAKEFILE, both things that has to work all the time.
82 *
83 * - The traditional recursive build must always work, i.e. undefine
84 * VBOX_SINGLE_MAKEFILE.
85 *
86 * - Template names starts with VBOX and are all upper cased, no
87 * underscores or other separators. (TODO: Change this to camel case.)
88 *
89 * - Makefile variables shall be prefixed with VBOX or VB to avoid clashes
90 * with environment and kBuild variables.
91 *
92 * - Makefile variables are all upper cased and uses underscores to
93 * separate the words.
94 *
95 * - All variables are global. Make sure they are globally unique, but try
96 * not make them incredible long.
97 *
98 * - Makefile variables goes after the inclusion of the header and
99 * usually after including sub-makefiles.
100 *
101 * - Variables that are used by more than one makefile usually belongs
102 * in the monster file, Config.kmk.
103 *
104 * - Targets are lower or camel cased and as a rule the same as the
105 * resulting binary.
106 *
107 * - Install targets frequently have a -inst in their name, and a name that
108 * gives some idea what they install
109 *
110 * - Always use templates (mytarget_TEMPLATE = VBOXSOMETHING).
111 *
112 * - Comment each target with a 3+ line block as seen in
113 * src/VBox/Debugger/Makefile.kmk.
114 *
115 * - No space between the comment block and the target definition.
116 *
117 * - Try fit all the custom recipes after the target they apply to.
118 *
119 * - Custom recipes that apply to more than one target should be placed at
120 * the bottom of the makefile, before the footer inclusion when possible.
121 *
122 * - Do NOT use custom recipes to install stuff, use install targets.
123 * Generate files to inst-target_0_OUTDIR. (Yes, there are a lot places
124 * where we don't do this yet.)
125 *
126 * - Always break SOURCES, LIBS, long target list and other lists the
127 * manner Debugger_SOURCES is broken into multiple lines in
128 * src/VBox/Debugger/Makefile.kmk. I.e. exactly one tab, the file name /
129 * list item, another space, the slash and then the newline.
130 *
131 * - The last element of an broken list should not have a slash-newline,
132 * otherwise we risk getting the next variable into the list.
133 *
134 * - Indentation of if'ed blocks is done in 1 space increments, this also
135 * applies to broken lists. It does not apply to the commands in a
136 * recipes of course, because that would make kmk choke. (Yes, there are
137 * plenty examples of doing this differently, but these will be weeded
138 * out over time.)
139 *
140 * - \$(NO_SUCH_VARIABLE) should be when you need to put nothing somewhere,
141 * for instance to prevent inherting an attribute.
142 *
143 * - Always put the defines in the DEFS properties, never use the FLAGS
144 * properties for this. Doing so may screw up depenencies and object
145 * caches.
146 *
147 * - Mark each section and target of the file with a 3+ lines comment
148 * block.
149 *
150 * - Document variables that are not obvious using double hash comments.
151 *
152 * - Each an every Makefile.kmk shall have a file header with Id, file
153 * description and copyright/license exactly like in the examples.
154 *
155 * - Multiple blank lines in a makefile is very seldom there without a
156 * reason and shall be preserved.
157 *
158 * - Inserting blank lines between target properties is all right if the
159 * target definition is long and/or crooked.
160 *
161 * - if1of and ifn1of shall always have a space after the comma, while ifeq
162 * and ifneq shall not. That way they are easier to tell apart.
163 *
164 * - Do a svn diff before committing makefile changes.
165 *
166 *
167 * @section sec_vbox_makefile_guidelines_reminders Helpful reminders
168 *
169 * - Do not be afraid to ask for help on IRC or in the defect you're
170 * working on. There are usually somebody around that know how to best do
171 * something.
172 *
173 * - Watch out for "Heads Up!" bugtracker messages concerning the build
174 * system.
175 *
176 * - To remove bits from a template you're using you have to create a new
177 * template that extends the existing one and creatively use
178 * \$(filter-out) or \$(patsubst).
179 *
180 * - You can build sub-trees.
181 *
182 * - You don't have to cd into sub-trees: kmk -C src/recompiler
183 *
184 * - You can build individual targets: kmk VBoxRT
185 *
186 * - Even install targets: kmk nobin
187 *
188 * - You can compile individual source files: kmk ConsoleImpl.o
189 *
190 */
191
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