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