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