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