/* $Id: VBox-MakefileGuidelines.cpp 93115 2022-01-01 11:31:46Z vboxsync $ */ /** @file * VBox - Makefile Guidelines. */ /* * Copyright (C) 2009-2022 Oracle Corporation * * This file is part of VirtualBox Open Source Edition (OSE), as * available from http://www.virtualbox.org. This file is free software; * you can redistribute it and/or modify it under the terms of the GNU * General Public License (GPL) as published by the Free Software * Foundation, in version 2 as it comes in the "COPYING" file of the * VirtualBox OSE distribution. VirtualBox OSE is distributed in the * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind. */ /** @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 * */