1.\" Copyright (c) 2002-2003 David O'Brien <obrien@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the author nor the names of any contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL DAVID O'BRIEN OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" $FreeBSD$ 29.\" 30.Dd July 17, 2023 31.Dt STYLE.MAKEFILE 5 32.Os 33.Sh NAME 34.Nm style.Makefile 35.Nd 36.Fx 37.Pa Makefile 38file style guide 39.Sh DESCRIPTION 40This file specifies the preferred style for makefiles in the 41.Fx 42source tree. 43.Bl -bullet 44.It 45.Cm .PATH : 46comes first if needed, and is spelled 47.Dq Li ".PATH: " , 48with a single 49.Tn ASCII 50space after a colon. 51Do not use the 52.Va VPATH 53variable. 54.It 55Special variables (i.e., 56.Va LIB , SRCS , MLINKS , 57etc.) are listed in order of 58.Dq product , 59then building and installing a binary. 60Special variables may also be listed in 61.Dq build 62order: i.e., ones for the primary program (or library) first. 63The general 64.Dq product 65order is: 66.Va PROG Ns / Ns Oo Va SH Oc Ns Va LIB Ns / Ns Va SCRIPTS 67.Va FILES 68.Va LINKS 69.Va MAN 70.Va MLINKS 71.Va INCS 72.Va SRCS 73.Va WARNS 74.Va CSTD 75.Va CFLAGS 76.Va DPADD 77.Va LDADD . 78The general 79.Dq build 80order is: 81.Va PROG Ns / Ns Oo Va SH Oc Ns Va LIB Ns / Ns Va SCRIPTS 82.Va SRCS 83.Va WARNS 84.Va CSTD 85.Va CFLAGS 86.Va DPADD 87.Va LDADD 88.Va INCS 89.Va FILES 90.Va LINKS 91.Va MAN 92.Va MLINKS . 93.It 94Omit 95.Va SRCS 96when using 97.In bsd.prog.mk 98and there is a single source file named the same as the 99.Va PROG . 100.It 101Omit 102.Va MAN 103when using 104.In bsd.prog.mk 105and the manual page is named the same as the 106.Va PROG , 107and is in section 1. 108.It 109All variable assignments are spelled 110.Dq Va VAR Ns Ic = , 111i.e., no space between the variable name and the 112.Ic = . 113Keep values sorted alphabetically, if possible. 114.It 115Variables are expanded with 116.Sy {} , 117not 118.Sy () . 119Such as 120.Va ${VARIABLE} . 121.It 122Do not use 123.Ic += 124to set variables that are only set once 125(or to set variables for the first time). 126.It 127Do not use vertical whitespace in simple makefiles, 128but do use it to group locally related things in more complex/longer ones. 129.It 130.Va WARNS 131comes before 132.Va CFLAGS , 133as it is basically a 134.Va CFLAGS 135modifier. 136It comes before 137.Va CFLAGS 138rather than after 139.Va CFLAGS 140so it does not get lost in a sea of 141.Va CFLAGS 142statements as 143.Va WARNS 144is an important thing. 145The usage of 146.Va WARNS 147is spelled 148.Dq Li "WARNS?= " , 149so that it may be overridden on the command line or in 150.Xr make.conf 5 . 151.It 152.Dq Li "MK_WERROR=no" 153should not be used, 154it defeats the purpose of 155.Va WARNS . 156It should only be used on the command line and in special circumstances. 157.It 158.Va CFLAGS 159is spelled 160.Dq Li "CFLAGS+= " . 161.It 162Listing 163.Fl D Ns 's 164before 165.Fl I Ns 's 166in 167.Va CFLAGS 168is preferred for alphabetical ordering and to make 169.Fl D Ns 's 170easier to see. 171The 172.Fl D Ns 's 173often affect conditional compilation, 174and 175.Fl I Ns 's 176tend to be quite long. 177Split long 178.Va CFLAGS 179settings between the 180.Fl D Ns 's 181and 182.Fl I Ns 's. 183.It 184Do not use GCCisms (such as 185.Fl g 186and 187.Fl Wall ) 188in 189.Va CFLAGS . 190.It 191Typically, there is one 192.Tn ASCII 193tab between 194.Va VAR Ns Ic = 195and the value in order to start the value in column 9. 196An 197.Tn ASCII 198space is allowed for variable names that extend beyond column 9. 199A lack of whitespace is also allowed for very long variable names. 200.It 201.Ic .include In bsd.*.mk 202goes last. 203.It 204Do not use anachronisms like 205.Va $< 206and 207.Va $@ . 208Instead use 209.Va ${.IMPSRC} 210or 211.Va ${.ALLSRC} 212and 213.Va ${.TARGET} . 214.It 215To not build the 216.Dq foo 217part of the base system, 218use 219.Va NO_FOO , 220not 221.Va NOFOO . 222.It 223To optionally build something in the base system, 224spell the knob 225.Va WITH_FOO 226not 227.Va WANT_FOO 228or 229.Va USE_FOO . 230The latter are reserved for the 231.Fx 232Ports Collection. 233.It 234For variables that are only checked with 235.Fn defined , 236do not provide any fake value. 237.El 238.Pp 239The desire to express a logical grouping often means not obeying some of the 240above. 241.Sh EXAMPLES 242The simplest program 243.Pa Makefile 244is: 245.Bd -literal -offset indent 246PROG= foo 247 248\&.include <bsd.prog.mk> 249.Ed 250.Pp 251The simplest library 252.Pa Makefile 253is: 254.Bd -literal -offset indent 255LIB= foo 256SHLIB_MAJOR= 1 257MAN= libfoo.3 258SRCS= foo.c 259 260\&.include <bsd.lib.mk> 261.Ed 262.Sh SEE ALSO 263.Xr make 1 , 264.Xr make.conf 5 , 265.Xr style 9 266.Sh HISTORY 267This manual page is inspired from the same source as 268.Xr style 9 269manual page in 270.Fx . 271.Sh BUGS 272There are few hard and fast style rules here. 273The style of many things is too dependent on the context of the whole makefile, 274or the lines surrounding it. 275