1.\" 2.\" SPDX-License-Identifier: BSD-3-Clause 3.\" 4.\" Copyright (c) 2002-2003, 2023, 2025 David O'Brien <deo@NUXI.org> 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the author nor the names of any contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL DAVID O'BRIEN OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.Dd October 29, 2025 32.Dt STYLE.MAKEFILE 5 33.Os 34.Sh NAME 35.Nm style.Makefile 36.Nd FreeBSD Makefile 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 182Lists that span more than one line should be formatted as follows: 183.Bd -literal -offset indent 184SRCS+=<SP>\\ 185<TAB>main.c<SP>\\ 186<TAB>trace.c<SP>\\ 187<TAB>zoo.c \\ 188\& 189.Ed 190Specifically, the last item in the list should have a trailing '\\'. 191This is to avoid causing a "false diff" or "false blame" when 192a new item is appended at the end. 193In general the list should be English language alphabetized. 194A list of libraries or header inclusion paths are notable exceptions 195if needed for proper building. 196.It 197Do not use GCCisms (such as 198.Fl g 199and 200.Fl Wall ) 201in 202.Va CFLAGS . 203.It 204Typically, there is one 205.Tn ASCII 206tab between 207.Va VAR Ns Ic = 208and the value in order to start the value in column 9. 209An 210.Tn ASCII 211space is allowed for variable names that extend beyond column 9. 212A lack of whitespace is also allowed for very long variable names. 213.It 214.Ic .include In bsd.*.mk 215goes last. 216.It 217Do not use anachronisms like 218.Va $< 219and 220.Va $@ . 221Instead use 222.Va ${.IMPSRC} 223or 224.Va ${.ALLSRC} 225and 226.Va ${.TARGET} . 227.It 228To not build the 229.Dq foo 230part of the base system, 231use 232.Va NO_FOO , 233not 234.Va NOFOO . 235.It 236To optionally build something in the base system, 237spell the knob 238.Va WITH_FOO 239not 240.Va WANT_FOO 241or 242.Va USE_FOO . 243The latter are reserved for the 244.Fx 245Ports Collection. 246.It 247For variables that are only checked with 248.Fn defined , 249do not provide any fake value. 250.El 251.Sh EXAMPLES 252The simplest program 253.Pa Makefile 254is: 255.Bd -literal -offset indent 256PROG= foo 257 258\&.include <bsd.prog.mk> 259.Ed 260.Pp 261The simplest library 262.Pa Makefile 263is: 264.Bd -literal -offset indent 265LIB= foo 266SHLIB_MAJOR= 1 267MAN= libfoo.3 268SRCS= foo.c 269 270\&.include <bsd.lib.mk> 271.Ed 272.Sh SEE ALSO 273.Xr make 1 , 274.Xr make.conf 5 , 275.Xr style 9 276.Sh HISTORY 277This manual page is inspired from the 278.Xr style 9 279manual page and first appeared in 280.Fx 5.1 . 281.Sh AUTHORS 282.An David O'Brien Aq deo@NUXI.org 283.Sh BUGS 284There are few hard and fast style rules here. 285The desire to express a logical grouping sometimes means not obeying some of the 286above. 287The style of many things is too dependent on the context of the whole makefile, 288or the lines surrounding it. 289