share/man/man5/style.Makefile.5

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