1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
<table class="head">
<tr>
<td class="head-ltitle">STYLE.MAKEFILE(5)</td>
<td class="head-vol">File Formats Manual</td>
<td class="head-rtitle">STYLE.MAKEFILE(5)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">style.Makefile</code> —
<span class="Nd">FreeBSD Makefile style guide</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">This file specifies the preferred style for makefiles in the
<span class="Ux">FreeBSD</span> source tree.</p>
<ul class="Bl-bullet">
<li id=".PATH"><a class="permalink" href="#.PATH"><code class="Cm">.PATH</code></a>:
comes first if needed, and is spelled “<code class="Li">.PATH:
</code>”, with a single ASCII space after a colon. Do not use the
<var class="Va">VPATH</var> variable.</li>
<li>Special variables (i.e., <var class="Va">LIB</var>,
<var class="Va">SRCS</var>, <var class="Va">MLINKS</var>, etc.) are listed
in order of “product”, then building and installing a
binary. Special variables may also be listed in “build”
order: i.e., ones for the primary program (or library) first. The general
“product” order is:
<var class="Va">PROG</var>/[<var class="Va">SH</var>]<var class="Va">LIB</var>/<var class="Va">SCRIPTS</var>
<var class="Va">FILES</var> <var class="Va">LINKS</var>
<var class="Va">MAN</var> <var class="Va">MLINKS</var>
<var class="Va">INCS</var> <var class="Va">SRCS</var>
<var class="Va">WARNS</var> <var class="Va">CSTD</var>
<var class="Va">CFLAGS</var> <var class="Va">DPADD</var>
<var class="Va">LDADD</var>. The general “build” order is:
<var class="Va">PROG</var>/[<var class="Va">SH</var>]<var class="Va">LIB</var>/<var class="Va">SCRIPTS</var>
<var class="Va">SRCS</var> <var class="Va">WARNS</var>
<var class="Va">CSTD</var> <var class="Va">CFLAGS</var>
<var class="Va">DPADD</var> <var class="Va">LDADD</var>
<var class="Va">INCS</var> <var class="Va">FILES</var>
<var class="Va">LINKS</var> <var class="Va">MAN</var>
<var class="Va">MLINKS</var>.</li>
<li>Omit <var class="Va">SRCS</var> when using
<code class="In"><<a class="In">bsd.prog.mk</a>></code> and there is
a single source file named the same as the
<var class="Va">PROG</var>.</li>
<li>Omit <var class="Va">MAN</var> when using
<code class="In"><<a class="In">bsd.prog.mk</a>></code> and the
manual page is named the same as the <var class="Va">PROG</var>, and is in
section 1.</li>
<li>All variable assignments are spelled
“<var class="Va">VAR</var><code class="Ic">=</code>”, i.e.,
no space between the variable name and the <code class="Ic">=</code>. Keep
values sorted alphabetically, if possible.</li>
<li id="__">Variables are expanded with
<a class="permalink" href="#__"><b class="Sy">{}</b></a>, not
<a class="permalink" href="#()"><b class="Sy" id="()">()</b></a>. Such as
<var class="Va">${VARIABLE}</var>.</li>
<li>Do not use <code class="Ic">+=</code> to set variables that are only set
once (or to set variables for the first time).</li>
<li>Do not use vertical whitespace in simple makefiles, but do use it to group
locally related things in more complex/longer ones.</li>
<li id="WARNS"><var class="Va">WARNS</var> comes before
<var class="Va">CFLAGS</var>, as it is basically a
<var class="Va">CFLAGS</var> modifier. It comes before
<var class="Va">CFLAGS</var> rather than after
<var class="Va">CFLAGS</var> so it does not get lost in a sea of
<var class="Va">CFLAGS</var> statements as <var class="Va">WARNS</var> is
an important thing. The usage of <var class="Va">WARNS</var> is spelled
“<code class="Li">WARNS?= </code>”, so that it may be
overridden on the command line or in <a class="Xr">make.conf(5)</a>.</li>
<li>“<code class="Li">MK_WERROR=no</code>” should not be used,
it defeats the purpose of <var class="Va">WARNS</var>. It should only be
used on the command line and in special circumstances.</li>
<li id="CFLAGS"><var class="Va">CFLAGS</var> is spelled
“<code class="Li">CFLAGS+= </code>”.</li>
<li>Listing <code class="Fl">-D</code>'s before <code class="Fl">-I</code>'s
in <var class="Va">CFLAGS</var> is preferred for alphabetical ordering and
to make <code class="Fl">-D</code>'s easier to see. The
<code class="Fl">-D</code>'s often affect conditional compilation, and
<code class="Fl">-I</code>'s tend to be quite long. Split long
<var class="Va">CFLAGS</var> settings between the
<code class="Fl">-D</code>'s and <code class="Fl">-I</code>'s.</li>
<li>Lists that span more than one line should be formatted as follows:
<div class="Bd Pp Bd-indent Li">
<pre>SRCS+=<SP>\
<TAB>main.c<SP>\
<TAB>trace.c<SP>\
<TAB>zoo.c \
</pre>
</div>
Specifically, the last item in the list should have a trailing '\'. This is
to avoid causing a "false diff" or "false blame" when
a new item is appended at the end. In general the list should be English
language alphabetized. A list of libraries or header inclusion paths are
notable exceptions if needed for proper building.</li>
<li>Do not use GCCisms (such as <code class="Fl">-g</code> and
<code class="Fl">-Wall</code>) in <var class="Va">CFLAGS</var>.</li>
<li>Typically, there is one ASCII tab between
<var class="Va">VAR</var><code class="Ic">=</code> and the value in order
to start the value in column 9. An ASCII space is allowed for variable
names that extend beyond column 9. A lack of whitespace is also allowed
for very long variable names.</li>
<li id=".include"><a class="permalink" href="#.include"><code class="Ic">.include</code></a>
<code class="In"><<a class="In">bsd.*.mk</a>></code> goes last.</li>
<li>Do not use anachronisms like <var class="Va">$<</var> and
<var class="Va">$@</var>. Instead use <var class="Va">${.IMPSRC}</var> or
<var class="Va">${.ALLSRC}</var> and
<var class="Va">${.TARGET}</var>.</li>
<li>To not build the “foo” part of the base system, use
<var class="Va">NO_FOO</var>, not <var class="Va">NOFOO</var>.</li>
<li>To optionally build something in the base system, spell the knob
<var class="Va">WITH_FOO</var> not <var class="Va">WANT_FOO</var> or
<var class="Va">USE_FOO</var>. The latter are reserved for the
<span class="Ux">FreeBSD</span> Ports Collection.</li>
<li id="defined">For variables that are only checked with
<a class="permalink" href="#defined"><code class="Fn">defined</code></a>(),
do not provide any fake value.</li>
</ul>
</section>
<section class="Sh">
<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
<p class="Pp">The simplest program <span class="Pa">Makefile</span> is:</p>
<div class="Bd Pp Bd-indent Li">
<pre>PROG= foo
.include <bsd.prog.mk></pre>
</div>
<p class="Pp">The simplest library <span class="Pa">Makefile</span> is:</p>
<div class="Bd Pp Bd-indent Li">
<pre>LIB= foo
SHLIB_MAJOR= 1
MAN= libfoo.3
SRCS= foo.c
.include <bsd.lib.mk></pre>
</div>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">make(1)</a>, <a class="Xr">make.conf(5)</a>,
<a class="Xr">style(9)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">This manual page is inspired from the <a class="Xr">style(9)</a>
manual page and first appeared in <span class="Ux">FreeBSD 5.1</span>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp"><span class="An">David O'Brien</span>
⟨deo@NUXI.org⟩</p>
</section>
<section class="Sh">
<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1>
<p class="Pp">There are few hard and fast style rules here. The desire to
express a logical grouping sometimes means not obeying some of the above.
The style of many things is too dependent on the context of the whole
makefile, or the lines surrounding it.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">October 29, 2025</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
