ienglish_knight - english_knight - A ninja replacement.	Err	bitreich.org	70
hgit clone git://bitreich.org/english_knight git://enlrupgkhuxnvlhsf6lc3fziv5h2hhfrinws65d7roiv6bfj7d652fid.onion/english_knight	URL:git://bitreich.org/english_knight git://enlrupgkhuxnvlhsf6lc3fziv5h2hhfrinws65d7roiv6bfj7d652fid.onion/english_knight	bitreich.org	70
1Log	/scm/english_knight/log.gph	bitreich.org	70
1Files	/scm/english_knight/files.gph	bitreich.org	70
1Refs	/scm/english_knight/refs.gph	bitreich.org	70
1Tags	/scm/english_knight/tag	bitreich.org	70
1README	/scm/english_knight/file/README.md.gph	bitreich.org	70
1LICENSE	/scm/english_knight/file/LICENSE.gph	bitreich.org	70
i---	Err	bitreich.org	70
ienglish_knight (10124B)	Err	bitreich.org	70
i---	Err	bitreich.org	70
i     1 #!/bin/sh	Err	bitreich.org	70
i     2 	Err	bitreich.org	70
i     3 if [ -f Makefile -o -f makefile -o -f GNUmakefile ];	Err	bitreich.org	70
i     4 then	Err	bitreich.org	70
i     5         make "$@"	Err	bitreich.org	70
i     6         exit $?	Err	bitreich.org	70
i     7 fi	Err	bitreich.org	70
i     8 	Err	bitreich.org	70
i     9 cat <<EOF	Err	bitreich.org	70
i    10 #[1]Seninha's notes	Err	bitreich.org	70
i    11 	Err	bitreich.org	70
i    12                   A Template for Portable Idiomatic Makefiles	Err	bitreich.org	70
i    13 	Err	bitreich.org	70
i    14 [2]seninha.org	Err	bitreich.org	70
i    15 2022-04-07	Err	bitreich.org	70
i    16 	Err	bitreich.org	70
i    17 In this post, I present the template I use to write portable, idiomatic	Err	bitreich.org	70
i    18 Makefiles for building C programs.	Err	bitreich.org	70
i    19 	Err	bitreich.org	70
i    20 I use ${MYVAR}, with curly braces, rather than $(MYVAR), with parentheses, but	Err	bitreich.org	70
i    21 both notations are supported. In this document I identify two different people:	Err	bitreich.org	70
i    22 the developer or Makefile author, who writes the Makefile; and the user or	Err	bitreich.org	70
i    23 package maintainer, who defines the proper variables and run make(1).	Err	bitreich.org	70
i    24 	Err	bitreich.org	70
i    25 The Project Files	Err	bitreich.org	70
i    26 	Err	bitreich.org	70
i    27 There are several files involved in the building process: the target files to be	Err	bitreich.org	70
i    28 built, the source files, and the intermediate files. They may be referenced	Err	bitreich.org	70
i    29 several times by different rules, so it is a good practice to name them with	Err	bitreich.org	70
i    30 variables. Suppose we're building a program called myprog composed of three	Err	bitreich.org	70
i    31 modules. These are the variables to be defined:	Err	bitreich.org	70
i    32 PROG = myprog	Err	bitreich.org	70
i    33 SRCS = main.c parse.c util.c	Err	bitreich.org	70
i    34 OBJS = main.o parse.o util.o	Err	bitreich.org	70
i    35 	Err	bitreich.org	70
i    36 The varialbe PROG is the final file; SRCS lists the source files; and OBJS lists	Err	bitreich.org	70
i    37 the intermediate, object files. Note that both the list of source files and of	Err	bitreich.org	70
i    38 object files are almost equal, differing only by the extension of the files.	Err	bitreich.org	70
i    39 POSIX make(1) has a notation for changing the ending of each word in a variable.	Err	bitreich.org	70
i    40 In order to avoid repeating ourselves, we can use this notation to define	Err	bitreich.org	70
i    41 ${OBJS}.	Err	bitreich.org	70
i    42 PROG = myprog	Err	bitreich.org	70
i    43 SRCS = main.c parse.c util.c	Err	bitreich.org	70
i    44 OBJS = ${SRCS:.c=.o}	Err	bitreich.org	70
i    45 	Err	bitreich.org	70
i    46 We want to build our program when we call make without any arguments. To do	Err	bitreich.org	70
i    47 this, the first target should be ${PROG} itself. However, it is a common	Err	bitreich.org	70
i    48 practice to use the target all to build the final files. So the first target is	Err	bitreich.org	70
i    49 all, which just has ${PROG} as prerequisite.	Err	bitreich.org	70
i    50 all: ${PROG}	Err	bitreich.org	70
i    51 	Err	bitreich.org	70
i    52 Next we need to declare the dependencies between the program modules. This is	Err	bitreich.org	70
i    53 done with rules without commands.	Err	bitreich.org	70
i    54 main.o: parse.h util.h	Err	bitreich.org	70
i    55 parse.o: parse.h util.h	Err	bitreich.org	70
i    56 util.o: util.h	Err	bitreich.org	70
i    57 	Err	bitreich.org	70
i    58 The Compilation Rules	Err	bitreich.org	70
i    59 	Err	bitreich.org	70
i    60 The compilation process is split in two parts: generate the object files from	Err	bitreich.org	70
i    61 the source files, and generate the program from the object files. So we need two	Err	bitreich.org	70
i    62 rules.	Err	bitreich.org	70
i    63 	Err	bitreich.org	70
i    64 The following rule builds object files (.o) from source files (.c). The .c.o is	Err	bitreich.org	70
i    65 a inference rule that declare each .c file to be the prerequisite of a	Err	bitreich.org	70
i    66 homonymous .o file. This notation is defined by POSIX and is, therefore,	Err	bitreich.org	70
i    67 portable (different from the %.o: %.c rule, which is a GNU extension). In the	Err	bitreich.org	70
i    68 command of an inference rule (and only in the command of an inference rule), the	Err	bitreich.org	70
i    69 $< variable evaluates to the prerequisite file.	Err	bitreich.org	70
i    70 .c.o:	Err	bitreich.org	70
i    71         ${CC} -I/usr/X11R6/include ${CFLAGS} ${CPPFLAGS} -c $<	Err	bitreich.org	70
i    72 	Err	bitreich.org	70
i    73 We use the variable ${CC} to expand to the proper C compiler command. This	Err	bitreich.org	70
i    74 variable is set by default to the proper command. We should use this variable	Err	bitreich.org	70
i    75 rather than hardcoding it to gcc, for example.	Err	bitreich.org	70
i    76 	Err	bitreich.org	70
i    77 The variables ${CFLAGS} and ${CPPFLAGS} contains options that the user or	Err	bitreich.org	70
i    78 package maintainer wants to pass to the compiler or preprocessor. It is a bad	Err	bitreich.org	70
i    79 practice to define those variables in a Makefile; let the user (or package	Err	bitreich.org	70
i    80 maintainer) define them. Any option that must be passed to the compiler (such as	Err	bitreich.org	70
i    81 -I/usr/X11R6/include above) should be passed before those variables. If the	Err	bitreich.org	70
i    82 Makefile author, for example, define ${CFLAGS} to -I/usr/X11R6/include, either	Err	bitreich.org	70
i    83 this value may override the values set by the user, or the values set by the	Err	bitreich.org	70
i    84 user may shadow the option set by the Makefile author.	Err	bitreich.org	70
i    85 	Err	bitreich.org	70
i    86 The following rule links all object files into the program. We define ${OBJS} to	Err	bitreich.org	70
i    87 be the prerequisites of ${PROG}. The $@ variable evaluates to the target file	Err	bitreich.org	70
i    88 (${PROG} in our case). Since this is not an inference rule, the $< variable	Err	bitreich.org	70
i    89 cannot be used; we must write ${OBJS} both in the rule and in the command.	Err	bitreich.org	70
i    90 ${PROG}: ${OBJS}	Err	bitreich.org	70
i    91         ${CC} -o $@ ${OBJS} -L/usr/X11R6/lib -lX11 ${LDFLAGS}	Err	bitreich.org	70
i    92 	Err	bitreich.org	70
i    93 The variable ${LDFLAGS} contains options that the user or package maintainer	Err	bitreich.org	70
i    94 wants to pass to the linker. Again, it is a bad practice to define it in the	Err	bitreich.org	70
i    95 Makefile. The options -L/usr/X11R6/lib and -lX11 are passed before this variable	Err	bitreich.org	70
i    96 (so the user can override or increment them if necessary).	Err	bitreich.org	70
i    97 	Err	bitreich.org	70
i    98 The Installation rules	Err	bitreich.org	70
i    99 	Err	bitreich.org	70
i   100 Your Makefile may include rules for installing the final files in the system. In	Err	bitreich.org	70
i   101 this example, two files are installed, ${PROG} (the final, compiled program),	Err	bitreich.org	70
i   102 and ${PROG}.1 (the manpage, named as the program followed by .1). The following	Err	bitreich.org	70
i   103 rule performs the installation.	Err	bitreich.org	70
i   104 PREFIX    = /usr/local	Err	bitreich.org	70
i   105 MANPREFIX = ${PREFIX}/share/man	Err	bitreich.org	70
i   106 	Err	bitreich.org	70
i   107 install: all	Err	bitreich.org	70
i   108         mkdir -p ${DESTDIR}${PREFIX}/bin	Err	bitreich.org	70
i   109         mkdir -p ${DESTDIR}${MANPREFIX}/man1	Err	bitreich.org	70
i   110         install -m 755 ${PROG} ${DESTDIR}${PREFIX}/bin/${PROG}	Err	bitreich.org	70
i   111         install -m 644 ${PROG}.1 ${DESTDIR}${MANPREFIX}/man1/${PROG}.1	Err	bitreich.org	70
i   112 	Err	bitreich.org	70
i   113 Before installing, the program should have been built; therefore all must be a	Err	bitreich.org	70
i   114 prerequisite for install.	Err	bitreich.org	70
i   115 	Err	bitreich.org	70
i   116 The user or package maintainer can set the variable ${DESTDIR} to specify a	Err	bitreich.org	70
i   117 different installation destination. This variable must be prepended to each	Err	bitreich.org	70
i   118 installation path; and the Makefile author should not define it (it is left to	Err	bitreich.org	70
i   119 the user or package maintainer to define it). Note that there is no bar	Err	bitreich.org	70
i   120 separating ${DESTDIR} from what follows, because the ${PREFIX} and ${MANPREFIX}	Err	bitreich.org	70
i   121 variables should already begin with a bar.	Err	bitreich.org	70
i   122 	Err	bitreich.org	70
i   123 The Makefile author, however, is expected to define two variables pointing to	Err	bitreich.org	70
i   124 installation prefixes: ${PREFIX}, pointing to the general installation prefix;	Err	bitreich.org	70
i   125 and ${MANPREFIX}, pointing to the manual page installation prefix. There are	Err	bitreich.org	70
i   126 other commonly defined prefixes, such as ${bindir}, set to ${PREFIX}/bin. The	Err	bitreich.org	70
i   127 user or package maintainer can then invoke make(1) with those variables assigned	Err	bitreich.org	70
i   128 to different prefixes. On most GNU/Linux systems, for example, ${PREFIX} is	Err	bitreich.org	70
i   129 assigned to /usr; and on OpenBSD, ${MANPREFIX} is assigned to ${PREFIX}/man	Err	bitreich.org	70
i   130 (without the share/ part).	Err	bitreich.org	70
i   131 	Err	bitreich.org	70
i   132 The variables ${PREFIX} and ${MANPREFIX} are not automatically assigned, but	Err	bitreich.org	70
i   133 they can be changed by the user or package maintainer. These variables are	Err	bitreich.org	70
i   134 commonly assigned in the Makefile by the Makefile author with the ?= operator,	Err	bitreich.org	70
i   135 which assign them only if not already defined, rather than with the common =	Err	bitreich.org	70
i   136 operator. Thus, the values of these variables can be inherited from the	Err	bitreich.org	70
i   137 environment, and the user need not have to assign them on each invocation. This	Err	bitreich.org	70
i   138 operator is a non-POSIX extension, however, although supported by both GNU and	Err	bitreich.org	70
i   139 BSD make implementations.	Err	bitreich.org	70
i   140 	Err	bitreich.org	70
i   141 Looking back at the installation commands, we first use mkdir(1) to create the	Err	bitreich.org	70
i   142 destination directories, and then use install(1) to install them. We could	Err	bitreich.org	70
i   143 simply call install with the -D flag, which automatically creates the	Err	bitreich.org	70
i   144 destination directories if necessary. However, this option is an extension and	Err	bitreich.org	70
i   145 is not supported by some implementations (such as FreeBSD's). Remember to	Err	bitreich.org	70
i   146 install each file with its proper permission modes with the -m option.	Err	bitreich.org	70
i   147 	Err	bitreich.org	70
i   148 The Makefile author can also create a uninstallation rule, which simply remove	Err	bitreich.org	70
i   149 the files from their destination directories.	Err	bitreich.org	70
i   150 uninstall:	Err	bitreich.org	70
i   151         rm ${DESTDIR}${PREFIX}/bin/${PROG}	Err	bitreich.org	70
i   152         rm ${DESTDIR}${MANPREFIX}/man1/${PROG}.1	Err	bitreich.org	70
i   153 	Err	bitreich.org	70
i   154 The Cleaning Rule	Err	bitreich.org	70
i   155 	Err	bitreich.org	70
i   156 The Makefile author can define a rule to clean the build directory and revert it	Err	bitreich.org	70
i   157 to its original state. Such rule is commonly called clean. It removes the	Err	bitreich.org	70
i   158 intermediate object files and the final files. As convenience, for the developer	Err	bitreich.org	70
i   159 to clean the build directory from core files that may be created by the system	Err	bitreich.org	70
i   160 during the development, the clean rule can also delete .core files.	Err	bitreich.org	70
i   161 clean:	Err	bitreich.org	70
i   162         -rm -f ${OBJS} ${PROG} ${PROG:=.core}	Err	bitreich.org	70
i   163 	Err	bitreich.org	70
i   164 Note that the command of this rule begins with an hyphen -. This causes make to	Err	bitreich.org	70
i   165 not return error (non-zero) exit status when the command fails. This is handy,	Err	bitreich.org	70
i   166 for cleaning an already cleaned build directory to not print errors.	Err	bitreich.org	70
i   167 	Err	bitreich.org	70
i   168 The Phony Targets	Err	bitreich.org	70
i   169 	Err	bitreich.org	70
i   170 In a Makefile, some rules specify “virtual” targets which do not correspond to	Err	bitreich.org	70
i   171 any file to be created. These are the “phony” targets. The .PHONY special target	Err	bitreich.org	70
i   172 is used to mark its prerequisites as phony targets. In our Makefile, we have	Err	bitreich.org	70
i   173 four phony targets: all, install, uninstall, and clean.	Err	bitreich.org	70
i   174 .PHONY: all clean install uninstall	Err	bitreich.org	70
i   175 	Err	bitreich.org	70
i   176 The Makefile	Err	bitreich.org	70
i   177 	Err	bitreich.org	70
i   178 In the end, our Makefile should look like this:	Err	bitreich.org	70
i   179 PROG = myprog	Err	bitreich.org	70
i   180 SRCS = main.c util.c	Err	bitreich.org	70
i   181 OBJS = ${SRCS:.c=.o}	Err	bitreich.org	70
i   182 	Err	bitreich.org	70
i   183 PREFIX    = /usr/local	Err	bitreich.org	70
i   184 MANPREFIX = ${PREFIX}/share/man	Err	bitreich.org	70
i   185 	Err	bitreich.org	70
i   186 all: ${PROG}	Err	bitreich.org	70
i   187 	Err	bitreich.org	70
i   188 main.o: parse.h util.h	Err	bitreich.org	70
i   189 parse.o: parse.h util.h	Err	bitreich.org	70
i   190 util.o: util.h	Err	bitreich.org	70
i   191 	Err	bitreich.org	70
i   192 .c.o:	Err	bitreich.org	70
i   193         ${CC} -I/usr/X11R6/include ${CFLAGS} ${CPPFLAGS} -c $<	Err	bitreich.org	70
i   194 	Err	bitreich.org	70
i   195 ${PROG}: ${OBJS}	Err	bitreich.org	70
i   196         ${CC} -o $@ ${OBJS} -L/usr/X11R6/lib -lX11 ${LDFLAGS}	Err	bitreich.org	70
i   197 	Err	bitreich.org	70
i   198 install: all	Err	bitreich.org	70
i   199         mkdir -p ${DESTDIR}${PREFIX}/bin	Err	bitreich.org	70
i   200         mkdir -p ${DESTDIR}${MANPREFIX}/man1	Err	bitreich.org	70
i   201         install -m 755 ${PROG} ${DESTDIR}${PREFIX}/bin/${PROG}	Err	bitreich.org	70
i   202         install -m 644 ${PROG}.1 ${DESTDIR}${MANPREFIX}/man1/${PROG}.1	Err	bitreich.org	70
i   203 	Err	bitreich.org	70
i   204 uninstall:	Err	bitreich.org	70
i   205         rm ${DESTDIR}${PREFIX}/bin/${PROG}	Err	bitreich.org	70
i   206         rm ${DESTDIR}${MANPREFIX}/man1/${PROG}.1	Err	bitreich.org	70
i   207 	Err	bitreich.org	70
i   208 clean:	Err	bitreich.org	70
i   209         -rm -f ${OBJS} ${PROG} ${PROG:=.core}	Err	bitreich.org	70
i   210 	Err	bitreich.org	70
i   211 .PHONY: all clean install uninstall	Err	bitreich.org	70
i   212 	Err	bitreich.org	70
i   213 tl;dr	Err	bitreich.org	70
i   214 	Err	bitreich.org	70
i   215   * Define variables for the final files to be built, the source files, and the	Err	bitreich.org	70
i   216 intermediate object files created by the building process. Those are commonly	Err	bitreich.org	70
i   217 named ${PROG}, ${SRCS} and ${OBJS}, respectively.	Err	bitreich.org	70
i   218   * Include in the Makefile, but do not assign them, the variables ${CFLAGS},	Err	bitreich.org	70
i   219 ${CPPFLAGS}, ${LDFLAGS} and ${DESTDIR}. They should be assigned by the user or	Err	bitreich.org	70
i   220 package maintainer.	Err	bitreich.org	70
i   221   * Evaluate the flag variables (${CFLAGS}, ${CPPFLAGS}, and ${LDFLAGS}) after	Err	bitreich.org	70
i   222 any hardcoded flag, so the user or package maintainer can override it.	Err	bitreich.org	70
i   223   * Include the all and clean phony targets. Optionally include install and	Err	bitreich.org	70
i   224 uninstall phony targets. Always mark them as .PHONY.	Err	bitreich.org	70
i   225   * Do not use $< on anything but on the command of inference rules.	Err	bitreich.org	70
i   226   * Do not use -D with install(1).	Err	bitreich.org	70
i   227   * Do not call c99 or gcc manually. Call the command set in ${CC} instead.	Err	bitreich.org	70
i   228   * Assign ${PREFIX} and ${MANPREFIX} to the proper installation prefixes. You	Err	bitreich.org	70
i   229 can assign them with the ?= operator for the user convenience, but this	Err	bitreich.org	70
i   230 assignment operatior is not portable, although commonly supported.	Err	bitreich.org	70
i   231 	Err	bitreich.org	70
i   232 References	Err	bitreich.org	70
i   233 	Err	bitreich.org	70
i   234    1. file:///feed.xml	Err	bitreich.org	70
i   235    2. https://seninha.org/	Err	bitreich.org	70
i   236 EOF	Err	bitreich.org	70
i   237 	Err	bitreich.org	70
.