Date: Fri, 28 Feb 2003 19:05:48 +0200 From: Ruslan Ermilov <ru@freebsd.org> To: "David E. O'Brien" <obrien@freebsd.org> Cc: Bruce Evans <bde@freebsd.org>, src-committers@freebsd.org, cvs-src@freebsd.org, cvs-all@freebsd.org Subject: Re: cvs commit: src/share/man/man5 Makefile style.Makefile.5 Message-ID: <20030228170548.GA60899@sunbay.com> In-Reply-To: <200302262043.h1QKhlN4009440@repoman.freebsd.org> References: <200302262043.h1QKhlN4009440@repoman.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
--vGgW1X5XWziG23Ko Content-Type: multipart/mixed; boundary="5mCyUwZo2JvN/JJP" Content-Disposition: inline --5mCyUwZo2JvN/JJP Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Wed, Feb 26, 2003 at 12:43:47PM -0800, David E. O'Brien wrote: > obrien 2003/02/26 12:43:47 PST >=20 > Modified files: > share/man/man5 Makefile=20 > Added files: > share/man/man5 style.Makefile.5=20 > Log: > FreeBSD Makefile style guide. > =20 > Approved by: TRB > =20 > Revision Changes Path > 1.48 +1 -1 src/share/man/man5/Makefile > 1.1 +178 -0 src/share/man/man5/style.Makefile.5 (new) >=20 I seem to have missed a copy for review too. A post-commit review, part #1, is attached. --=20 Ruslan Ermilov Sysadmin and DBA, ru@sunbay.com Sunbay Software AG, ru@FreeBSD.org FreeBSD committer, +380.652.512.251 Simferopol, Ukraine http://www.FreeBSD.org The Power To Serve http://www.oracle.com Enabling The Information Age --5mCyUwZo2JvN/JJP Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename=p Content-Transfer-Encoding: quoted-printable Index: style.Makefile.5 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D RCS file: /home/ncvs/src/share/man/man5/style.Makefile.5,v retrieving revision 1.1 diff -u -p -r1.1 style.Makefile.5 --- style.Makefile.5 26 Feb 2003 20:43:47 -0000 1.1 +++ style.Makefile.5 28 Feb 2003 16:50:08 -0000 @@ -9,9 +9,6 @@ .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. -.\" 3. Neither the name of the author nor the names of any contributors -.\" may be used to endorse or promote products derived from this softwa= re -.\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE @@ -27,72 +24,80 @@ .\" .\" $FreeBSD: src/share/man/man5/style.Makefile.5,v 1.1 2003/02/26 20:43:4= 7 obrien Exp $ .\" -.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: src/share/man/man5/style.Makefile.5,v 1.1 2003/02/26 20:43:47 = obrien Exp $ +# $FreeBSD\&$ =20 .Ed .It -\&.PATH: comes next if needed, and is spelled -.Pa ".PATH: <ascii space>" -.It -Special variables (i.e., LIB, SRCS, MLINKS, etc..) are listed in order -of 'product', +.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., +.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=3D" , -i.e. no space between the variable name and the -.Pa "=3D" . +All variable assignments are spelled +.Dq Va VAR Ns Ic =3D , +i.e., no space between the variable name and the +.Ic =3D . Keep values sorted alphabetically, if possible. .It -Don't use -.Pa "+=3D" +Do not use +.Ic +=3D 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 +117,71 @@ statements as is an important thing. .It Unconditional -.Pa "NO_WERROR=3Dyes" -should not be used. -It defeats the purpose of +.Dq Li "NO_WERROR=3D yes" +should not be used, +it defeats the purpose of .Va WARNS . .It .Va CFLAGS is spelled -.Pa "CFLAGS+=3D<ascii space>" . +.Dq Li "CFLAGS+=3D " . .It -Listing -D's before -I'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. -.It -Don't use GCC'isms (such as -g and -Wall) in +Listing +.Fl D Ns 's +before +.Fl I Ns 's +in +.Va CFLAGS +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 +Do not use GCCisms (such as +.Fl g +and +.Fl Wall ) +in .Va CFLAGS . .It -Typically there is one <ascii tab> between -.Pa "VAR=3D" +Typically, there is one +.Tn ASCII +tab between +.Va VAR Ns Ic =3D 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 t= he above. -.Pp -The simplist program Makefile is: -.Bd -literal -# $FreeBSD: src/share/man/man5/style.Makefile.5,v 1.1 2003/02/26 20:43:47 = obrien Exp $ +.Sh EXAMPLE +The simplest program +.Pa Makefile +is: +.Bd -literal -offset indent +# $FreeBSD\&$ =20 PROG=3D foo =20 \&.include <bsd.prog.mk> +.Ed .Pp -The simplist library Makefile is: -.Bd -literal -# $FreeBSD: src/share/man/man5/style.Makefile.5,v 1.1 2003/02/26 20:43:47 = obrien Exp $ +The simplest library +.Pa Makefile +is: +.Bd -literal -offset indent +# $FreeBSD\&$ =20 LIB=3D foo SHLIB_MAJOR=3D 1 @@ -163,16 +189,16 @@ MAN=3D libfoo.3 SRCS=3D foo.c =20 \&.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 Mak= efile, +The style of many things is too dependent on the context of the whole make= file, or the lines surrounding it. --5mCyUwZo2JvN/JJP-- --vGgW1X5XWziG23Ko Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.1 (FreeBSD) iD8DBQE+X5brUkv4P6juNwoRAiEsAJwOtsV87elVmUqsmpkNfx3pPQTEgwCfYtwI pY2RZ7FvQJl5g1OBbjrYSi0= =ff9C -----END PGP SIGNATURE----- --vGgW1X5XWziG23Ko-- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe cvs-src" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20030228170548.GA60899>