style.makefile(5)
NAME
style.Makefile - FreeBSD Makefile file style guide
DESCRIPTION
- This file specifies the preferred style for makefiles in the
- FreeBSD
source tree. - +o All makefiles should have an SCM ID at the start of the
- file, fol
- lowed by a blank line.
- # $FreeBSD$
- +o .PATH: comes next if needed, and is spelled ``.PATH: '',
- with a sin
- gle ASCII space after a colon. Do not use the VPATH
- variable.
- +o Special variables (i.e., LIB, SRCS, MLINKS, 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 ``prod
- uct'' order is:
PROG/[SH]LIB/SCRIPTS FILES LINKS [NO_]MAN MLINKS INCS - SRCS WARNS
CFLAGS DPADD LDADD. The general ``build'' order is: PROG/[SH]LIB/SCRIPTS SRCS WARNS CFLAGS DPADD LDADD INCS - FILES LINKS
[NO_]MAN MLINKS. - +o Omit SRCS when using #include <bsd.prog.mk>
- and there is a single source file named the same as the
- PROG.
- +o Omit MAN when using #include <bsd.prog.mk>
- and the manual page is named the same as the PROG, and
- is in section
1. - +o All variable assignments are spelled ``VAR='', i.e., no
- space between
- the variable name and the =. Keep values sorted alpha
- betically, if
possible. - +o Do not use += to set variables that are only set once
- (or to set
- variables for the first time).
- +o Do not use vertical whitespace in simple makefiles, but
- do use it to
- group locally related things in more complex/longer
- ones.
- +o WARNS comes before CFLAGS, as it is basically a CFLAGS
- modifier. It
- comes before CFLAGS rather than after CFLAGS so it does
- not get lost
in a sea of CFLAGS statements as WARNS is an important - thing. The
usage of WARNS is spelled ``WARNS?= '', so that it may - be overridden
on the command line or in make.conf(5). - +o ``NO_WERROR= yes'' should not be used, it defeats the
- purpose of
- WARNS. It should only be used on the command line and
- in special
circumstances. - +o CFLAGS is spelled ``CFLAGS+= ''.
- +o Listing -D's before -I's in CFLAGS is preferred for al
- phabetical
- ordering and to make -D's easier to see. The -D's often
- affect conditional compilation, and -I's tend to be quite long.
- Split long
CFLAGS settings between the -D's and -I's. - +o Do not use GCCisms (such as -g and -Wall) in CFLAGS.
- +o Typically, there is one ASCII tab between VAR= and the
- value in order
- to start the value in column 9. An ASCII space is al
- lowed for variable names that extend beyond column 9. A lack of
- whitespace is also
allowed for very long variable names. - +o .include goes last.
- +o Do not use anachronisms like $< and $@. Instead use
- ${.IMPSRC} or
- ${.ALLSRC} and ${.TARGET}.
- +o To not build the ``foo'' part of the base system, use
- NO_FOO, not
- NOFOO.
- +o To optionally build something in the base system, spell
- the knob
- WITH_FOO not WANT_FOO or USE_FOO. The latter are re
- served for the
FreeBSD Ports Collection. - +o For variables that are only checked with defined(), do
- not provide
- any fake value.
- The desire to express a logical grouping often means not
- obeying some of
the above.
EXAMPLES
- The simplest program Makefile is:
- # $FreeBSD$
- PROG= foo
- .include <bsd.prog.mk>
- The simplest library Makefile is:
# $FreeBSD$- LIB= foo
SHLIB_MAJOR= 1
MAN= libfoo.3
SRCS= foo.c - .include <bsd.lib.mk>
SEE ALSO
make(1), make.conf(5), style(9)
HISTORY
- This manual page is inspired from the same source as
- style(9) manual page
in FreeBSD.
BUGS
- There are few hard and fast style rules here. The style of
- many things
is too dependent on the context of the whole makefile, or - the lines surrounding it.
- BSD January 8, 2005