pkgtools/bootstrap-mk-files/files/bsd.README

   1 #       $NetBSD: bsd.README,v 1.2 2009/12/30 20:46:22 abs Exp $
   2 #       @(#)bsd.README  8.2 (Berkeley) 4/2/94
   3
   4 This is the README file for the new make "include" files for the BSD
   5 source tree.  The files are installed in /usr/share/mk, and are, by
   6 convention, named with the suffix ".mk".
   7
   8 Note, this file is not intended to replace reading through the .mk
   9 files for anything tricky.
  10
  11 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  12
  13 RANDOM THINGS WORTH KNOWING:
  14
  15 The files are simply C-style #include files, and pretty much behave like
  16 you'd expect.  The syntax is slightly different in that a single '.' is
  17 used instead of the hash mark, i.e. ".include <bsd.prog.mk>".
  18
  19 One difference that will save you lots of debugging time is that inclusion
  20 of the file is normally done at the *end* of the Makefile.  The reason for
  21 this is because .mk files often modify variables and behavior based on the
  22 values of variables set in the Makefile.  To make this work, remember that
  23 the 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
  30 the command "make a" will echo "a".  To make things confusing, the SECOND
  31 variable 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
  39 the command "make b" will echo "bar".  This is for compatibility with the
  40 way the V7 make behaved.
  41
  42 It's fairly difficult to make the BSD .mk files work when you're building
  43 multiple programs in a single directory.  It's a lot easier to split up the
  44 programs than to deal with the problem.  Most of the agony comes from making
  45 the "obj" directory stuff work right, not because we switched to a new version
  46 of make.  So, don't get mad at us, figure out a better way to handle multiple
  47 architectures so we can quit using the symbolic link stuff.  (Imake doesn't
  48 count.)
  49
  50 The file .depend in the source directory is expected to contain dependencies
  51 for the source files.  This file is read automatically by make after reading
  52 the Makefile.
  53
  54 The variable DESTDIR works as before.  It's not set anywhere but will change
  55 the tree where the file gets installed.
  56
  57 The profiled libraries are no longer built in a different directory than
  58 the regular libraries.  A new suffix, ".po", is used to denote a profiled
  59 object, and ".so" denotes a shared (position-independent) object.
  60
  61 The following variables that control how things are made/installed that
  62 are not set by default. These should not be set by Makefiles; they're for
  63 the user to define in MAKECONF (see bsd.own.mk, below) or on the make(1)
  64 command line:
  65
  66 BUILD           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-existent targets.
  70
  71 UPDATE          If defined, 'make install' only installs targets that are
  72                 more recently modified in the source directories that their
  73                 installed counterparts.
  74
  75 UNPRIVILEGED    If defined, don't set the owner/group/mode when installing
  76                 files or directories.  This allows a non-root "make install".
  77
  78 MKCATPAGES      If "no", don't build or install the catman pages.
  79
  80 MKDOC           If "no", don't build or install the documentation.
  81
  82 MKINFO          If "no", don't build or install Info documentation from
  83                 Texinfo source files.
  84
  85 MKLINT          If "no", don't build or install the lint libraries.
  86
  87 MKMAN           If "no", don't build or install the man or catman pages.
  88                 Also acts as "MKCATPAGES=no"
  89
  90 MKNLS           If "no", don't build or install the NLS files and locale
  91                 definition files.
  92
  93 MKOBJ           If "no", don't enable the rule which creates objdirs.
  94                 "yes" by default.
  95
  96 MKOBJDIRS       If "no", don't create objdirs during a "make build".
  97                 "no" by default.
  98
  99 MKPIC           If "no", don't build or install shared libraries.
 100
 101 MKPICINSTALL    If "no", don't install the *_pic.a libraries.
 102
 103 MKPROFILE       If "no", don't build or install the profiling libraries.
 104
 105 MKSHARE         If "no", act as "MKCATPAGES=no MKDOC=no MKINFO=no MKMAN=no
 106                 MKNLS=no".  I.e, don't build catman pages, documentation,
 107                 Info documentation, man pages, NLS files, ...
 108
 109 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 110
 111 The include file <sys.mk> has the default rules for all makes, in the BSD
 112 environment or otherwise.  You probably don't want to touch this file.
 113 If you intend to run a cross build, you will need to supply the following
 114 host tools, and configure the following variables properly:
 115
 116 OBJCOPY         objcopy - copy and translate object files
 117
 118 STRIP           strip - Discard symbols from object files
 119
 120 CONFIG          config - build kernel compilation directories
 121
 122 RPCGEN          rpcgen - Remote Procedure Call (RPC) protocol compiler
 123
 124 MKLOCALE        mklocale - make LC_CTYPE locale files
 125
 126 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 127
 128 The include file <bsd.man.mk> handles installing manual pages and their
 129 links.
 130
 131 It has a two targets:
 132
 133         maninstall:
 134                 Install the manual page sources and their links.
 135         catinstall:
 136                 Install the preformatted manual pages and their links.
 137
 138 It sets/uses the following variables:
 139
 140 MANDIR          Base path for manual installation.
 141
 142 MANGRP          Manual group.
 143
 144 MANOWN          Manual owner.
 145
 146 MANMODE         Manual mode.
 147
 148 MANSUBDIR       Subdirectory under the manual page section, i.e. "/vax"
 149                 or "/tahoe" for machine specific manual pages.
 150
 151 MAN             The manual pages to be installed (use a .1 - .9 suffix).
 152
 153 MLINKS          List of manual page links (using a .1 - .9 suffix).  The
 154                 linked-to file must come first, the linked file second,
 155                 and there may be multiple pairs.  The files are soft-linked.
 156
 157 The include file <bsd.man.mk> includes a file named "../Makefile.inc" if
 158 it exists.
 159
 160 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 161
 162 The include file <bsd.own.mk> contains source tree configuration parameters,
 163 such as the owners, groups, etc. for both manual pages and binaries, and
 164 a few global "feature configuration" parameters.
 165
 166 It has no targets.
 167
 168 To get system-specific configuration parameters, bsd.own.mk will try to
 169 include the file specified by the "MAKECONF" variable.  If MAKECONF is not
 170 set, or no such file exists, the system make configuration file, /etc/mk.conf
 171 is included.  These files may define any of the variables described below.
 172
 173 bsd.own.mk sets the following variables, if they are not already defined
 174 (defaults are in brackets):
 175
 176 BSDSRCDIR       The real path to the system sources, so that 'make obj'
 177                 will work correctly. [/usr/src]
 178
 179 BSDOBJDIR       The real path to the system 'obj' tree, so that 'make obj'
 180                 will work correctly. [/usr/obj]
 181
 182 BINGRP          Binary group. [wheel]
 183
 184 BINOWN          Binary owner. [root]
 185
 186 BINMODE         Binary mode. [555]
 187
 188 NONBINMODE      Mode for non-executable files. [444]
 189
 190 MANDIR          Base path for manual installation. [/usr/share/man/cat]
 191
 192 MANGRP          Manual group. [wheel]
 193
 194 MANOWN          Manual owner. [root]
 195
 196 MANMODE         Manual mode. [${NONBINMODE}]
 197
 198 MANINSTALL      Manual installation type: maninstall, catinstall, or both
 199
 200 LDSTATIC        Control program linking; if set blank, link everything
 201                 dynamically. If set to "-static", link everything statically.
 202                 If not set, programs link according to their makefile.
 203
 204 LIBDIR          Base path for library installation. [/usr/lib]
 205
 206 LINTLIBDIR      Base path for lint(1) library installation. [/usr/libdata/lint]
 207
 208 LIBGRP          Library group. [${BINGRP}]
 209
 210 LIBOWN          Library owner. [${BINOWN}]
 211
 212 LIBMODE         Library mode. [${NONBINMODE}]
 213
 214 DOCDIR          Base path for system documentation (e.g. PSD, USD, etc.)
 215                 installation. [/usr/share/doc]
 216
 217 HTMLDOCDIR      Base path for html system documentation installation.
 218                 [/usr/share/doc/html]
 219
 220 DOCGRP          Documentation group. [wheel]
 221
 222 DOCOWN          Documentation owner. [root]
 223
 224 DOCMODE         Documentation mode. [${NONBINMODE}]
 225
 226 NLSDIR          Base path for National Language Support files installation.
 227                 [/usr/share/nls]
 228
 229 NLSGRP          National Language Support files group. [wheel]
 230
 231 NLSOWN          National Language Support files owner. [root]
 232
 233 NLSMODE         National Language Support files mode. [${NONBINMODE}]
 234
 235 STRIPFLAG       The flag passed to the install program to cause the binary
 236                 to be stripped.  This is to be used when building your
 237                 own install script so that the entire system can be made
 238                 stripped/not-stripped using a single knob. [-s]
 239
 240 COPY            The flag passed to the install program to cause the binary
 241                 to be copied rather than moved.  This is to be used when
 242                 building our own install script so that the entire system
 243                 can either be installed with copies, or with moves using
 244                 a single knob. [-c]
 245
 246 Additionally, the following variables may be set by bsd.own.mk or in a
 247 make configuration file to modify the behaviour of the system build
 248 process (default values are in brackets along with comments, if set by
 249 bsd.own.mk):
 250
 251 MKCRYPTO        If set to "no", no cryptography support will be built
 252                 into the system.  Defaults to "yes".
 253
 254 NOCRYPTO        If set, it is equivalent to setting MKCRYPTO to "no".
 255
 256 MKCRYPTO_IDEA   If set to "yes", IDEA support will be built into
 257                 libcrypto_idea.a.  Defaults to "no".
 258
 259 MKCRYPTO_RC5    If set to "yes", RC5 support will be built into
 260                 libcrypto_rc5.a.  Defaults to "no".
 261
 262 MKKERBEROS      If set to "no", disables building Kerberos (v4 or v5)
 263                 support into various system utilities that support it.
 264                 Defaults to "yes".  NOTE: This does not affect the
 265                 building of the Kerberos libraries or infrastructure
 266                 programs themselves.  To completely disable Kerberos,
 267                 set MKCRYPTO to "no".
 268
 269 NOKERBEROS      If set, it is equivalent to setting MKKERBEROS to "no".
 270
 271 SKEY            Compile in support for S/key authentication. [yes, set
 272                 unconditionally]
 273
 274 MANZ            Compress manual pages at installation time.
 275
 276 SYS_INCLUDE     Copy or symlink kernel include files into /usr/include.
 277                 Possible values are "symlinks" or "copies" (which is
 278                 the same as the variable being unset).
 279
 280 NOPROFILE       Do not build profiled versions of system libraries
 281
 282 NOPIC           Do not build PIC versions of system libraries, and
 283                 do not build shared libraries.  [set if ${MACHINE_ARCH}
 284                 is "sh3" and ${OBJECT_FMT} is "COFF", unset otherwise.]
 285
 286 NOLINT          Do not build lint libraries.
 287
 288 OBJECT_FMT      Object file format. [set to "ELF" on architectures that
 289                 use ELF -- currently if ${MACHINE_ARCH} is "alpha",
 290                 "mipsel", "mipseb", "powerpc", "sparc", "sparc64",
 291                 "i386" and some m68k machines, or set to "a.out" on
 292                 other architectures].
 293
 294 MKSOFTFLOAT     If "yes", build with options to enable the compiler to
 295                 generate output containing library calls for floating
 296                 point and possibly soft-float library support.  Defaults
 297                 to "no".
 298
 299 bsd.own.mk is generally useful when building your own Makefiles so that
 300 they use the same default owners etc. as the rest of the tree.
 301
 302 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 303
 304 The include file <bsd.prog.mk> handles building programs from one or
 305 more source files, along with their manual pages.  It has a limited number
 306 of suffixes, consistent with the current needs of the BSD tree.
 307
 308 It has eight targets:
 309
 310         all:
 311                 build the program and its manual page
 312         clean:
 313                 remove the program, any object files and the files a.out,
 314                 Errs, errs, mklog, and ${PROG}.core.
 315         cleandir:
 316                 remove all of the files removed by the target clean, as
 317                 well as .depend, tags, and any manual pages.
 318                 `distclean' is a synonym for `cleandir'.
 319         depend:
 320                 make the dependencies for the source files, and store
 321                 them in the file .depend.
 322         includes:
 323                 install any header files.
 324         install:
 325                 install the program and its manual pages; if the Makefile
 326                 does not itself define the target install, the targets
 327                 beforeinstall and afterinstall may also be used to cause
 328                 actions immediately before and after the install target
 329                 is executed.
 330         lint:
 331                 run lint on the source files
 332         tags:
 333                 create a tags file for the source files.
 334
 335 It sets/uses the following variables:
 336
 337 BINGRP          Binary group.
 338
 339 BINOWN          Binary owner.
 340
 341 BINMODE         Binary mode.
 342
 343 CLEANFILES      Additional files to remove for the clean and cleandir targets.
 344
 345 COPTS           Additional flags to the compiler when creating C objects.
 346
 347 CPPFLAGS        Additional flags to the C pre-processor
 348
 349 LDADD           Additional loader objects.  Usually used for libraries.
 350                 For example, to load with the compatibility and utility
 351                 libraries, use:
 352
 353                         LDADD+=-lutil -lcompat
 354
 355 LDFLAGS         Additional loader flags.
 356
 357 LINKS           The list of binary links; should be full pathnames, the
 358                 linked-to file coming first, followed by the linked
 359                 file.  The files are hard-linked.  For example, to link
 360                 /bin/test and /bin/[, use:
 361
 362                         LINKS=  ${DESTDIR}/bin/test ${DESTDIR}/bin/[
 363
 364 SYMLINKS        The list of symbolic links; should be full pathnames.
 365                 Syntax is identical to LINKS. Note that DESTDIR is not
 366                 automatically included in the link.
 367
 368 MAN             Manual pages (should end in .1 - .9).  If no MAN variable is
 369                 defined, "MAN=${PROG}.1" is assumed.
 370
 371 PROG            The name of the program to build.  If not supplied, nothing
 372                 is built.
 373
 374 PROGNAME        The name that the above program will be installed as, if
 375                 different from ${PROG}.
 376
 377 SRCS            List of source files to build the program.  If SRCS is not
 378                 defined, it's assumed to be ${PROG}.c.
 379
 380 DPADD           Additional dependencies for the program.  Usually used for
 381                 libraries.  For example, to depend on the compatibility and
 382                 utility libraries use:
 383
 384                         DPADD+=${LIBCOMPAT} ${LIBUTIL}
 385
 386                 The following libraries are predefined for DPADD:
 387
 388                 LIBCRT0?=       ${DESTDIR}/usr/lib/crt0.o
 389                 LIBC?=          ${DESTDIR}/usr/lib/libc.a
 390                 LIBC_PIC?=      ${DESTDIR}/usr/lib/libc_pic.a
 391                 LIBCOMPAT?=     ${DESTDIR}/usr/lib/libcompat.a
 392                 LIBCRYPT?=      ${DESTDIR}/usr/lib/libcrypt.a
 393                 LIBCURSES?=     ${DESTDIR}/usr/lib/libcurses.a
 394                 LIBDBM?=        ${DESTDIR}/usr/lib/libdbm.a
 395                 LIBDES?=        ${DESTDIR}/usr/lib/libdes.a
 396                 LIBEDIT?=       ${DESTDIR}/usr/lib/libedit.a
 397                 LIBFORM?=       ${DESTDIR}/usr/lib/libform.a
 398                 LIBGCC?=        ${DESTDIR}/usr/lib/libgcc.a
 399                 LIBGNUMALLOC?=  ${DESTDIR}/usr/lib/libgnumalloc.a
 400                 LIBINTL?=       ${DESTDIR}/usr/lib/libintl.a
 401                 LIBIPSEC?=      ${DESTDIR}/usr/lib/libipsec.a
 402                 LIBKDB?=        ${DESTDIR}/usr/lib/libkdb.a
 403                 LIBKRB?=        ${DESTDIR}/usr/lib/libkrb.a
 404                 LIBKVM?=        ${DESTDIR}/usr/lib/libkvm.a
 405                 LIBL?=          ${DESTDIR}/usr/lib/libl.a
 406                 LIBM?=          ${DESTDIR}/usr/lib/libm.a
 407                 LIBMENU?=       ${DESTDIR}/usr/lib/libmenu.a
 408                 LIBMP?=         ${DESTDIR}/usr/lib/libmp.a
 409                 LIBNTP?=        ${DESTDIR}/usr/lib/libntp.a
 410                 LIBPC?=         ${DESTDIR}/usr/lib/libpc.a
 411                 LIBPCAP?=       ${DESTDIR}/usr/lib/libpcap.a
 412                 LIBPLOT?=       ${DESTDIR}/usr/lib/libplot.a
 413                 LIBPOSIX?=      ${DESTDIR}/usr/lib/libposix.a
 414                 LIBRESOLV?=     ${DESTDIR}/usr/lib/libresolv.a
 415                 LIBRPCSVC?=     ${DESTDIR}/usr/lib/librpcsvc.a
 416                 LIBSKEY?=       ${DESTDIR}/usr/lib/libskey.a
 417                 LIBTERMCAP?=    ${DESTDIR}/usr/lib/libtermcap.a
 418                 LIBTELNET?=     ${DESTDIR}/usr/lib/libtelnet.a
 419                 LIBUTIL?=       ${DESTDIR}/usr/lib/libutil.a
 420                 LIBWRAP?=       ${DESTDIR}/usr/lib/libwrap.a
 421                 LIBY?=          ${DESTDIR}/usr/lib/liby.a
 422                 LIBZ?=          ${DESTDIR}/usr/lib/libz.a
 423
 424
 425 SHAREDSTRINGS   If defined, a new .c.o rule is used that results in shared
 426                 strings, using xstr(1). Note that this will not work with
 427                 parallel makes.
 428
 429 STRIPFLAG       The flag passed to the install program to cause the binary
 430                 to be stripped.
 431
 432 SUBDIR          A list of subdirectories that should be built as well.
 433                 Each of the targets will execute the same target in the
 434                 subdirectories.
 435
 436 SCRIPTS         A list of interpreter scripts [file.{sh,csh,pl,awk,...}].
 437                 These are installed exactly like programs.
 438
 439 SCRIPTSNAME     The name that the above program will be installed as, if
 440                 different from ${SCRIPTS}. These can be further specialized
 441                 by setting SCRIPTSNAME_<script>.
 442
 443 FILES           A list of files to install. The installation is controlled
 444                 by the FILESNAME, FILESOWN, FILESGRP, FILESMODE, FILESDIR
 445                 variables that can be further specialized by FILES<VAR>_<file>
 446
 447 The include file <bsd.prog.mk> includes the file named "../Makefile.inc"
 448 if it exists, as well as the include file <bsd.man.mk>.
 449
 450 Some simple examples:
 451
 452 To build foo from foo.c with a manual page foo.1, use:
 453
 454         PROG=   foo
 455
 456         .include <bsd.prog.mk>
 457
 458 To build foo from foo.c with a manual page foo.2, add the line:
 459
 460         MAN=    foo.2
 461
 462 If foo does not have a manual page at all, add the line:
 463
 464         MKMAN=  no
 465
 466 If foo has multiple source files, add the line:
 467
 468         SRCS=   a.c b.c c.c d.c
 469
 470 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 471
 472 The include file <bsd.subdir.mk> contains the default targets for building
 473 subdirectories.  It has the same eight targets as <bsd.prog.mk>: all,
 474 clean, cleandir, depend, includes, install, lint, and tags.  For all of
 475 the directories listed in the variable SUBDIR, the specified directory
 476 will be visited and the target made.  There is also a default target which
 477 allows the command "make subdir" where subdir is any directory listed in
 478 the variable SUBDIR.
 479
 480 As a special case, the use of a token .WAIT as an entry in SUBDIR acts
 481 as a synchronization barrier when multiple make jobs are run; subdirs
 482 before the .WAIT must complete before any subdirs after .WAIT are
 483 started.  See make(1) for some caveats on use of .WAIT and other
 484 special sources.
 485
 486 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 487
 488 The include file <bsd.links.mk> handles the LINKS and SYMLINKS variables
 489 and is included from from bsd.lib.mk and bsd.prog.mk.
 490
 491 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 492
 493 The include file <bsd.files.mk> handles the FILES variables and is included
 494 from bsd.lib.mk and bsd.prog.mk.
 495
 496 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 497
 498 The include file <bsd.inc.mk> defines the includes target and uses two
 499 variables:
 500
 501 INCS    The list of include files
 502
 503 INCSDIR The location to install the include files.
 504
 505 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 506
 507 The include file <bsd.kinc.mk> defines the many targets (includes,
 508 subdirectories, etc.), and is used by kernel makefiles to handle
 509 include file installation.  It is intended to be included alone, by
 510 kernel Makefiles.  Please see bsd.kinc.mk for more details, and keep
 511 the documentation in that file up to date.
 512
 513 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 514
 515 The include file <bsd.info.mk> is used to generate and install GNU Info
 516 documentation from respective Texinfo source files.  It defines three
 517 implicit targets (.txi.info, .texi.info, and .texinfo.info), and uses the
 518 following variables:
 519
 520 TEXINFO         List of Texinfo source files.  Info documentation will
 521                 consist of single files with the extension replaced by
 522                 .info.
 523
 524 INFOFLAGS       Flags to pass to makeinfo.  []
 525
 526 INSTALL_INFO    Name of install-info program.  [install-info]
 527
 528 MAKEINFO        Name of makeinfo program.  [makeinfo]
 529
 530 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 531
 532 The include file <bsd.sys.mk> is used by <bsd.prog.mk> and
 533 <bsd.lib.mk>.  It contains overrides that are used when building
 534 the NetBSD source tree.  For instance, if "PARALLEL" is defined by
 535 the program/library Makefile, it includes a set of rules for lex and
 536 yacc that allow multiple lex and yacc targets to be built in parallel.
 537
 538 Other variables of note (incomplete list):
 539
 540 WARNS           Crank up gcc warning options; WARNS=1 and WARNS=2 are the two
 541                 distinct levels.
 542
 543 FORMAT_AUDIT    If FORMAT_AUDIT is set, and WFORMAT is set and > 1, turn on
 544 WFORMAT         -Wnetbsd-format-audit for extra-stringent format checking.
 545                 WFORMAT belongs in individual makefiles and/or
 546                 Makefile.inc files.  (set WFORMAT=1 in individual
 547                 makefiles if a program is not security critical and is
 548                 doing bizarre things with format strings which would
 549                 be even uglier if rewritten) FORMAT_AUDIT should go in
 550                 mk.conf if you're doing format-string auditing.
 551                 FORMAT_AUDIT may go away in time.
 552
 553 =-=-=-=-=   bsd.lib.mk   =-=-=-=-=
 554
 555 The include file <bsd.lib.mk> has support for building libraries.  It has
 556 the same eight targets as <bsd.prog.mk>: all, clean, cleandir, depend,
 557 includes, install, lint, and tags.  Additionally, it has a checkver target
 558 which checks for installed shared object libraries whose version is greater
 559 that the version of the source. It has a limited number of suffixes,
 560 consistent with the current needs of the BSD tree.
 561
 562 It sets/uses the following variables:
 563
 564 LIB             The name of the library to build.
 565
 566 LIBDIR          Target directory for libraries.
 567
 568 SHLIB_MAJOR
 569 SHLIB_MINOR
 570 SHLIB_TEENY     Major, minor, and teeny version numbers of shared library
 571
 572 LINTLIBDIR      Target directory for lint libraries.
 573
 574 LIBGRP          Library group.
 575
 576 LIBOWN          Library owner.
 577
 578 LIBMODE         Library mode.
 579
 580 LDADD           Additional loader objects.
 581
 582 MAN             The manual pages to be installed (use a .1 - .9 suffix).
 583
 584 MKLINKLIB       If "no", act as "MKPICINSTALL=no MKPROFILE=no".
 585                 Also:
 586                         - don't install the .a libraries
 587                         - don't install _pic.a libraries on PIC systems
 588                         - don't build .a libraries on PIC systems
 589                         - don't install the .so symlink on ELF systems
 590                 I.e, only install the shared library (and the .so.major
 591                 symlink on ELF).
 592
 593 MKPICLIB        If "no", don't build _pic.a libraries, and build the
 594                 shared object libraries from the .a libraries.  A
 595                 symlink is installed in ${DESTDIR}/usr/lib for the
 596                 _pic.a library pointing to the .a library.
 597
 598 NOCHECKVER_<library>
 599 NOCHECKVER      If set, disables checking for installed shared object
 600                 libraries with versions greater than the source.  A
 601                 particular library name, without the "lib" prefix, may
 602                 be appended to the variable name to disable the check for
 603                 only that library.
 604
 605 SRCS            List of source files to build the library.  Suffix types
 606                 .s, .c, and .f are supported.  Note, .s files are preferred
 607                 to .c files of the same name.  (This is not the default for
 608                 versions of make.)
 609
 610 The include file <bsd.lib.mk> includes the file named "../Makefile.inc"
 611 if it exists, as well as the include file <bsd.man.mk>.
 612
 613 It has rules for building profiled objects; profiled libraries are
 614 built by default.
 615
 616 Libraries are ranlib'd when made.
 617
 618 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 619
 620 The include file <bsd.obj.mk> defines targets related to the creation
 621 and use of separated object and source directories.
 622
 623 If an environment variable named MAKEOBJDIRPREFIX is set, make(1) uses
 624 ${MAKEOBJDIRPREFIX}${.CURDIR} as the name of the object directory if
 625 it exists.  Otherwise make(1) looks for the existence of a
 626 subdirectory (or a symlink to a directory) of the source directory
 627 into which built targets should be placed.  If an environment variable
 628 named MAKEOBJDIR is set, make(1) uses its value as the name of the
 629 object directory; failing that, make first looks for a subdirectory
 630 named "obj.${MACHINE}", and if that doesn't exist, it looks for "obj".
 631
 632 Object directories are not created automatically by make(1) if they
 633 don't exist; you need to run a separate "make obj".  (This will happen
 634 during a top-level build if "MKOBJDIRS" is set to a value other than
 635 "no").  When the source directory is a subdirectory of ${BSDSRCDIR} --
 636 and this is determined by a simple string prefix comparison -- object
 637 directories are created in a separate object directory tree, and a
 638 symlink to the object directory in that tree is created in the source
 639 directory; otherwise, "make obj" assumes that you're not in the main
 640 source tree and that it's not safe to use a separate object tree.
 641
 642 Several variables used by <bsd.obj.mk> control exactly what
 643 directories and links get created during a "make obj":
 644
 645 MAKEOBJDIR      If set, this is the component name of the object
 646                 directory.
 647
 648 OBJMACHINE      If this is set but MAKEOBJDIR is not set, creates
 649                 object directories or links named "obj.${MACHINE}";
 650                 otherwise, just creates ones named "obj".
 651
 652 USR_OBJMACHINE  If set, and the current directory is a subdirectory of
 653                 ${BSDSRCDIR}, create object directory in the
 654                 corresponding subdirectory of ${BSDOBJDIR}.${MACHINE};
 655                 otherwise, create it in the corresponding subdirectory
 656                 of ${BSDOBJDIR}
 657
 658 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 659
 660 The include file <bsd.kernobj.mk> defines variables related to the
 661 location of kernel sources and object directories.
 662
 663 KERNSRCDIR      Is the location of the top of the kernel src.
 664                 It defaults to ${BSDSRCDIR}/sys, but the top-level
 665                 Makefile.inc sets it to ${ABSTOP}/sys (ABSTOP is the
 666                 absolute path to the directory where the top-level
 667                 Makefile.inc was found.
 668
 669 KERNARCHDIR     Is the location of the machine dependent kernel
 670                 sources.  It defaults to arch/${MACHINE}
 671
 672 KERNCONFDIR     Is where the configuration files for kernels are
 673                 found; default is ${KERNSRCDIR}/${KERNARCHDIR}/conf.
 674
 675 KERNOBJDIR      Is the kernel build directory.  The kernel GENERIC for
 676                 instance will be compiled in ${KERNOBJDIR}/GENERIC.
 677                 The default value is
 678                 ${MAKEOBJDIRPREFIX}${KERNSRCDIR}/${KERNARCHDIR}/compile
 679                 if it exists or the target 'obj' is being made.
 680                 Otherwise the default is
 681                 ${KERNSRCDIR}/${KERNARCHDIR}/compile.
 682
 683 It is important that Makefiles (such as those under src/distrib) that
 684 wish to find compiled kernels use bsd.kernobj.mk and ${KERNOBJDIR}
 685 rather than make assumptions about the location of the compiled kernel.
 686
 687 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=