style.Makefile.5 (08b9134350fd8435d5504d9cb2c8f3e83a3b1e3e) style.Makefile.5 (91c8d237228eaf3fac1b4ec4183a83e13bbc6e6b)
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.

--- 13 unchanged lines hidden (view full) ---

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.\"
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.

--- 13 unchanged lines hidden (view full) ---

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
30.Dd November 27, 2002
31.Dt STYLE.MAKEFILE 5
32.Os
33.Sh NAME
34.Nm style.Makefile
31.Dt STYLE.MAKEFILE 5
32.Os
33.Sh NAME
34.Nm style.Makefile
35.Nd
36.Fx
37.Pa Makefile
38file style guide
35.Nd "FreeBSD Makefile file style guide"
39.Sh DESCRIPTION
36.Sh DESCRIPTION
40This file specifies the preferred style for makefiles in the
37This file specifies the preferred style for Makefiles in the
41.Fx
42source tree.
38.Fx
39source tree.
43.Bl -bullet
40.Pp
41.Bl -bullet -compact
44.It
42.It
45All makefiles should have an SCM ID at the start of the file,
43All Makefiles should have an SCM ID at the start of the file,
46followed by a blank line.
47.Bd -literal
44followed by a blank line.
45.Bd -literal
48# $FreeBSD\&$
46# $FreeBSD$
49
50.Ed
51.It
47
48.Ed
49.It
52.Cm .PATH :
53comes next if needed, and is spelled
54.Dq Li ".PATH: " ,
55with a single
56.Tn ASCII
57space after a colon.
58Do not use the
59.Va VPATH
60variable.
50\&.PATH: comes next if needed, and is spelled
51.Pa ".PATH: <ascii space>"
61.It
52.It
62Special variables (i.e.,
63.Va LIB , SRCS , MLINKS ,
64etc.) are listed in order of
65.Dq product ,
53Special variables (i.e., LIB, SRCS, MLINKS, etc..) are listed in order
54of 'product',
66then building and installing a binary.
55then building and installing a binary.
67Special variables may also be listed in
68.Dq build
69order: i.e., ones for the primary program (or library) first.
70The general
71.Dq product
72order is:
73.Va PROG Ns / Ns Oo Va SH Oc Ns Va LIB Ns / Ns Va SCRIPTS
56The general order is:
57.Va PROG/LIB/SCRIPT
74.Va FILES
75.Va LINKS
58.Va FILES
59.Va LINKS
76.Oo Va NO_ Oc Ns Va MAN
77.Va MLINKS
60.Va [NO]MAN
61.Va MLINK
78.Va INCS
62.Va INCS
79.Va SRCS
63.Va SRC
80.Va WARNS
81.Va CFLAGS
82.Va DPADD
64.Va WARNS
65.Va CFLAGS
66.Va DPADD
83.Va LDADD .
84The general
85.Dq build
86order 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
67.Va LDADD
93.Va INCS
94.Va FILES
95.Va LINKS
96.Oo Va NO_ Oc Ns Va MAN
97.Va MLINKS .
98.It
99Omit
68.It
69Omit
100.Va SRCS
70.Va SRC
101when using
71when using
102.In bsd.prog.mk
72.Pa bsd.prog.mk
103and there is a single source file named the same as the
104.Va PROG .
105.It
106Omit
107.Va MAN
108when using
73and there is a single source file named the same as the
74.Va PROG .
75.It
76Omit
77.Va MAN
78when using
109.In bsd.prog.mk
110and the manual page is named the same as the
111.Va PROG ,
79.Pa bsd.prog.mk
80and the man page is named the same as the
81.Va PROG
112and is in section 1.
113.It
82and is in section 1.
83.It
114All variable assignments are spelled
115.Dq Va VAR Ns Ic = ,
116i.e., no space between the variable name and the
117.Ic = .
84All variable assignment is spelled
85.Pa "VAR=" ,
86i.e. no space between the variable name and the
87.Pa "=" .
118Keep values sorted alphabetically, if possible.
119.It
88Keep values sorted alphabetically, if possible.
89.It
120Do not use
121.Ic +=
90Don't use
91.Pa "+="
122to set variables that are only set once
123(or to set variables for the first time).
124.It
92to set variables that are only set once
93(or to set variables for the first time).
94.It
125Do not use vertical whitespace in simple makefiles,
95Don't 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.
96but do use it to group locally related things in more complex/longer ones.
97.It
98.Va WARNS
99comes before
100.Va CFLAGS ,
101as it is basically a
102.Va CFLAGS
103modifier.
104It comes before
105.Va CFLAGS
106rather than after
107.Va CFLAGS
108so it does not get lost in a sea of
109.Va CFLAGS
110statements as
111.Va WARNS
112is 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
113.It
150.Dq Li "NO_WERROR= yes"
151should not be used,
152it defeats the purpose of
114Unconditional
115.Pa "NO_WERROR=yes"
116should not be used.
117It defeats the purpose of
153.Va WARNS .
118.Va WARNS .
154It should only be used on the command line and in special circumstances.
155.It
156.Va CFLAGS
157is spelled
119.It
120.Va CFLAGS
121is spelled
158.Dq Li "CFLAGS+= " .
122.Pa "CFLAGS+=<ascii space>" .
159.It
123.It
160Listing
161.Fl D Ns 's
162before
163.Fl I Ns 's
164in
124Listing -D's before -I's in
165.Va CFLAGS
125.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.
126is preferred for alphabetical ordering and to make -D's easier to see.
127The -D's often affect conditional compilation,
128and -I's tend to be quite long.
181.It
129.It
182Do not use GCCisms (such as
183.Fl g
184and
185.Fl Wall )
186in
130Don't use GCC'isms (such as -g and -Wall) in
187.Va CFLAGS .
188.It
131.Va CFLAGS .
132.It
189Typically, there is one
190.Tn ASCII
191tab between
192.Va VAR Ns Ic =
133Typically there is one <ascii tab> between
134.Pa "VAR="
193and the value in order to start the value in column 9.
135and 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.
136An <ascii space> is allowed for VAR names that extend beyond column 9.
137A lack of whitespace also is allowed for very long VAR names.
138.Bd -literal
198.It
139.It
199.Ic .include In bsd.*.mk
140".include <bsd.*.mk>"
200goes last.
141goes 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
142.El
143.Ed
236.Pp
237The desire to express a logical grouping often means not obeying some of the
238above.
144.Pp
145The desire to express a logical grouping often means not obeying some of the
146above.
239.Sh EXAMPLES
240The simplest program
241.Pa Makefile
242is:
243.Bd -literal -offset indent
244# $FreeBSD\&$
147.Pp
148The simplist program Makefile is:
149.Bd -literal
150# $FreeBSD$
245
246PROG= foo
247
248\&.include <bsd.prog.mk>
151
152PROG= foo
153
154\&.include <bsd.prog.mk>
249.Ed
250.Pp
155.Pp
251The simplest library
252.Pa Makefile
253is:
254.Bd -literal -offset indent
255# $FreeBSD\&$
156The simplist library Makefile is:
157.Bd -literal
158# $FreeBSD$
256
257LIB= foo
258SHLIB_MAJOR= 1
259MAN= libfoo.3
260SRCS= foo.c
261
262\&.include <bsd.lib.mk>
159
160LIB= foo
161SHLIB_MAJOR= 1
162MAN= libfoo.3
163SRCS= foo.c
164
165\&.include <bsd.lib.mk>
263.Ed
166.Pp
264.Sh SEE ALSO
167.Sh SEE ALSO
265.Xr make 1 ,
266.Xr make.conf 5 ,
168.Xr make 1
267.Xr style 9
268.Sh HISTORY
169.Xr style 9
170.Sh HISTORY
269This manual page is inspired from the same source as
171This man page is inspired from the same source as
270.Xr style 9
172.Xr style 9
271manual page in
173man page in
272.Fx .
273.Sh BUGS
274There are few hard and fast style rules here.
174.Fx .
175.Sh BUGS
176There are few hard and fast style rules here.
275The style of many things is too dependent on the context of the whole makefile,
177The style of many things are too dependent on the context of the whole Makefile,
276or the lines surrounding it.
178or the lines surrounding it.