bsd.README revision 1.47
1# $NetBSD: bsd.README,v 1.47 1999/02/12 15:10:22 tv Exp $ 2# @(#)bsd.README 8.2 (Berkeley) 4/2/94 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 switched 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, and ".so" denotes a shared (position-independent) object. 60 61The following variables that control how things are made/installed that 62are not set by default. These should not be set by Makefiles; they're for 63the user to define in MAKECONF (see bsd.own.mk, below) or on the make(1) 64command line: 65 66BUILD If defined, 'make install' checks that the targets in the 67 source directories are up-to-date and remakes them if they 68 are out of date, instead of blindly trying to install 69 out of date or non-existant targets. 70 71UPDATE If defined, 'make install' only installs targets that are 72 more recently modified in the source directories that their 73 installed counterparts. 74 75MKCATPAGES If "no", don't build or install the catman pages. 76 77MKDOC If "no", don't build or install the documentation. 78 79MKINFO If "no", don't build or install Info documentation from 80 Texinfo source files. 81 82MKLINT If "no", don't build or install the lint libraries. 83 84MKMAN If "no", don't build or install the man or catman pages. 85 Also acts as "MKCATPAGES=no" 86 87MKNLS If "no", don't build or install the NLS files. 88 89MKOBJ If "no", don't create objdirs. 90 91MKPIC If "no", don't build or install shared libraries. 92 93MKPICINSTALL If "no", don't install the *_pic.a libraries. 94 95MKPROFILE If "no", don't build or install the profiling libraries. 96 97MKSHARE If "no", act as "MKCATPAGES=no MKDOC=no MKMAN=no MKNLS=no". 98 I.e, don't build documentation, man pages, NLS files, etc. 99 100=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 101 102The include file <sys.mk> has the default rules for all makes, in the BSD 103environment or otherwise. You probably don't want to touch this file. 104 105=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 106 107The include file <bsd.man.mk> handles installing manual pages and their 108links. 109 110It has a two targets: 111 112 maninstall: 113 Install the manual page sources and their links. 114 catinstall: 115 Install the preformatted manual pages and their links. 116 117It sets/uses the following variables: 118 119MANDIR Base path for manual installation. 120 121MANGRP Manual group. 122 123MANOWN Manual owner. 124 125MANMODE Manual mode. 126 127MANSUBDIR Subdirectory under the manual page section, i.e. "/vax" 128 or "/tahoe" for machine specific manual pages. 129 130MAN The manual pages to be installed (use a .1 - .9 suffix). 131 132MLINKS List of manual page links (using a .1 - .9 suffix). The 133 linked-to file must come first, the linked file second, 134 and there may be multiple pairs. The files are soft-linked. 135 136The include file <bsd.man.mk> includes a file named "../Makefile.inc" if 137it exists. 138 139=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 140 141The include file <bsd.own.mk> contains source tree configuration parameters, 142such as the owners, groups, etc. for both manual pages and binaries, and 143a few global "feature configuration" parameters. 144 145It has no targets. 146 147To get system-specific configuration parameters, bsd.own.mk will try to 148include the file specified by the "MAKECONF" variable. If MAKECONF is not 149set, or no such file exists, the system make configuration file, /etc/mk.conf 150is included. These files may define any of the variables described below. 151 152bsd.own.mk sets the following variables, if they are not already defined 153(defaults are in brackets): 154 155BSDSRCDIR The real path to the system sources, so that 'make obj' 156 will work correctly. [/usr/src] 157 158BSDOBJDIR The real path to the system 'obj' tree, so that 'make obj' 159 will work correctly. [/usr/obj] 160 161BINGRP Binary group. [wheel] 162 163BINOWN Binary owner. [root] 164 165BINMODE Binary mode. [555] 166 167NONBINMODE Mode for non-executable files. [444] 168 169MANDIR Base path for manual installation. [/usr/share/man/cat] 170 171MANGRP Manual group. [wheel] 172 173MANOWN Manual owner. [root] 174 175MANMODE Manual mode. [${NONBINMODE}] 176 177MANINSTALL Manual installation type: maninstall, catinstall, or both 178 179LIBDIR Base path for library installation. [/usr/lib] 180 181LINTLIBDIR Base path for lint(1) library installation. [/usr/libdata/lint] 182 183LIBGRP Library group. [${BINGRP}] 184 185LIBOWN Library owner. [${BINOWN}] 186 187LIBMODE Library mode. [${NONBINMODE}] 188 189DOCDIR Base path for system documentation (e.g. PSD, USD, etc.) 190 installation. [/usr/share/doc] 191 192DOCGRP Documentation group. [wheel] 193 194DOCOWN Documentation owner. [root] 195 196DOCMODE Documentation mode. [${NONBINMODE}] 197 198NLSDIR Base path for National Language Support files installation. 199 [/usr/share/nls] 200 201NLSGRP National Language Support files group. [wheel] 202 203NLSOWN National Language Support files owner. [root] 204 205NLSMODE National Language Support files mode. [${NONBINMODE}] 206 207STRIPFLAG The flag passed to the install program to cause the binary 208 to be stripped. This is to be used when building your 209 own install script so that the entire system can be made 210 stripped/not-stripped using a single knob. [-s] 211 212COPY The flag passed to the install program to cause the binary 213 to be copied rather than moved. This is to be used when 214 building our own install script so that the entire system 215 can either be installed with copies, or with moves using 216 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 223EXPORTABLE_SYSTEM 224 Do not build /usr/src/domestic, even if it is present. 225 226SKEY Compile in support for S/key authentication. [yes, set 227 unconditionally] 228 229KERBEROS Compile in support for Kerberos 4 authentication. 230 231KERBEROS5 Compile in support for Kerberos 5 authentication. 232 233MANZ Compress manual pages at installation time. 234 235SYS_INCLUDE Copy or symlink kernel include files into /usr/include. 236 Possible values are "symlinks" or "copies" (which is 237 the same as the variable being unset). 238 239NOPROFILE Do not build profiled versions of system libraries 240 241NOPIC Do not build PIC versions of system libraries, and 242 do not build shared libraries. [set if ${MACHINE_ARCH} 243 is "sparc64", unset otherwise.] 244 245NOLINT Do not build lint libraries. 246 247OBJECT_FMT Object file format. [set to "ELF" on ports that use 248 ELF -- currently if ${MACHINE_ARCH} is "alpha", "mips" 249 or "powerpc" or set to "a.out" on other ports]. 250 251 252bsd.own.mk is generally useful when building your own Makefiles so that 253they use the same default owners etc. as the rest of the tree. 254 255=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 256 257The include file <bsd.prog.mk> handles building programs from one or 258more source files, along with their manual pages. It has a limited number 259of suffixes, consistent with the current needs of the BSD tree. 260 261It has eight targets: 262 263 all: 264 build the program and its manual page 265 clean: 266 remove the program, any object files and the files a.out, 267 Errs, errs, mklog, and ${PROG}.core. 268 cleandir: 269 remove all of the files removed by the target clean, as 270 well as .depend, tags, and any manual pages. 271 `distclean' is a synonym for `cleandir'. 272 depend: 273 make the dependencies for the source files, and store 274 them in the file .depend. 275 includes: 276 install any header files. 277 install: 278 install the program and its manual pages; if the Makefile 279 does not itself define the target install, the targets 280 beforeinstall and afterinstall may also be used to cause 281 actions immediately before and after the install target 282 is executed. 283 lint: 284 run lint on the source files 285 tags: 286 create a tags file for the source files. 287 288It sets/uses the following variables: 289 290BINGRP Binary group. 291 292BINOWN Binary owner. 293 294BINMODE Binary mode. 295 296CLEANFILES Additional files to remove for the clean and cleandir targets. 297 298COPTS Additional flags to the compiler when creating C objects. 299 300CPPFLAGS Additional flags to the C pre-processor 301 302LDADD Additional loader objects. Usually used for libraries. 303 For example, to load with the compatibility and utility 304 libraries, use: 305 306 LDADD+=-lutil -lcompat 307 308LDFLAGS Additional loader flags. 309 310LINKS The list of binary links; should be full pathnames, the 311 linked-to file coming first, followed by the linked 312 file. The files are hard-linked. For example, to link 313 /bin/test and /bin/[, use: 314 315 LINKS= ${DESTDIR}/bin/test ${DESTDIR}/bin/[ 316 317SYMLINKS The list of symbolic links; should be full pathnames. 318 Syntax is identical to LINKS. Note that DESTDIR is not 319 automatically included in the link. 320 321MAN Manual pages (should end in .1 - .9). If no MAN variable is 322 defined, "MAN=${PROG}.1" is assumed. 323 324PROG The name of the program to build. If not supplied, nothing 325 is built. 326 327PROGNAME The name that the above program will be installed as, if 328 different from ${PROG}. 329 330SRCS List of source files to build the program. If SRCS is not 331 defined, it's assumed to be ${PROG}.c. 332 333DPADD Additional dependencies for the program. Usually used for 334 libraries. For example, to depend on the compatibility and 335 utility libraries use: 336 337 DPADD+=${LIBCOMPAT} ${LIBUTIL} 338 339 The following libraries are predefined for DPADD: 340 341 LIBCRT0?= ${DESTDIR}/usr/lib/crt0.o 342 LIBC?= ${DESTDIR}/usr/lib/libc.a 343 LIBC_PIC?= ${DESTDIR}/usr/lib/libc_pic.a 344 LIBCOMPAT?= ${DESTDIR}/usr/lib/libcompat.a 345 LIBCRYPT?= ${DESTDIR}/usr/lib/libcrypt.a 346 LIBCURSES?= ${DESTDIR}/usr/lib/libcurses.a 347 LIBDBM?= ${DESTDIR}/usr/lib/libdbm.a 348 LIBDES?= ${DESTDIR}/usr/lib/libdes.a 349 LIBEDIT?= ${DESTDIR}/usr/lib/libedit.a 350 LIBGCC?= ${DESTDIR}/usr/lib/libgcc.a 351 LIBGNUMALLOC?= ${DESTDIR}/usr/lib/libgnumalloc.a 352 LIBKDB?= ${DESTDIR}/usr/lib/libkdb.a 353 LIBKRB?= ${DESTDIR}/usr/lib/libkrb.a 354 LIBKVM?= ${DESTDIR}/usr/lib/libkvm.a 355 LIBL?= ${DESTDIR}/usr/lib/libl.a 356 LIBM?= ${DESTDIR}/usr/lib/libm.a 357 LIBMP?= ${DESTDIR}/usr/lib/libmp.a 358 LIBNTP?= ${DESTDIR}/usr/lib/libntp.a 359 LIBPC?= ${DESTDIR}/usr/lib/libpc.a 360 LIBPCAP?= ${DESTDIR}/usr/lib/libpcap.a 361 LIBPLOT?= ${DESTDIR}/usr/lib/libplot.a 362 LIBPOSIX?= ${DESTDIR}/usr/lib/libposix.a 363 LIBRESOLV?= ${DESTDIR}/usr/lib/libresolv.a 364 LIBRPCSVC?= ${DESTDIR}/usr/lib/librpcsvc.a 365 LIBSKEY?= ${DESTDIR}/usr/lib/libskey.a 366 LIBTERMCAP?= ${DESTDIR}/usr/lib/libtermcap.a 367 LIBTELNET?= ${DESTDIR}/usr/lib/libtelnet.a 368 LIBUTIL?= ${DESTDIR}/usr/lib/libutil.a 369 LIBWRAP?= ${DESTDIR}/usr/lib/libwrap.a 370 LIBY?= ${DESTDIR}/usr/lib/liby.a 371 LIBZ?= ${DESTDIR}/usr/lib/libz.a 372 373 374SHAREDSTRINGS If defined, a new .c.o rule is used that results in shared 375 strings, using xstr(1). Note that this will not work with 376 parallel makes. 377 378STRIP The flag passed to the install program to cause the binary 379 to be stripped. 380 381SUBDIR A list of subdirectories that should be built as well. 382 Each of the targets will execute the same target in the 383 subdirectories. 384 385SCRIPTS A list of interpreter scripts [file.{sh,csh,pl,awk,...}]. 386 These are installed exactly like programs. 387 388SCRIPTSNAME The name that the above program will be installed as, if 389 different from ${SCRIPTS}. These can be further specialized 390 by setting SCRIPTSNAME_<script>. 391 392FILES A list of files to install. The installation is controlled 393 by the FILESNAME, FILESOWN, FILESGRP, FILESMODE, FILESDIR 394 variables that can be further specialized by FILES<VAR>_<file> 395 396The include file <bsd.prog.mk> includes the file named "../Makefile.inc" 397if it exists, as well as the include file <bsd.man.mk>. 398 399Some simple examples: 400 401To build foo from foo.c with a manual page foo.1, use: 402 403 PROG= foo 404 405 .include <bsd.prog.mk> 406 407To build foo from foo.c with a manual page foo.2, add the line: 408 409 MAN= foo.2 410 411If foo does not have a manual page at all, add the line: 412 413 NOMAN= noman 414 415If foo has multiple source files, add the line: 416 417 SRCS= a.c b.c c.c d.c 418 419=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 420 421The include file <bsd.subdir.mk> contains the default targets for building 422subdirectories. It has the same eight targets as <bsd.prog.mk>: all, 423clean, cleandir, depend, includes, install, lint, and tags. For all of 424the directories listed in the variable SUBDIRS, the specified directory 425will be visited and the target made. There is also a default target which 426allows the command "make subdir" where subdir is any directory listed in 427the variable SUBDIRS. 428 429=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 430 431The include file <bsd.links.mk> handles the LINKS and SYMLINKS variables 432and is included from from bsd.lib.mk and bsd.prog.mk. 433 434=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 435 436The include file <bsd.files.mk> handles the FILES variables and is included 437from bsd.lib.mk and bsd.prog.mk. 438 439=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 440 441The include file <bsd.inc.mk> defines the includes target and uses two 442variables: 443 444INCS The list of include files 445 446INCSDIR The location to install the include files. 447 448=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 449 450The include file <bsd.kinc.mk> defines the many targets (includes, 451subdirectories, etc.), and is used by kernel makefiles to handle 452include file installation. It is intended to be included alone, by 453kernel Makefiles. Please see bsd.kinc.mk for more details, and keep 454the documentation in that file up to date. 455 456=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 457 458The include file <bsd.info.mk> is used to generate and install GNU Info 459documentation from respective Texinfo source files. It defines three 460implicit targets (.txi.info, .texi.info, and .texinfo.info), and uses the 461following variables: 462 463TEXINFO List of Texinfo source files. Info documentation will 464 consist of single files with the extension replaced by 465 .info. 466 467INFOFLAGS Flags to pass to makeinfo. [] 468 469INSTALL_INFO Name of install-info program. [install-info] 470 471MAKEINFO Name of makeinfo program. [makeinfo] 472 473=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 474 475The include file <bsd.sys.mk> is used by <bsd.prog.mk> and 476<bsd.lib.mk>. It contains overrides that are used when building 477the NetBSD source tree. For instance, if "PARALLEL" is defined by 478the program/library Makefile, it includes a set of rules for lex and 479yacc that allow multiple lex and yacc targets to be built in parallel. 480 481=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 482 483The include file <bsd.lib.mk> has support for building libraries. It has 484the same eight targets as <bsd.prog.mk>: all, clean, cleandir, depend, 485includes, install, lint, and tags. Additionally, it has a checkver target 486which checks for installed shared object libraries whose version is greater 487that the version of the source. It has a limited number of suffixes, 488consistent with the current needs of the BSD tree. 489 490It sets/uses the following variables: 491 492LIB The name of the library to build. 493 494LIBDIR Target directory for libraries. 495 496LINTLIBDIR Target directory for lint libraries. 497 498LIBGRP Library group. 499 500LIBOWN Library owner. 501 502LIBMODE Library mode. 503 504LDADD Additional loader objects. 505 506MAN The manual pages to be installed (use a .1 - .9 suffix). 507 508MKLINKLIB If "no", act as "MKPICINSTALL=no MKPROFILE=no". 509 Also: 510 - don't install the .a libraries 511 - don't install _pic.a libraries on PIC systems 512 - don't build .a libraries on PIC systems 513 - don't install the .so symlink on ELF systems 514 I.e, only install the shared library (and the .so.major 515 symlink on ELF). 516 517NOCHECKVER_<library> 518NOCHECKVER If set, disables checking for installed shared object 519 libraries with versions greater than the source. A 520 particular library name, without the "lib" prefix, may 521 be appended to the variable name to disable the check for 522 only that library. 523 524SRCS List of source files to build the library. Suffix types 525 .s, .c, and .f are supported. Note, .s files are preferred 526 to .c files of the same name. (This is not the default for 527 versions of make.) 528 529The include file <bsd.lib.mk> includes the file named "../Makefile.inc" 530if it exists, as well as the include file <bsd.man.mk>. 531 532It has rules for building profiled objects; profiled libraries are 533built by default. 534 535Libraries are ranlib'd when made. 536 537=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 538