bsd.README revision 1.16
1# $NetBSD: bsd.README,v 1.16 1996/04/04 02:05:03 jtc 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 eight 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 includes: 220 install any header files. 221 install: 222 install the program and its manual pages; if the Makefile 223 does not itself define the target install, the targets 224 beforeinstall and afterinstall may also be used to cause 225 actions immediately before and after the install target 226 is executed. 227 lint: 228 run lint on the source files 229 tags: 230 create a tags file for the source files. 231 232It sets/uses the following variables: 233 234BINGRP Binary group. 235 236BINOWN Binary owner. 237 238BINMODE Binary mode. 239 240CLEANFILES Additional files to remove for the clean and cleandir targets. 241 242COPTS Additional flags to the compiler when creating C objects. 243 244HIDEGAME If HIDEGAME is defined, the binary is installed in 245 /usr/games/hide, and a symbolic link is created to 246 /usr/games/dm. 247 248LDADD Additional loader objects. Usually used for libraries. 249 For example, to load with the compatibility and utility 250 libraries, use: 251 252 LDADD+=-lutil -lcompat 253 254LDFLAGS Additional loader flags. 255 256LINKS The list of binary links; should be full pathnames, the 257 linked-to file coming first, followed by the linked 258 file. The files are hard-linked. For example, to link 259 /bin/test and /bin/[, use: 260 261 LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[ 262 263MAN Manual pages (should end in .1 - .9). If no MAN variable is 264 defined, "MAN=${PROG}.1" is assumed. 265 266PROG The name of the program to build. If not supplied, nothing 267 is built. 268 269SRCS List of source files to build the program. If PROG is not 270 defined, it's assumed to be ${PROG}.c. 271 272DPADD Additional dependencies for the program. Usually used for 273 libraries. For example, to depend on the compatibility and 274 utility libraries use: 275 276 DPADD+=${LIBCOMPAT} ${LIBUTIL} 277 278 The following libraries are predefined for DPADD: 279 280 LIBC /lib/libc.a 281 LIBCOMPAT /usr/lib/libcompat.a 282 LIBCRYPT /usr/lib/libcrypt.a 283 LIBCURSES /usr/lib/libcurses.a 284 LIBDBM /usr/lib/libdbm.a 285 LIBDES /usr/lib/libdes.a 286 LIBL /usr/lib/libl.a 287 LIBKDB /usr/lib/libkdb.a 288 LIBKRB /usr/lib/libkrb.a 289 LIBKVM /usr/lib/libkvm.a 290 LIBM /usr/lib/libm.a 291 LIBMP /usr/lib/libmp.a 292 LIBPC /usr/lib/libpc.a 293 LIBPLOT /usr/lib/libplot.a 294 LIBRPC /usr/lib/sunrpc.a 295 LIBTERM /usr/lib/libterm.a 296 LIBUTIL /usr/lib/libutil.a 297 298SHAREDSTRINGS If defined, a new .c.o rule is used that results in shared 299 strings, using xstr(1). Note that this will not work with 300 parallel makes. 301 302STRIP The flag passed to the install program to cause the binary 303 to be stripped. 304 305SUBDIR A list of subdirectories that should be built as well. 306 Each of the targets will execute the same target in the 307 subdirectories. 308 309The include file <bsd.prog.mk> includes the file named "../Makefile.inc" 310if it exists, as well as the include file <bsd.man.mk>. 311 312Some simple examples: 313 314To build foo from foo.c with a manual page foo.1, use: 315 316 PROG= foo 317 318 .include <bsd.prog.mk> 319 320To build foo from foo.c with a manual page foo.2, add the line: 321 322 MAN= foo.2 323 324If foo does not have a manual page at all, add the line: 325 326 NOMAN= noman 327 328If foo has multiple source files, add the line: 329 330 SRCS= a.c b.c c.c d.c 331 332=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 333 334The include file <bsd.subdir.mk> contains the default targets for building 335subdirectories. It has the same eight targets as <bsd.prog.mk>: all, 336clean, cleandir, depend, includes, install, lint, and tags. For all of 337the directories listed in the variable SUBDIRS, the specified directory 338will be visited and the target made. There is also a default target which 339allows the command "make subdir" where subdir is any directory listed in 340the variable SUBDIRS. 341 342=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 343 344The include file <bsd.sys.mk> is used by <bsd.prog.mk> and 345<bsd.lib.mk>. It contains overrides that are used when building 346the NetBSD source tree. For instance, if "PARALLEL" is defined by 347the program/library Makefile, it includes a set of rules for lex and 348yacc that allow multiple lex and yacc targets to be built in parallel. 349 350=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 351 352The include file <bsd.lib.mk> has support for building libraries. It has 353the same eight targets as <bsd.prog.mk>: all, clean, cleandir, depend, 354includes, install, lint, and tags. It has a limited number of suffixes, 355consistent with the current needs of the BSD tree. 356 357It sets/uses the following variables: 358 359LIB The name of the library to build. 360 361LIBDIR Target directory for libraries. 362 363LINTLIBDIR Target directory for lint libraries. 364 365LIBGRP Library group. 366 367LIBOWN Library owner. 368 369LIBMODE Library mode. 370 371LDADD Additional loader objects. 372 373MAN The manual pages to be installed (use a .1 - .9 suffix). 374 375SRCS List of source files to build the library. Suffix types 376 .s, .c, and .f are supported. Note, .s files are preferred 377 to .c files of the same name. (This is not the default for 378 versions of make.) 379 380The include file <bsd.lib.mk> includes the file named "../Makefile.inc" 381if it exists, as well as the include file <bsd.man.mk>. 382 383It has rules for building profiled objects; profiled libraries are 384built by default. 385 386Libraries are ranlib'd when made. 387