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 August 25, 2020 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 45All makefiles should have an SCM ID at the start of the file, 46followed by a blank line. 47.Bd -literal 48# $FreeBSD\&$ 49 50.Ed 51.It 52.Cm .PATH : 53comes next if needed, and is spelled 54.Dq Li ".PATH: " , 55with a single 56.Tn ASCII 57space after a colon. 58Do not use the 59.Va VPATH 60variable. 61.It 62Special variables (i.e., 63.Va LIB , SRCS , MLINKS , 64etc.) are listed in order of 65.Dq product , 66then building and installing a binary. 67Special variables may also be listed in 68.Dq build 69order: i.e., ones for the primary program (or library) first. 70The general 71.Dq product 72order is: 73.Va PROG Ns / Ns Oo Va SH Oc Ns Va LIB Ns / Ns Va SCRIPTS 74.Va FILES 75.Va LINKS 76.Oo Va NO_ Oc Ns Va MAN 77.Va MLINKS 78.Va INCS 79.Va SRCS 80.Va WARNS 81.Va CSTD 82.Va CFLAGS 83.Va DPADD 84.Va LDADD . 85The general 86.Dq build 87order is: 88.Va PROG Ns / Ns Oo Va SH Oc Ns Va LIB Ns / Ns Va SCRIPTS 89.Va SRCS 90.Va WARNS 91.Va CSTD 92.Va CFLAGS 93.Va DPADD 94.Va LDADD 95.Va INCS 96.Va FILES 97.Va LINKS 98.Oo Va NO_ Oc Ns Va MAN 99.Va MLINKS . 100.It 101Omit 102.Va SRCS 103when using 104.In bsd.prog.mk 105and there is a single source file named the same as the 106.Va PROG . 107.It 108Omit 109.Va MAN 110when using 111.In bsd.prog.mk 112and the manual page is named the same as the 113.Va PROG , 114and is in section 1. 115.It 116All variable assignments are spelled 117.Dq Va VAR Ns Ic = , 118i.e., no space between the variable name and the 119.Ic = . 120Keep values sorted alphabetically, if possible. 121.It 122Variables are expanded with 123.Sy {} , 124not 125.Sy () . 126Such as 127.Va ${VARIABLE} . 128.It 129Do not use 130.Ic += 131to set variables that are only set once 132(or to set variables for the first time). 133.It 134Do not use vertical whitespace in simple makefiles, 135but do use it to group locally related things in more complex/longer ones. 136.It 137.Va WARNS 138comes before 139.Va CFLAGS , 140as it is basically a 141.Va CFLAGS 142modifier. 143It comes before 144.Va CFLAGS 145rather than after 146.Va CFLAGS 147so it does not get lost in a sea of 148.Va CFLAGS 149statements as 150.Va WARNS 151is an important thing. 152The usage of 153.Va WARNS 154is spelled 155.Dq Li "WARNS?= " , 156so that it may be overridden on the command line or in 157.Xr make.conf 5 . 158.It 159.Dq Li "MK_WERROR=no" 160should not be used, 161it defeats the purpose of 162.Va WARNS . 163It should only be used on the command line and in special circumstances. 164.It 165.Va CFLAGS 166is spelled 167.Dq Li "CFLAGS+= " . 168.It 169Listing 170.Fl D Ns 's 171before 172.Fl I Ns 's 173in 174.Va CFLAGS 175is preferred for alphabetical ordering and to make 176.Fl D Ns 's 177easier to see. 178The 179.Fl D Ns 's 180often affect conditional compilation, 181and 182.Fl I Ns 's 183tend to be quite long. 184Split long 185.Va CFLAGS 186settings between the 187.Fl D Ns 's 188and 189.Fl I Ns 's. 190.It 191Do not use GCCisms (such as 192.Fl g 193and 194.Fl Wall ) 195in 196.Va CFLAGS . 197.It 198Typically, there is one 199.Tn ASCII 200tab between 201.Va VAR Ns Ic = 202and the value in order to start the value in column 9. 203An 204.Tn ASCII 205space is allowed for variable names that extend beyond column 9. 206A lack of whitespace is also allowed for very long variable names. 207.It 208.Ic .include In bsd.*.mk 209goes last. 210.It 211Do not use anachronisms like 212.Va $< 213and 214.Va $@ . 215Instead use 216.Va ${.IMPSRC} 217or 218.Va ${.ALLSRC} 219and 220.Va ${.TARGET} . 221.It 222To not build the 223.Dq foo 224part of the base system, 225use 226.Va NO_FOO , 227not 228.Va NOFOO . 229.It 230To optionally build something in the base system, 231spell the knob 232.Va WITH_FOO 233not 234.Va WANT_FOO 235or 236.Va USE_FOO . 237The latter are reserved for the 238.Fx 239Ports Collection. 240.It 241For variables that are only checked with 242.Fn defined , 243do not provide any fake value. 244.El 245.Pp 246The desire to express a logical grouping often means not obeying some of the 247above. 248.Sh EXAMPLES 249The simplest program 250.Pa Makefile 251is: 252.Bd -literal -offset indent 253# $FreeBSD\&$ 254 255PROG= foo 256 257\&.include <bsd.prog.mk> 258.Ed 259.Pp 260The simplest library 261.Pa Makefile 262is: 263.Bd -literal -offset indent 264# $FreeBSD\&$ 265 266LIB= foo 267SHLIB_MAJOR= 1 268MAN= libfoo.3 269SRCS= foo.c 270 271\&.include <bsd.lib.mk> 272.Ed 273.Sh SEE ALSO 274.Xr make 1 , 275.Xr make.conf 5 , 276.Xr style 9 277.Sh HISTORY 278This manual page is inspired from the same source as 279.Xr style 9 280manual page in 281.Fx . 282.Sh BUGS 283There are few hard and fast style rules here. 284The style of many things is too dependent on the context of the whole makefile, 285or the lines surrounding it. 286