bsd.README revision 1.15
1# $NetBSD: bsd.README,v 1.15 1996/01/22 22:46:06 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 - .9 suffix). 90 91MLINKS List of manual page links (using a .1 - .9 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 the following variables, if they are not already defined (defaults 106are in brackets): 107 108BSDSRCDIR The real path to the system sources, so that 'make obj' 109 will work correctly. [/usr/src] 110 111BSDOBJDIR The real path to the system 'obj' tree, so that 'make obj' 112 will work correctly. [/usr/obj] 113 114BINGRP Binary group. [bin] 115 116BINOWN Binary owner. [bin] 117 118BINMODE Binary mode. [555] 119 120NONBINMODE Mode for non-executable files. [444] 121 122MANDIR Base path for manual installation. [/usr/share/man/cat] 123 124MANGRP Manual group. [bin] 125 126MANOWN Manual owner. [bin] 127 128MANMODE Manual mode. [${NONBINMODE}] 129 130LIBDIR Base path for library installation. [/usr/lib] 131 132LINTLIBDIR Base path for lint(1) library installation. [/usr/libdata/lint] 133 134LIBGRP Library group. [${BINGRP}] 135 136LIBOWN Library owner. [${BINOWN}] 137 138LIBMODE Library mode. [${NONBINMODE}] 139 140DOCDIR Base path for system documentation (e.g. PSD, USD, etc.) 141 installation. [/usr/share/doc] 142 143DOCGRP Documentation group. [bin] 144 145DOCOWN Documentation owner. [bin] 146 147DOCMODE Documentation mode. [${NONBINMODE}] 148 149NLSDIR Base path for National Language Support files installation. 150 [/usr/share/nls] 151 152NLSGRP National Language Support files group. [bin] 153 154NLSOWN National Language Support files owner. [bin] 155 156NLSMODE National Language Support files mode. [${NONBINMODE}] 157 158STRIP The flag passed to the install program to cause the binary 159 to be stripped. This is to be used when building your 160 own install script so that the entire system can be made 161 stripped/not-stripped using a single knob. [-s] 162 163COPY The flag passed to the install program to cause the binary 164 to be copied rather than moved. This is to be used when 165 building our own install script so that the entire system 166 can either be installed with copies, or with moves using 167 a single knob. [-c] 168 169Additionally, the following variables may be set to modify the behaviour 170of the system build process (default values are in brackets along with 171comments, if set by bsd.own.mk): 172 173EXPORTABLE_SYSTEM 174 Do not build /usr/src/domestic, even if it is present. 175 176SKEY Compile in support for S/key authentication. [yes, set 177 unconditionally] 178 179KERBEROS Compile in support for Kerberos 4 authentication. 180 181KERBEROS5 Compile in support for Kerberos 5 authentication. 182 183MANZ Compress manual pages at installation time. 184 185SYS_INCLUDE Copy or symlink kernel include files into /usr/include. 186 Possible values are "symlinks" or "copies" (which is 187 the same as the variable being unset). 188 189NOPROFILE Do not build profiled versions of system libraries 190 191NOPIC Do not build PIC versions of system libraries, and 192 do not build shared libraries. [set if ${MACHINE_ARCH} 193 is "mips", "vax", or "alpha", unset otherwise.] 194 195NOLINT Do not build lint libraries. [set, set unconditionally] 196 197This file is generally useful when building your own Makefiles so that 198they use the same default owners etc. as the rest of the tree. 199 200=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 201 202The include file <bsd.prog.mk> handles building programs from one or 203more source files, along with their manual pages. It has a limited number 204of suffixes, consistent with the current needs of the BSD tree. 205 206It has seven targets: 207 208 all: 209 build the program and its manual page 210 clean: 211 remove the program, any object files and the files a.out, 212 Errs, errs, mklog, and core. 213 cleandir: 214 remove all of the files removed by the target clean, as 215 well as .depend, tags, and any manual pages. 216 depend: 217 make the dependencies for the source files, and store 218 them in the file .depend. 219 install: 220 install the program and its manual pages; if the Makefile 221 does not itself define the target install, the targets 222 beforeinstall and afterinstall may also be used to cause 223 actions immediately before and after the install target 224 is executed. 225 lint: 226 run lint on the source files 227 tags: 228 create a tags file for the source files. 229 230It sets/uses the following variables: 231 232BINGRP Binary group. 233 234BINOWN Binary owner. 235 236BINMODE Binary mode. 237 238CLEANFILES Additional files to remove for the clean and cleandir targets. 239 240COPTS Additional flags to the compiler when creating C objects. 241 242HIDEGAME If HIDEGAME is defined, the binary is installed in 243 /usr/games/hide, and a symbolic link is created to 244 /usr/games/dm. 245 246LDADD Additional loader objects. Usually used for libraries. 247 For example, to load with the compatibility and utility 248 libraries, use: 249 250 LDADD+=-lutil -lcompat 251 252LDFLAGS Additional loader flags. 253 254LINKS The list of binary links; should be full pathnames, the 255 linked-to file coming first, followed by the linked 256 file. The files are hard-linked. For example, to link 257 /bin/test and /bin/[, use: 258 259 LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[ 260 261MAN Manual pages (should end in .1 - .9). If no MAN variable is 262 defined, "MAN=${PROG}.1" is assumed. 263 264PROG The name of the program to build. If not supplied, nothing 265 is built. 266 267SRCS List of source files to build the program. If PROG is not 268 defined, it's assumed to be ${PROG}.c. 269 270DPADD Additional dependencies for the program. Usually used for 271 libraries. For example, to depend on the compatibility and 272 utility libraries use: 273 274 DPADD+=${LIBCOMPAT} ${LIBUTIL} 275 276 The following libraries are predefined for DPADD: 277 278 LIBC /lib/libc.a 279 LIBCOMPAT /usr/lib/libcompat.a 280 LIBCRYPT /usr/lib/libcrypt.a 281 LIBCURSES /usr/lib/libcurses.a 282 LIBDBM /usr/lib/libdbm.a 283 LIBDES /usr/lib/libdes.a 284 LIBL /usr/lib/libl.a 285 LIBKDB /usr/lib/libkdb.a 286 LIBKRB /usr/lib/libkrb.a 287 LIBKVM /usr/lib/libkvm.a 288 LIBM /usr/lib/libm.a 289 LIBMP /usr/lib/libmp.a 290 LIBPC /usr/lib/libpc.a 291 LIBPLOT /usr/lib/libplot.a 292 LIBRPC /usr/lib/sunrpc.a 293 LIBTERM /usr/lib/libterm.a 294 LIBUTIL /usr/lib/libutil.a 295 296SHAREDSTRINGS If defined, a new .c.o rule is used that results in shared 297 strings, using xstr(1). Note that this will not work with 298 parallel makes. 299 300STRIP The flag passed to the install program to cause the binary 301 to be stripped. 302 303SUBDIR A list of subdirectories that should be built as well. 304 Each of the targets will execute the same target in the 305 subdirectories. 306 307The include file <bsd.prog.mk> includes the file named "../Makefile.inc" 308if it exists, as well as the include file <bsd.man.mk>. 309 310Some simple examples: 311 312To build foo from foo.c with a manual page foo.1, use: 313 314 PROG= foo 315 316 .include <bsd.prog.mk> 317 318To build foo from foo.c with a manual page foo.2, add the line: 319 320 MAN= foo.2 321 322If foo does not have a manual page at all, add the line: 323 324 NOMAN= noman 325 326If foo has multiple source files, add the line: 327 328 SRCS= a.c b.c c.c d.c 329 330=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 331 332The include file <bsd.subdir.mk> contains the default targets for building 333subdirectories. It has the same seven targets as <bsd.prog.mk>: all, clean, 334cleandir, depend, install, lint, and tags. For all of the directories 335listed in the variable SUBDIRS, the specified directory will be visited 336and the target made. There is also a default target which allows the 337command "make subdir" where subdir is any directory listed in the variable 338SUBDIRS. 339 340=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 341 342The include file <bsd.sys.mk> is used by <bsd.prog.mk> and 343<bsd.lib.mk>. It contains overrides that are used when building 344the NetBSD source tree. For instance, if "PARALLEL" is defined by 345the program/library Makefile, it includes a set of rules for lex and 346yacc that allow multiple lex and yacc targets to be built in parallel. 347 348=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 349 350The include file <bsd.lib.mk> has support for building libraries. It has 351the same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend, 352install, lint, and tags. It has a limited number of suffixes, consistent 353with the current needs of the BSD tree. 354 355It sets/uses the following variables: 356 357LIB The name of the library to build. 358 359LIBDIR Target directory for libraries. 360 361LINTLIBDIR Target directory for lint libraries. 362 363LIBGRP Library group. 364 365LIBOWN Library owner. 366 367LIBMODE Library mode. 368 369LDADD Additional loader objects. 370 371MAN The manual pages to be installed (use a .1 - .9 suffix). 372 373SRCS List of source files to build the library. Suffix types 374 .s, .c, and .f are supported. Note, .s files are preferred 375 to .c files of the same name. (This is not the default for 376 versions of make.) 377 378The include file <bsd.lib.mk> includes the file named "../Makefile.inc" 379if it exists, as well as the include file <bsd.man.mk>. 380 381It has rules for building profiled objects; profiled libraries are 382built by default. 383 384Libraries are ranlib'd when made. 385