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