bsd.README revision 1.14
1# $NetBSD: bsd.README,v 1.14 1995/12/13 01:25:05 cgd Exp $ 2# @(#)bsd.README 5.1 (Berkeley) 5/11/90 3 4This is the README file for the new make "include" files for the BSD 5source tree. The files are installed in /usr/share/mk, and are, by 6convention, named with the suffix ".mk". 7 8Note, this file is not intended to replace reading through the .mk 9files for anything tricky. 10 11=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 12 13RANDOM THINGS WORTH KNOWING: 14 15The files are simply C-style #include files, and pretty much behave like 16you'd expect. The syntax is slightly different in that a single '.' is 17used instead of the hash mark, i.e. ".include <bsd.prog.mk>". 18 19One difference that will save you lots of debugging time is that inclusion 20of the file is normally done at the *end* of the Makefile. The reason for 21this is because .mk files often modify variables and behavior based on the 22values of variables set in the Makefile. To make this work, remember that 23the FIRST target found is the target that is used, i.e. if the Makefile has: 24 25 a: 26 echo a 27 a: 28 echo a number two 29 30the command "make a" will echo "a". To make things confusing, the SECOND 31variable assignment is the overriding one, i.e. if the Makefile has: 32 33 a= foo 34 a= bar 35 36 b: 37 echo ${a} 38 39the command "make b" will echo "bar". This is for compatibility with the 40way the V7 make behaved. 41 42It's fairly difficult to make the BSD .mk files work when you're building 43multiple programs in a single directory. It's a lot easier split up the 44programs than to deal with the problem. Most of the agony comes from making 45the "obj" directory stuff work right, not because we switch to a new version 46of make. So, don't get mad at us, figure out a better way to handle multiple 47architectures so we can quit using the symbolic link stuff. (Imake doesn't 48count.) 49 50The file .depend in the source directory is expected to contain dependencies 51for the source files. This file is read automatically by make after reading 52the Makefile. 53 54The variable DESTDIR works as before. It's not set anywhere but will change 55the tree where the file gets installed. 56 57The profiled libraries are no longer built in a different directory than 58the regular libraries. A new suffix, ".po", is used to denote a profiled 59object. 60 61=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 62 63The include file <sys.mk> has the default rules for all makes, in the BSD 64environment or otherwise. You probably don't want to touch this file. 65 66=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 67 68The include file <bsd.man.mk> handles installing manual pages and their 69links. 70 71It has a single target: 72 73 maninstall: 74 Install the manual pages and their links. 75 76It sets/uses the following variables: 77 78MANDIR Base path for manual installation. 79 80MANGRP Manual group. 81 82MANOWN Manual owner. 83 84MANMODE Manual mode. 85 86MANSUBDIR Subdirectory under the manual page section, i.e. "/vax" 87 or "/tahoe" for machine specific manual pages. 88 89MAN The manual pages to be installed (use a .1 - .8 suffix). 90 91MLINKS List of manual page links (using a .1 - .8 suffix). The 92 linked-to file must come first, the linked file second, 93 and there may be multiple pairs. The files are soft-linked. 94 95The include file <bsd.man.mk> includes a file named "../Makefile.inc" if 96it exists. 97 98=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 99 100The include file <bsd.own.mk> contains the owners, groups, etc. for both 101manual pages and binaries. 102 103It has no targets. 104 105It sets/uses the following variables: 106 107BINGRP Binary group. 108 109BINOWN Binary owner. 110 111BINMODE Binary mode. 112 113STRIP The flag passed to the install program to cause the binary 114 to be stripped. This is to be used when building your 115 own install script so that the entire system can be made 116 stripped/not-stripped using a single nob. 117 118COPY The flag passed to the install program to cause the binary 119 to be copied rather than moved. This is to be used when 120 building our own install script so that the entire system 121 can either be installed with copies, or with moves using 122 a single nob. 123 124MANDIR Base path for manual installation. 125 126MANGRP Manual group. 127 128MANOWN Manual owner. 129 130MANMODE Manual mode. 131 132This file is generally useful when building your own Makefiles so that 133they use the same default owners etc. as the rest of the tree. 134 135=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 136 137The include file <bsd.prog.mk> handles building programs from one or 138more source files, along with their manual pages. It has a limited number 139of suffixes, consistent with the current needs of the BSD tree. 140 141It has seven targets: 142 143 all: 144 build the program and its manual page 145 clean: 146 remove the program, any object files and the files a.out, 147 Errs, errs, mklog, and core. 148 cleandir: 149 remove all of the files removed by the target clean, as 150 well as .depend, tags, and any manual pages. 151 depend: 152 make the dependencies for the source files, and store 153 them in the file .depend. 154 install: 155 install the program and its manual pages; if the Makefile 156 does not itself define the target install, the targets 157 beforeinstall and afterinstall may also be used to cause 158 actions immediately before and after the install target 159 is executed. 160 lint: 161 run lint on the source files 162 tags: 163 create a tags file for the source files. 164 165It sets/uses the following variables: 166 167BINGRP Binary group. 168 169BINOWN Binary owner. 170 171BINMODE Binary mode. 172 173CLEANFILES Additional files to remove for the clean and cleandir targets. 174 175COPTS Additional flags to the compiler when creating C objects. 176 177HIDEGAME If HIDEGAME is defined, the binary is installed in 178 /usr/games/hide, and a symbolic link is created to 179 /usr/games/dm. 180 181LDADD Additional loader objects. Usually used for libraries. 182 For example, to load with the compatibility and utility 183 libraries, use: 184 185 LDADD+=-lutil -lcompat 186 187LDFLAGS Additional loader flags. 188 189LINKS The list of binary links; should be full pathnames, the 190 linked-to file coming first, followed by the linked 191 file. The files are hard-linked. For example, to link 192 /bin/test and /bin/[, use: 193 194 LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[ 195 196MAN Manual pages (should end in .1 - .8). If no MAN variable is 197 defined, "MAN=${PROG}.1" is assumed. 198 199PROG The name of the program to build. If not supplied, nothing 200 is built. 201 202SRCS List of source files to build the program. If PROG is not 203 defined, it's assumed to be ${PROG}.c. 204 205DPADD Additional dependencies for the program. Usually used for 206 libraries. For example, to depend on the compatibility and 207 utility libraries use: 208 209 DPADD+=${LIBCOMPAT} ${LIBUTIL} 210 211 The following libraries are predefined for DPADD: 212 213 LIBC /lib/libc.a 214 LIBCOMPAT /usr/lib/libcompat.a 215 LIBCRYPT /usr/lib/libcrypt.a 216 LIBCURSES /usr/lib/libcurses.a 217 LIBDBM /usr/lib/libdbm.a 218 LIBDES /usr/lib/libdes.a 219 LIBL /usr/lib/libl.a 220 LIBKDB /usr/lib/libkdb.a 221 LIBKRB /usr/lib/libkrb.a 222 LIBKVM /usr/lib/libkvm.a 223 LIBM /usr/lib/libm.a 224 LIBMP /usr/lib/libmp.a 225 LIBPC /usr/lib/libpc.a 226 LIBPLOT /usr/lib/libplot.a 227 LIBRPC /usr/lib/sunrpc.a 228 LIBTERM /usr/lib/libterm.a 229 LIBUTIL /usr/lib/libutil.a 230 231SHAREDSTRINGS If defined, a new .c.o rule is used that results in shared 232 strings, using xstr(1). Note that this will not work with 233 parallel makes. 234 235STRIP The flag passed to the install program to cause the binary 236 to be stripped. 237 238SUBDIR A list of subdirectories that should be built as well. 239 Each of the targets will execute the same target in the 240 subdirectories. 241 242The include file <bsd.prog.mk> includes the file named "../Makefile.inc" 243if it exists, as well as the include file <bsd.man.mk>. 244 245Some simple examples: 246 247To build foo from foo.c with a manual page foo.1, use: 248 249 PROG= foo 250 251 .include <bsd.prog.mk> 252 253To build foo from foo.c with a manual page foo.2, add the line: 254 255 MAN= foo.2 256 257If foo does not have a manual page at all, add the line: 258 259 NOMAN= noman 260 261If foo has multiple source files, add the line: 262 263 SRCS= a.c b.c c.c d.c 264 265=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 266 267The include file <bsd.subdir.mk> contains the default targets for building 268subdirectories. It has the same seven targets as <bsd.prog.mk>: all, clean, 269cleandir, depend, install, lint, and tags. For all of the directories 270listed in the variable SUBDIRS, the specified directory will be visited 271and the target made. There is also a default target which allows the 272command "make subdir" where subdir is any directory listed in the variable 273SUBDIRS. 274 275=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 276 277The include file <bsd.sys.mk> is used by <bsd.prog.mk> and 278<bsd.lib.mk>. It contains overrides that are used when building 279the NetBSD source tree. For instance, if "PARALLEL" is defined by 280the program/library Makefile, it includes a set of rules for lex and 281yacc that allow multiple lex and yacc targets to be built in parallel. 282 283=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 284 285The include file <bsd.lib.mk> has support for building libraries. It has 286the same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend, 287install, lint, and tags. It has a limited number of suffixes, consistent 288with the current needs of the BSD tree. 289 290It sets/uses the following variables: 291 292LIB The name of the library to build. 293 294LIBDIR Target directory for libraries. 295 296LINTLIBDIR Target directory for lint libraries. 297 298LIBGRP Library group. 299 300LIBOWN Library owner. 301 302LIBMODE Library mode. 303 304LDADD Additional loader objects. 305 306MAN The manual pages to be installed (use a .1 - .8 suffix). 307 308SRCS List of source files to build the library. Suffix types 309 .s, .c, and .f are supported. Note, .s files are preferred 310 to .c files of the same name. (This is not the default for 311 versions of make.) 312 313The include file <bsd.lib.mk> includes the file named "../Makefile.inc" 314if it exists, as well as the include file <bsd.man.mk>. 315 316It has rules for building profiled objects; profiled libraries are 317built by default. 318 319Libraries are ranlib'd when made. 320