diff options
author | obrien <obrien@FreeBSD.org> | 2003-03-02 02:21:37 +0000 |
---|---|---|
committer | obrien <obrien@FreeBSD.org> | 2003-03-02 02:21:37 +0000 |
commit | 812f230725b34156be713cde741e309c3a13561e (patch) | |
tree | 975a403df8b985d71e581adac2edcd39db4e2cf0 | |
parent | af2849b505125bd246931a01ac1ea4b3c435c334 (diff) | |
download | FreeBSD-src-812f230725b34156be713cde741e309c3a13561e.zip FreeBSD-src-812f230725b34156be713cde741e309c3a13561e.tar.gz |
Mdoc police.
Submitted by: ru
-rw-r--r-- | share/man/man5/style.Makefile.5 | 141 |
1 files changed, 85 insertions, 56 deletions
diff --git a/share/man/man5/style.Makefile.5 b/share/man/man5/style.Makefile.5 index aa48513..47e5305 100644 --- a/share/man/man5/style.Makefile.5 +++ b/share/man/man5/style.Makefile.5 @@ -27,72 +27,80 @@ .\" .\" $FreeBSD$ .\" -.Dd November 27, 2002 +.Dd February 28, 2003 .Dt STYLE.MAKEFILE 5 .Os .Sh NAME .Nm style.Makefile -.Nd "FreeBSD Makefile file style guide" +.Nd +.Fx +.Pa Makefile +file style guide .Sh DESCRIPTION -This file specifies the preferred style for Makefiles in the +This file specifies the preferred style for makefiles in the .Fx source tree. -.Pp -.Bl -bullet -compact +.Bl -bullet .It -All Makefiles should have an SCM ID at the start of the file, +All makefiles should have an SCM ID at the start of the file, followed by a blank line. .Bd -literal -# $FreeBSD$ +# $FreeBSD\&$ .Ed .It -\&.PATH: comes next if needed, and is spelled -.Pa ".PATH: <ascii space>" +.Cm .PATH : +comes next if needed, and is spelled +.Dq Li ".PATH: " , +with a single +.Tn ASCII +space after a colon. .It -Special variables (i.e., LIB, SRCS, MLINKS, etc..) are listed in order -of 'product', +Special variables (i.e., +.Va LIB , SRCS , MLINKS , +etc.) are listed in order of +.Dq product , then building and installing a binary. The general order is: -.Va PROG/LIB/SCRIPT +.Va PROG Ns / Ns Va LIB Ns / Ns Va SCRIPT .Va FILES .Va LINKS -.Va [NO]MAN -.Va MLINK +.Oo Va NO Oc Ns Va MAN +.Va MLINKS .Va INCS -.Va SRC +.Va SRCS .Va WARNS .Va CFLAGS .Va DPADD -.Va LDADD +.Va LDADD . .It Omit -.Va SRC +.Va SRCS when using -.Pa bsd.prog.mk +.Aq Pa bsd.prog.mk and there is a single source file named the same as the .Va PROG . .It Omit .Va MAN when using -.Pa bsd.prog.mk -and the man page is named the same as the -.Va PROG +.Aq Pa bsd.prog.mk +and the manual page is named the same as the +.Va PROG , and is in section 1. .It -All variable assignment is spelled -.Pa "VAR=" , -i.e. no space between the variable name and the -.Pa "=" . +All variable assignments are spelled +.Dq Va VAR Ns Ic = , +i.e., no space between the variable name and the +.Ic = . Keep values sorted alphabetically, if possible. .It -Don't use -.Pa "+=" +Do not use +.Ic += to set variables that are only set once (or to set variables for the first time). .It -Don't use vertical whitespace in simple Makefiles, +Do not use vertical whitespace in simple makefiles, but do use it to group locally related things in more complex/longer ones. .It .Va WARNS @@ -112,50 +120,71 @@ statements as is an important thing. .It Unconditional -.Pa "NO_WERROR=yes" -should not be used. -It defeats the purpose of +.Dq Li "NO_WERROR= yes" +should not be used, +it defeats the purpose of .Va WARNS . .It .Va CFLAGS is spelled -.Pa "CFLAGS+=<ascii space>" . +.Dq Li "CFLAGS+= " . .It -Listing -D's before -I's in +Listing +.Fl D Ns 's +before +.Fl I Ns 's +in .Va CFLAGS -is preferred for alphabetical ordering and to make -D's easier to see. -The -D's often affect conditional compilation, -and -I's tend to be quite long. +is preferred for alphabetical ordering and to make +.Fl D Ns 's +easier to see. +The +.Fl D Ns 's +often affect conditional compilation, +and +.Fl I Ns 's +tend to be quite long. .It -Don't use GCC'isms (such as -g and -Wall) in +Do not use GCCisms (such as +.Fl g +and +.Fl Wall ) +in .Va CFLAGS . .It -Typically there is one <ascii tab> between -.Pa "VAR=" +Typically, there is one +.Tn ASCII +tab between +.Va VAR Ns Ic = and the value in order to start the value in column 9. -An <ascii space> is allowed for VAR names that extend beyond column 9. -A lack of whitespace also is allowed for very long VAR names. -.Bd -literal +An +.Tn ASCII +space is allowed for variable names that extend beyond column 9. +A lack of whitespace is also allowed for very long variable names. .It -".include <bsd.*.mk>" +.Ic .include Aq Pa bsd.*.mk goes last. .El -.Ed .Pp The desire to express a logical grouping often means not obeying some of the above. -.Pp -The simplist program Makefile is: -.Bd -literal -# $FreeBSD$ +.Sh EXAMPLE +The simplest program +.Pa Makefile +is: +.Bd -literal -offset indent +# $FreeBSD\&$ PROG= foo \&.include <bsd.prog.mk> +.Ed .Pp -The simplist library Makefile is: -.Bd -literal -# $FreeBSD$ +The simplest library +.Pa Makefile +is: +.Bd -literal -offset indent +# $FreeBSD\&$ LIB= foo SHLIB_MAJOR= 1 @@ -163,16 +192,16 @@ MAN= libfoo.3 SRCS= foo.c \&.include <bsd.lib.mk> -.Pp +.Ed .Sh SEE ALSO -.Xr make 1 +.Xr make 1 , .Xr style 9 .Sh HISTORY -This man page is inspired from the same source as +This manual page is inspired from the same source as .Xr style 9 -man page in +manual page in .Fx . .Sh BUGS There are few hard and fast style rules here. -The style of many things are too dependent on the context of the whole Makefile, +The style of many things is too dependent on the context of the whole makefile, or the lines surrounding it. |