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