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: stable/12/share/man/man5/style.Makefile.5 371111 2021-11-28 16:47:03Z 0mp $
29.\"
30.Dd November 18, 2021
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
45.Cm .PATH :
46comes next if needed, and is spelled
47.Dq Li ".PATH: " ,
48with a single
49.Tn ASCII
50space after a colon.
51Do not use the
52.Va VPATH
53variable.
54.It
55Special variables (i.e.,
56.Va LIB , SRCS , MLINKS ,
57etc.) are listed in order of
58.Dq product ,
59then building and installing a binary.
60Special variables may also be listed in
61.Dq build
62order: i.e., ones for the primary program (or library) first.
63The general
64.Dq product
65order is:
66.Va PROG Ns / Ns Oo Va SH Oc Ns Va LIB Ns / Ns Va SCRIPTS
67.Va FILES
68.Va LINKS
69.Oo Va NO_ Oc Ns Va MAN
70.Va MLINKS
71.Va INCS
72.Va SRCS
73.Va WARNS
74.Va CFLAGS
75.Va DPADD
76.Va LDADD .
77The general
78.Dq build
79order is:
80.Va PROG Ns / Ns Oo Va SH Oc Ns Va LIB Ns / Ns Va SCRIPTS
81.Va SRCS
82.Va WARNS
83.Va CFLAGS
84.Va DPADD
85.Va LDADD
86.Va INCS
87.Va FILES
88.Va LINKS
89.Oo Va NO_ Oc Ns 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 "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 make.conf 5 ,
267.Xr style 9
268.Sh HISTORY
269This manual page is inspired from the same source as
270.Xr style 9
271manual page in
272.Fx .
273.Sh BUGS
274There are few hard and fast style rules here.
275The style of many things is too dependent on the context of the whole makefile,
276or the lines surrounding it.
277