Minor improvements to grammar and formatting - 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 4630281bedde87837f7c5ae63ffd10483a9d206e DIR parent 60d0637f5edd99ec9ee1175d37a3f7b03db3d318 HTML Author: Anders Damsgaard <anders@adamsgaard.dk> Date: Wed, 10 Jun 2020 15:26:27 +0200 Minor improvements to grammar and formatting Diffstat: M c/makefile-guideline.txt | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) --- DIR diff --git a/c/makefile-guideline.txt b/c/makefile-guideline.txt @@ -19,7 +19,7 @@ The following targets should be defined in the Makefile: * all or the "default": build the project. * clean: clean files used by compilation, such as: object files, compiled binaries. -* install: install the build project. +* install: install the built project. * uninstall (optional): uninstall the project. * dist (optional): create a source tarball of the project intended as redistribution for source packages. @@ -33,7 +33,7 @@ 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 -Trying to place yourself into the shoes of a package maintainer / porter. This +Try to place yourself into the shoes of a package maintainer / porter. This is helpful to make sure the package is easy to maintain: * https://www.openbsd.org/faq/ports/ @@ -47,12 +47,12 @@ Variables It is recommended to respect the following commonly-used variables. -* $DESTDIR: for the install targets make use of the $DESTDIR variable. This - make it simpler to install the package to an other location and make binary +* $DESTDIR: make use of the $DESTDIR variable for the install targets. This + makes it simpler to install the package to another location and make binary packages. It is the prefix destination directory to install to (before $PREFIX). It should be unset by default. -* $PREFIX: this specifies the prefix location to install to, it should be +* $PREFIX: this variable specifies the prefix location to install to, it should be "/usr/local" by default since this is most commonly used for ports. * $MANPREFIX or $MANDIR: @@ -63,7 +63,6 @@ Specifying compiler and linker flags: * $CC, $CFLAGS, $LDFLAGS, $CPPFLAGS: make sure to respect the default set flags as specified in POSIX: - https://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html under the section "Default rules". This make it easier for the ports build system to use the set variables and not having to patch the Makefile in some way. @@ -88,13 +87,13 @@ Considerations example to make output look nicer aligned). The verbose output is very useful for debugging and suppressing it only adds debugging abstractions. -* Try to use a single-file Makefile for atleast small projects. If needed some +* Try to use a single-file Makefile, at least for small projects. If needed some configuration could be included from the Makefile: config.mk. Keep in mind - reducing abstractions will increase readability and debugability. Package + that reducing abstractions will increase readability and debugability. Package maintainers/porters do not want to have to relearn a new system for each software package. -* As specified above different systems can use different locations for certain +* As specified above, different systems can use different locations for certain things like man pages, X11 header files and libraries and ports installation. Examples: @@ -107,8 +106,8 @@ Testing on many different systems is useful! For example: Linux, OpenBSD, NetBSD Examples -------- -Below is an example of a project json2tsv Makefile. It is line-numbered and -below are some added remarks why things are done the way they are. +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. 1 .POSIX: @@ -218,8 +217,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 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 mkdir the -p flag is used to create all intermediary directories and to not return an error if the directory already exists.