summaryrefslogtreecommitdiffstats
path: root/doc/VBox-MakefileGuidelines.cpp
diff options
context:
space:
mode:
Diffstat (limited to 'doc/VBox-MakefileGuidelines.cpp')
-rw-r--r--doc/VBox-MakefileGuidelines.cpp216
1 files changed, 216 insertions, 0 deletions
diff --git a/doc/VBox-MakefileGuidelines.cpp b/doc/VBox-MakefileGuidelines.cpp
new file mode 100644
index 00000000..b91bbc64
--- /dev/null
+++ b/doc/VBox-MakefileGuidelines.cpp
@@ -0,0 +1,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
+ *
+ */
+