1# $OpenBSD: bsd.README,v 1.44 2011/04/22 21:11:50 jmc Exp $ 2# $NetBSD: bsd.README,v 1.17 1996/04/13 02:08:08 thorpej Exp $ 3# @(#)bsd.README 5.1 (Berkeley) 5/11/90 4 5This is the README file for the new make "include" files for the BSD 6source tree. The files are installed in /usr/share/mk, and are, by 7convention, named with the suffix ".mk". 8 9bsd.dep.mk - handle Makefile dependencies 10bsd.lib.mk - support for building libraries 11bsd.lkm.mk - building loadable kernel modules 12bsd.man.mk - installing manual pages and their links 13bsd.nls.mk - National Language Support 14bsd.obj.mk - creating 'obj' directories and cleaning up 15bsd.own.mk - define common variables 16bsd.port.mk - building ports 17bsd.port.subdir.mk - targets for building subdirectories for ports 18bsd.prog.mk - building programs from source files 19bsd.regress.mk - regression tests 20bsd.subdir.mk - targets for building subdirectories 21bsd.sys.mk - building bsd from the source tree 22 23Note, this file is not intended to replace reading through the .mk 24files for anything tricky. 25 26=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 27 28RANDOM THINGS WORTH KNOWING: 29 30The files are simply C-style #include files, and pretty much behave like 31you'd expect. The syntax is slightly different in that a single '.' is 32used instead of the hash mark, i.e. ".include <bsd.prog.mk>". 33 34One difference that will save you lots of debugging time is that inclusion 35of the file is normally done at the *end* of the Makefile. The reason for 36this is because .mk files often modify variables and behavior based on the 37values of variables set in the Makefile. To make this work, remember that 38the FIRST target found is the target that is used, i.e. if the Makefile has: 39 40 a: 41 echo a 42 a: 43 echo a number two 44 45the command "make a" will echo "a". To make things confusing, the SECOND 46variable assignment is the overriding one, i.e. if the Makefile has: 47 48 a= foo 49 a= bar 50 51 b: 52 echo ${a} 53 54the command "make b" will echo "bar". This is for compatibility with the 55way the V7 make behaved. 56 57To make things even more confusing, make uses lazy evaluation. All 58variables are expanded only when needed. Which means that, in 59 60 a= foo 61 62 b: $(a) 63 echo $(.ALLSRC) 64 echo $(a) 65 66 foo: 67 touch foo 68 69 a= bar 70 71the command "make b" will echo "foo"; echo "bar". The first $(a) means 72"foo", because it's needed to generate the dependency rule when it's read, 73but the second $(a) is only expanded when needed, at which point a contains 74bar. 75 76It's fairly difficult to make the BSD .mk files work when you're building 77multiple programs in a single directory. It's a lot easier to split up the 78programs than to deal with the problem. Most of the agony comes from making 79the "obj" directory stuff work right, not because we switched to a new version 80of make. So, don't get mad at us, figure out a better way to handle multiple 81architectures so we can quit using the symbolic link stuff. (Imake doesn't 82count.) 83 84The file .depend in the source directory is expected to contain dependencies 85for the source files. This file is read automatically by make after reading 86the Makefile. 87 88The variable DESTDIR works as before. It's not set anywhere but will change 89the tree where the file gets installed. 90 91The profiled libraries are no longer built in a different directory than 92the regular libraries. A new suffix, ".po", is used to denote a profiled 93object. 94 95=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 96 97The include file <sys.mk> has the default rules for all makes, in the BSD 98environment or otherwise. You probably don't want to touch this file. 99 100=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 101 102The include file <bsd.man.mk> handles installing manual pages and their 103links. 104 105It has a single target: 106 107 maninstall: 108 Install the manual pages and their links. 109 110It sets/uses the following variables: 111 112MANDIR Base path for manual installation. 113 114MANGRP Manual group. 115 116MANOWN Manual owner. 117 118MANMODE Manual mode. 119 120MANSUBDIR Subdirectory under the manual page section, i.e. "vax" 121 or "tahoe" for machine specific manual pages. 122 123MAN The manual pages to be installed (use a .1 - .9 suffix). 124 125MLINKS List of manual page links (using a .1 - .9 suffix). The 126 linked-to file must come first, the linked file second, 127 and there may be multiple pairs. The files are soft-linked. 128 129BEFOREMAN List of extra targets that must be already built before the 130 man target can be run. Those targets must be real files (and 131 not .PHONY targets). 132 133The include file <bsd.man.mk> includes a file named "../Makefile.inc" if 134it exists. 135 136=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 137 138The include file <bsd.own.mk> contains source tree configuration parameters, 139such as the owners, groups, etc. for both manual pages and binaries, and 140a few global "feature configuration" parameters. 141 142It has no targets. 143 144To get system-specific configuration parameters, bsd.own.mk will try to 145include the file specified by the "MAKECONF" variable. If MAKECONF is not 146set, or no such file exists, the system make configuration file, /etc/mk.conf 147is included. These files may define any of the variables described below. 148 149bsd.own.mk sets the following variables, if they are not already defined 150(defaults are in brackets): 151 152BSDSRCDIR The real path to the system sources, so that 'make obj' 153 will work correctly. [/usr/src] 154 155BSDOBJDIR The real path to the system 'obj' tree, so that 'make obj' 156 will work correctly. [/usr/obj] 157 158BINGRP Binary group. [bin] 159 160BINOWN Binary owner. [root] 161 162BINMODE Binary mode. [555] 163 164NONBINMODE Mode for non-executable files. [444] 165 166DIRMODE Mode for new directories. [755] 167 168MANDIR Base path for manual installation. [/usr/share/man/cat] 169 170MANGRP Manual group. [bin] 171 172MANOWN Manual owner. [root] 173 174MANMODE Manual mode. [${NONBINMODE}] 175 176LIBDIR Base path for library installation. [/usr/lib] 177 178LINTLIBDIR Base path for lint(1) library installation. [/usr/libdata/lint] 179 180LIBGRP Library group. [${BINGRP}] 181 182LIBOWN Library owner. [${BINOWN}] 183 184LIBMODE Library mode. [${NONBINMODE}] 185 186DOCDIR Base path for system documentation 187 installation. [/usr/share/doc] 188 189DOCGRP Documentation group. [bin] 190 191DOCOWN Documentation owner. [root] 192 193DOCMODE Documentation mode. [${NONBINMODE}] 194 195NLSDIR Base path for National Language Support files installation. 196 [/usr/share/nls] 197 198NLSGRP National Language Support files group. [bin] 199 200NLSOWN National Language Support files owner. [root] 201 202NLSMODE National Language Support files mode. [${NONBINMODE}] 203 204INSTALL_STRIP The flag passed to the install program to cause the binary 205 to be stripped. This is to be used when building your 206 own install script so that the entire system can be made 207 stripped/not-stripped using a single knob. Note that 208 INSTALL_STRIP is not set if ${DEBUG} is defined. [-s] 209 210INSTALL_COPY The old usage of this flag is obsolescent since install(1) 211 now copies by default. However, it can also be used to 212 specify that a file not be copied unless it is different 213 (via the -p option). See install(1) for details. This 214 is to be used when building our own install script so 215 that the entire system can either be installed with copies, 216 or copy-if-different using a single knob. [-c] 217 218Additionally, the following variables may be set by bsd.own.mk or in a 219make configuration file to modify the behaviour of the system build 220process (default values are in brackets along with comments, if set by 221bsd.own.mk): 222 223AFS Compile support for AFS. 224 225SKEY Compile in support for S/key authentication. [yes, set 226 unconditionally] 227 228KERBEROS5 Compile in support for Kerberos 5 authentication. 229 230MANZ Compress manual pages at installation time. 231 232MANPS Define to have PostScript manual pages generated. 233 234SYS_INCLUDE Copy or symlink kernel include files into /usr/include. 235 Possible values are "symlinks" or "copies" (which is 236 the same as the variable being unset). 237 238NOPROFILE Do not build profiled versions of system libraries. 239 240NOPIC Do not build PIC versions of system libraries, and 241 do not build shared libraries. 242 243WANTLINT Build lint libraries. 244 245DEBUG Add -g to assembly, C compiler and linking passes. Also 246 doesn't set STRIP to -s per default if defined. 247 248DEBUGLIBS Create libraries with -g debug information, and install 249 them in /usr/lib/debug. 250 251WARNINGS Adds appropriate warning flags (defined in CDIAGFLAGS, 252 e.g., -Wall...) to compiles. [no] 253 254SUDO Command to run when doing "make install" portion of 255 "make build". If set to sudo, this allows one to run 256 "make build" as a user other than root (assuming sudo 257 is setup for that user). 258 259PIPE If set to "-pipe" gcc will be given the -pipe option 260 which can speed up compiles on machines with memory 261 to spare. Instead of using temp files, gcc uses pipes 262 for the temporary data. 263 264GLOBAL_AUTOCONF_CACHE 265 Set to the name of a file that all cached GNU autoconf 266 test results will be saved in. Reduces redundant tests. 267 Be careful! Redundant tests may not be redundant if you 268 are installing substantially updated gnu programs. 269 270bsd.own.mk is generally useful when building your own Makefiles so that 271they use the same default owners etc. as the rest of the tree. 272 273=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 274 275The include file <bsd.prog.mk> handles building programs from one or 276more source files, along with their manual pages. It has a limited number 277of suffixes, consistent with the current needs of the BSD tree. 278 279It has eight targets: 280 281 all: 282 build the program and its manual page 283 clean: 284 remove the program, any object files and the files a.out, 285 Errs, errs, mklog, and core. 286 cleandir: 287 remove all of the files removed by the target clean, as 288 well as .depend, tags, and any manual pages. 289 depend: 290 make the dependencies for the source files, and store 291 them in the file .depend. 292 includes: 293 install any header files. 294 install: 295 install the program and its manual pages; if the Makefile 296 does not itself define the target install, the targets 297 beforeinstall and afterinstall may also be used to cause 298 actions immediately before and after the install target 299 is executed. 300 lint: 301 run lint on the source files 302 tags: 303 create a tags file for the source files. 304 305It sets/uses the following variables: 306 307BINGRP Binary group. 308 309BINOWN Binary owner. 310 311BINMODE Binary mode. 312 313CLEANFILES Additional files to remove for the clean and cleandir targets. 314 315COPTS Additional flags to the compiler when creating C objects. 316 317LDADD Additional loader objects. Usually used for libraries. 318 For example, to load with the compatibility and utility 319 libraries, use: 320 321 LDADD+=-lutil -lcompat 322 323LDFLAGS Additional loader flags. 324 325LINKS The list of binary links; should be full pathnames, the 326 linked-to file coming first, followed by the linked 327 file. The files are hard-linked. For example, to link 328 /bin/test and /bin/[, use: 329 330 LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[ 331 332MAN Manual pages (should end in .1 - .9). If no MAN variable is 333 defined, "MAN=${PROG}.1" is assumed. 334 335PROG The name of the program to build. If not supplied, nothing 336 is built. 337 338SRCS List of source files to build the program. If it's not 339 defined, it's assumed to be ${PROG}.c. 340 341DPADD Additional dependencies for the program. Usually used for 342 libraries. For example, to depend on the compatibility and 343 utility libraries use: 344 345 DPADD+=${LIBCOMPAT} ${LIBUTIL} 346 347 The following libraries are predefined for DPADD: 348 349 LIBASN1 /usr/lib/libasn1.a 350 LIBC /usr/lib/libc.a 351 LIBCOM_ERR /usr/lib/libcom_err.a 352 LIBCOMPAT /usr/lib/libcompat.a 353 LIBCRYPTO /usr/lib/libcrypto.a 354 LIBCURSES /usr/lib/libcurses.a 355 LIBEDIT /usr/lib/libedit.a 356 LIBEVENT /usr/lib/libevent.a 357 LIBEXPAT /usr/lib/libexpat.a 358 LIBFORM /usr/lib/libform.a 359 LIBFORMW /usr/lib/libformw.a 360 LIBGSSAPI /usr/lib/libgssapi.a 361 LIBHDB /usr/lib/libhdb.a 362 LIBKADM5CLNT /usr/lib/libkadm5clnt.a 363 LIBKADM5SRV /usr/lib/libkadm5srv.a 364 LIBKAFS /usr/lib/libkafs.a 365 LIBKEYNOTE /usr/lib/libkeynote.a 366 LIBKRB5 /usr/lib/libkrb5.a 367 LIBKVM /usr/lib/libkvm.a 368 LIBL /usr/lib/libl.a 369 LIBM /usr/lib/libm.a 370 LIBMENU /usr/lib/libmenu.a 371 LIBMENUW /usr/lib/libmenuw.a 372 LIBOLDCURSES /usr/lib/libocurses.a 373 LIBOSSAUDIO /usr/lib/libossaudio.a 374 LIBPANEL /usr/lib/libpanel.a 375 LIBPANELW /usr/lib/libpanelw.a 376 LIBPCAP /usr/lib/libpcap.a 377 LIBPERL /usr/lib/libperl.a 378 LIBPTHREAD /usr/lib/libpthread.a 379 LIBRPCSVC /usr/lib/librpcsvc.a 380 LIBSKEY /usr/lib/libskey.a 381 LIBSNDIO /usr/lib/libsndio.a 382 LIBSSL /usr/lib/libssl.a 383 LIBTERMCAP /usr/lib/libtermcap.a 384 LIBTERMLIB /usr/lib/libtermlib.a 385 LIBUSB /usr/lib/libusbhid.a 386 LIBUTIL /usr/lib/libutil.a 387 LIBWRAP /usr/lib/libwrap.a 388 LIBY /usr/lib/liby.a 389 LIBZ /usr/lib/libz.a 390 LIBARCH arch-dependent stuff 391 392STRIP The flag passed to the install program to cause the binary 393 to be stripped. 394 395SUBDIR A list of subdirectories that should be built as well. 396 Each of the targets will execute the same target in the 397 subdirectories. 398 399The include file <bsd.prog.mk> includes the file named "../Makefile.inc" 400if it exists, as well as the include file <bsd.man.mk>. 401 402Some simple examples: 403 404To build foo from foo.c with a manual page foo.1, use: 405 406 PROG= foo 407 408 .include <bsd.prog.mk> 409 410To build foo from foo.c with a manual page foo.2, add the line: 411 412 MAN= foo.2 413 414If foo does not have a manual page at all, add the line: 415 416 NOMAN= noman 417 418If foo has multiple source files, add the line: 419 420 SRCS= a.c b.c c.c d.c 421 422=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 423 424The include file <bsd.subdir.mk> contains the default targets for building 425subdirectories. It has the same eight targets as <bsd.prog.mk>: all, 426clean, cleandir, depend, includes, install, lint, and tags. For all of 427the directories listed in the variable SUBDIR, the specified directory 428will be visited and the target made. There is also a default target which 429allows the command "make subdir" where subdir is any directory listed in 430the variable SUBDIR. 431 432=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 433 434The include file <bsd.sys.mk> is used by <bsd.prog.mk> and 435<bsd.lib.mk>. It contains overrides that are used when building 436the OpenBSD source tree. For instance, if "PARALLEL" is defined by 437the program/library Makefile, it includes a set of rules for lex and 438yacc that allow multiple lex and yacc targets to be built in parallel. 439 440=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 441 442The include file <bsd.lib.mk> has support for building libraries. It has 443the same eight targets as <bsd.prog.mk>: all, clean, cleandir, depend, 444includes, install, lint, and tags. It has a limited number of suffixes, 445consistent with the current needs of the BSD tree. 446 447It sets/uses the following variables: 448 449LIB The name of the library to build. 450 451LIBDIR Target directory for libraries. 452 453LINTLIBDIR Target directory for lint libraries. 454 455LIBGRP Library group. 456 457LIBOWN Library owner. 458 459LIBMODE Library mode. 460 461LDADD Additional loader objects. 462 463MAN The manual pages to be installed (use a .1 - .9 suffix). 464 465SRCS List of source files to build the library. Suffix types 466 .s, .c, and .f are supported. Note, .s files are preferred 467 to .c files of the same name. (This is not the default for 468 versions of make.) 469 470The include file <bsd.lib.mk> includes the file named "../Makefile.inc" 471if it exists, as well as the include file <bsd.man.mk>. 472 473It has rules for building profiled objects; profiled libraries are 474built by default. 475 476Libraries are ranlib'd when made. 477 478=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 479 480The include file <bsd.lkm.mk> has support for building the LKM's. It has 481the same seven targets as <bsd.prog.mk>: all, clean, cleandir, depend, 482install, lint, and tags. In addition two targets are made available 483that is specific to the LKM's: load, unload. 484 485It sets/uses the following variables (in addition to the <bsd.prog.mk>'s): 486 487LKM LKM name to build. 488 489LKMGRP Module group. 490 491LKMOWN Module owner. 492 493LKMMODE Module mode. 494 495POSTINSTALL Program to pass with '-p' flag to the modload. 496 If not defined, 497 POSTINSTALL=${LKM}install 498 is assumed. 499 500The include file <bsd.lkm.mk> includes the file named "../Makefile.inc" 501if it exists, as well as the include file <bsd.man.mk>. 502