VBox-MakefileGuidelines.cpp revision 2d8f7775ea7361ee20e62a6463e996d9234c7029
051203e46846205a982bcf5ab198a8b5f6f8e6e0vboxsync * VBox - Makefile Guidelines.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * Copyright (C) 2009 Sun Microsystems, Inc.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * available from http://www.virtualbox.org. This file is free software;
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * you can redistribute it and/or modify it under the terms of the GNU
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * General Public License (GPL) as published by the Free Software
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * Clara, CA 95054 USA or visit http://www.sun.com if you need
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * additional information or have any questions.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync/** @page pg_vbox_makefile_guidelines VBox Makefile Guidelines
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * These guidelines apply to all the Makefile.kmk files in the tree.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * No exceptions.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * All these makefiles are ultimately the responsiblity of bird. Since there are
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * currently more than two hundred files and the number is growing, they have to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * be very kept uniform or it will become very difficult to maintain them and
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * impossible do bulk refactoring. Thus these guidelines have no bits that are
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * optional unlike the coding guidelines, and should be thought of as rules
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * rather than guidelines.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * Note! The guidelines do not apply to the other makefiles found in the source
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * tree, like the ones shipped in the SDK and the ones for the linux kernel
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @section sec_vbox_makefile_guidelines_kbuild kBuild
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * kBuild is way older than VirtualBox, at least as a concept, but the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * VirtualBox project was a push to get something done about it again. It's
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * maintained by bird in his spare time because: "We don't make buildsystems, we
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * make virtual machines". So, kBuild makes progress when there is spare time or
6160306df39548f807965d1b3e6953ca2ce92847vboxsync * when there is an urgent need for something.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * The kBuild docs are in the process of being written. The current items and
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * their status per 2009-04-19:
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - kmk Quick Reference [completed]:
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * http://svn.netlabs.org/kbuild/wiki/kmk%20Quick%20Reference
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - kBuild Quick Reference [just started]:
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * http://svn.netlabs.org/kbuild/wiki/kBuild%20Quick%20Reference
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * Local copies of the docs can be found in kBuild/docs, just keep in mind that
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * they might be slightly behind the online version.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @section sec_vbox_makefile_guidelines_example Example Makefiles
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * Let me point to some good sample makefiles:
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - src/VBox/Additions/common/VBoxService/Makefile.kmk
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * And some bad ones:
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * @section sec_vbox_makefile_guidelines Guidelines
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * First one really important fact:
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * Everything is global because all makefiles
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * are virtually one single makefile.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * The rules:
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - Using bits defined by a sub-makefile is fine, using anything defined
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * by a parent, sibling, uncle, cousine, or remoter relatives is not
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * Okay. It may break sub-tree building and possibly also
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * VBOX_SINGLE_MAKEFILE, both things that has to work all the time.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - The traditional recursive build must always work, i.e. undefine
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * VBOX_SINGLE_MAKEFILE.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - Template names starts with VBOX and are all upper cased, no
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * underscores or other separators. (TODO: Change this to camel case.)
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - Makefile variables shall be prefixed with VBOX or VB to avoid clashes
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * with environment and kBuild variables.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - Makefile variables are all upper cased and uses underscores to
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * separate the words.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - All variables are global. Make sure they are globally unique, but try
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * not make them incredible long.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - Makefile variables goes after the inclusion of the header and
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * usually after including sub-makefiles.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - Variables that are used by more than one makefile usually belongs
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * in the monster file, Config.kmk.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - Targets are lower or camel cased and as a rule the same as the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * resulting binary.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - Install targets frequently have a -inst in their name, and a name that
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * gives some idea what they install
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - Always use templates (mytarget_TEMPLATE = VBOXSOMETHING).
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - Comment each target with a 3+ line block as seen in
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - No space between the comment block and the target definition.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - Try fit all the custom recipes after the target they apply to.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - Custom recipes that apply to more than one target should be placed at
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * the bottom of the makefile, before the footer inclusion when possible.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - Do NOT use custom recipes to install stuff, use install targets.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * Generate files to inst-target_0_OUTDIR. (Yes, there are a lot places
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * where we don't do this yet.)
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - Always break SOURCES, LIBS, long target list and other lists the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * manner Debugger_SOURCES is broken into multiple lines in
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * src/VBox/Debugger/Makefile.kmk. I.e. exactly one tab, the file name /
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * list item, another space, the slash and then the newline.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - The last element of an broken list should not have a slash-newline,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * otherwise we risk getting the next variable into the list.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - Indentation of if'ed blocks is done in 1 space increments, this also
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * applies to broken lists. It does not apply to the commands in a
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * recipes of course, because that would make kmk choke. (Yes, there are
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * plenty examples of doing this differently, but these will be weeded
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * out over time.)
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - \$(NO_SUCH_VARIABLE) should be when you need to put nothing somewhere,
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * for instance to prevent inherting an attribute.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - Always put the defines in the DEFS properties, never use the FLAGS
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * properties for this. Doing so may screw up depenencies and object
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - Mark each section and target of the file with a 3+ lines comment
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - Document variables that are not obvious using double hash comments.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - Each an every Makefile.kmk shall have a file header with Id, file
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * description and copyright/license exactly like in the examples.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - Multiple blank lines in a makefile is very seldom there without a
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * reason and shall be preserved.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - Inserting blank lines between target properties is all right if the
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * target definition is long and/or crooked.
e39cffdec314db08b1b3405c4ccd56728eaaa76avboxsync * - if1of and ifn1of shall always have a space after the comma, while ifeq
e39cffdec314db08b1b3405c4ccd56728eaaa76avboxsync * and ifneq shall not. That way they are easier to tell apart.
e39cffdec314db08b1b3405c4ccd56728eaaa76avboxsync * - Do a svn diff before committing makefile changes.
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync * @section sec_vbox_makefile_guidelines_reminders Helpful reminders
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync * - Do not be afraid to ask for help on IRC or in the defect you're
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync * working on. There are usually somebody around that know how to best do
bec052941a2aeb2a3d3bb695b2b37652b64df758vboxsync * something.
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - Watch out for "Heads Up!" bugtracker messages concerning the build
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - To remove bits from a template you're using you have to create a new
304f31a2a37f5d690086bff2fb4a59228b4dbd40vboxsync * template that extends the existing one and creatively use
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * \$(filter-out) or \$(patsubst).
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - You can build sub-trees.
051203e46846205a982bcf5ab198a8b5f6f8e6e0vboxsync * - You don't have to cd into sub-trees: kmk -C src/recompiler
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - You can build individual targets: kmk VBoxRT
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - Even install targets: kmk nobin
febf3f1de573e25fb134b8453a22b0732b4c52e2vboxsync * - You can compile individual source files: kmk ConsoleImpl.o