Copyediting. - bitreich-style - Style guide for programmers.
(HTM) 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
(HTM) 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.