Copyediting. - bitreich-style - Style guide for programmers. HTML git clone git://bitreich.org/bitreich-style DIR Log DIR Files DIR Refs DIR Tags DIR README DIR LICENSE --- DIR commit 9b48be81f3efe169f41975d6202ec4ed0651895c DIR parent 4630281bedde87837f7c5ae63ffd10483a9d206e HTML Author: Benjamin Neumann <btdn@lab-btdn.com> Date: Wed, 10 Jun 2020 09:11:05 -0500 Copyediting. Diffstat: M c/makefile-guideline.txt | 43 ++++++++++++++++--------------- 1 file changed, 22 insertions(+), 21 deletions(-) --- DIR diff --git a/c/makefile-guideline.txt b/c/makefile-guideline.txt @@ -1,14 +1,14 @@ -Title: Guidelins for writing simple portable Makefiles +Title: Guidelines for writing simple portable Makefiles -This page describes some guidelines and good practises for writing simple -portable POSIX Makefiles. It assumes a basic level of understanding in writing -Makefiles already. It will focus on projects that use the C programming +This page describes some guidelines and good practices for writing simple, +portable POSIX Makefiles. It assumes a basic level of understanding in +writing Makefiles and focuses on projects that use the C programming language. -make is used because it has been around for a long time, it is available on -many systems, it is a POSIX standard and it has proven to work well for most -projects. +make is used because it has been around for a long time, is available +on many systems, is a POSIX standard and has been proven to work well +for most projects. Targets @@ -29,12 +29,13 @@ The following targets should be defined in the Makefile: Portability ----------- -Do not use GNUisms in Makefiles. Testing with different make implementations -like BSD make which mostly respect POSIX is very useful. Use POSIX Makefile -rules: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html +Do not use GNUisms in Makefiles. Testing with different make +implementations, such as BSD make, which mostly respects POSIX, is very +useful. Use POSIX Makefile rules: +https://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html -Try to place yourself into the shoes of a package maintainer / porter. This -is helpful to make sure the package is easy to maintain: +Try to place yourself in the shoes of a package maintainer / porter. This +helps make sure that the package is easy to maintain: * https://www.openbsd.org/faq/ports/ * https://www.netbsd.org/docs/pkgsrc/ @@ -68,8 +69,8 @@ Specifying compiler and linker flags: the set variables and not having to patch the Makefile in some way. * $CFLAGS: do not hard-code optimization flags like (-O2) or diagnostic flags - such as -Wall, -Wextra, -pedantic. Of course do not specify unportable compiler - flags. + such as -Wall, -Wextra, -pedantic. Even more importantly, do not + specify unportable compiler flags. * $LDFLAGS: do not hard-code linker flags like -s (symbol stripping) or -g, -static or such flags. @@ -106,8 +107,9 @@ Testing on many different systems is useful! For example: Linux, OpenBSD, NetBSD Examples -------- -Below is an example of a Makefile from project json2tsv. It is line-numbered and -annotated with remarks on why things are done the way they are. +Below is an example of a Makefile from the json2tsv project. It is +line-numbered and annotated with remarks on why things are done the way +they are. 1 .POSIX: @@ -217,8 +219,8 @@ separately for cross-compiling. 48 cp -f ${MAN1} ${DOC} ${HDR} \ 49 ${SRC} ${LIBJSONSRC} Makefile "${NAME}-${VERSION}" -Use the -f (force) options for rm to make sure to not return an error in case -of failure. For cp it ensures to overwrite the file even if it is busy. For +Use the -f (force) options for rm ensures make does not return an error +on failure. For cp it ensures to overwrite the file even if it is busy. For mkdir the -p flag is used to create all intermediary directories and to not return an error if the directory already exists. @@ -242,8 +244,7 @@ Remove the binary, object files and the local archive library (.a) file. 59 mkdir -p "${DESTDIR}${PREFIX}/bin" 60 cp -f ${BIN} "${DESTDIR}${PREFIX}/bin" -For cp it ensures to overwrite the file even if it is installed already and -busy as a process. +cp's -f flag ensures overwriting the file even if it is busy. 61 for f in ${BIN}; do chmod 755 "${DESTDIR}${PREFIX}/bin/$$f"; done 62 # installing example files. @@ -255,7 +256,7 @@ busy as a process. 68 for m in ${MAN1}; do chmod 644 "${DESTDIR}${MANPREFIX}/man1/$$m"; done 69 -Explicitly sets permissions for executable files and for documentation. +Explicitly set permissions for executable files and for documentation. 70 uninstall: 71 # removing executable files.