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 January 8, 2005 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 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.Pa /etc/make.conf . 149.It 150.Dq Li "NO_WERROR= yes" 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 244# $FreeBSD\&$ 245 246PROG= foo 247 248\&.include <bsd.prog.mk> 249.Ed 250.Pp 251The simplest library 252.Pa Makefile 253is: 254.Bd -literal -offset indent 255# $FreeBSD\&$ 256 257LIB= foo 258SHLIB_MAJOR= 1 259MAN= libfoo.3 260SRCS= foo.c 261 262\&.include <bsd.lib.mk> 263.Ed 264.Sh SEE ALSO 265.Xr make 1 , 266.Xr style 9 267.Sh HISTORY 268This manual page is inspired from the same source as 269.Xr style 9 270manual page in 271.Fx . 272.Sh BUGS 273There are few hard and fast style rules here. 274The style of many things is too dependent on the context of the whole makefile, 275or the lines surrounding it. 276