share/mk/bsd.README

   1 #       $NetBSD: bsd.README,v 1.250 2009/05/12 18:07:54 plunky Exp $
   2 #       @(#)bsd.README  8.2 (Berkeley) 4/2/94
   3
   4 This is the README file for the make "include" files for the NetBSD
   5 source tree.  The files are installed in /usr/share/mk, and are,
   6 by 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 There are various make variables used during the build.
  62
  63 Many variables support a (case sensitive) value of "no" or "yes",
  64 and are tested with  ${VAR} == "no"  and  ${VAR} != "no" .
  65
  66
  67 The basic rule for the variable naming scheme is as follows:
  68
  69 HOST_xxx        A command that runs on the host machine regardless of
  70                 whether or not the system is being cross compiled, or
  71                 flags for such a command.
  72
  73 MKxxx           Can be set to "no" to disable functionality, or
  74                 "yes" to enable it.
  75                 Usually defaults to "yes", although some variables
  76                 default to "no".
  77                 Due to make(1) implementation issues, if a temporary
  78                 command-line override of a mk.conf(5) or <bsd.own.mk>
  79                 setting is required whilst still honoring a particular
  80                 Makefile's setting of MKxxx, use
  81                         env MKxxx=value make
  82                 instead of
  83                         make MKxxx=value
  84
  85 NOxxx           If defined, disables a feature.
  86                 Not intended for users.
  87                 This is to allow Makefiles to disable functionality
  88                 that they don't support (such as missing man pages).
  89                 NOxxx variables must be defined before <bsd.own.mk>
  90                 is included.
  91
  92 TOOL_xxx        A tool that is provided as part of the USETOOLS
  93                 framework.  When not using the USETOOLS framework,
  94                 TOOL_xxx variables should refer to tools that are
  95                 already installed on the host system.
  96
  97 The following variables that control how things are made/installed that
  98 are not set by default. These should not be set by Makefiles; they're for
  99 the user to define in MAKECONF (see <bsd.own.mk>, below, or mk.conf(5))
 100 or on the make(1) command line:
 101
 102 BUILD           If defined, 'make install' checks that the targets in the
 103                 source directories are up-to-date and remakes them if they
 104                 are out of date, instead of blindly trying to install
 105                 out of date or non-existent targets.
 106
 107 MAKEVERBOSE     Control how "verbose" the standard make(1) rules are.
 108                 Default: 2
 109                 Supported values:
 110                     0   Minimal output ("quiet")
 111                     1   Describe what is occurring
 112                     2   Describe what is occurring and echo the actual command
 113                     3   Ignore the effect of the "@" prefix in make commands
 114                     4   Trace shell commands using the shell's -x flag
 115
 116 MKATF           If "no", don't build libatf-c, libatf-c++ libraries associated
 117                 with the Automated Testing Framework (ATF).
 118                 Default: yes
 119
 120 MKBFD           If "no", don't build libbfd, libiberty, or any of the things
 121                 that depend on them (binutils/gas/ld, gdb, dbsym, mdsetimage).
 122                 Default: yes
 123
 124 MKCATPAGES      If "no", don't build or install the catman pages.
 125                 Default: yes
 126
 127 MKCOMPAT        If "no", don't build or install the src/compat.
 128                 Default: yes on amd64/sparc64, no elsewhere.
 129
 130 MKCOMPLEX       If "no", don't build libm support for <complex.h>
 131                 Default: yes
 132
 133 MKCRYPTO        If "no", no cryptography support will be built into the system,
 134                 and also acts as "MKKERBEROS=no".
 135                 Default: yes
 136
 137 MKCRYPTO_IDEA   If not "no", IDEA support will be built into libcrypto_idea.a.
 138                 Default: no
 139
 140 MKCRYPTO_MDC2   If not "no", MDC2 support will be built into libcrypto_mdc2.a
 141                 Default: no
 142
 143 MKCRYPTO_RC5    If not "no", RC5 support will be built into libcrypto_rc5.a.
 144                 Default: no
 145
 146 MKCVS           If "no", don't build or install cvs(1).
 147                 Default: yes
 148
 149 MKDEBUG         If "no", don't build and install separate debugging symbols
 150                 into /usr/libdata/debug.
 151                 Default: no
 152
 153 MKDEBUGLIB      Build *_g.a debugging libraries, which are compiled
 154                 with -DDEBUG.
 155                 Default: no
 156
 157 MKDOC           If "no", don't build or install the documentation.
 158                 Default: yes
 159
 160 MKDYNAMICROOT   If "no", build programs in /bin and /sbin statically,
 161                 don't install certain libraries in /lib, and don't
 162                 install the shared linker into /libexec.
 163                 Default: yes
 164
 165 MKGCC           If "no", don't build gcc(1) or any of the GCC-related
 166                 libraries (libgcc, libobjc, libstdc++).
 167                 Default: yes
 168
 169 MKGCCCMDS       If "no", don't build gcc(1), but do build the GCC-related
 170                 libraries (libgcc, libobjc, libstdc++).
 171                 Default: yes
 172
 173 MKGDB           If "no", don't build gdb(1).
 174                 Default: yes
 175
 176 MKHESIOD        If "no", disables building of Hesiod infrastructure
 177                 (libraries and support programs).
 178                 Default: yes
 179
 180 MKHOSTOBJ       If not "no", for programs intended to be run on the compile
 181                 host, the name, release, and architecture of the host
 182                 operating system will be suffixed to the name of the object
 183                 directory created by "make obj".
 184                 Default: no
 185
 186 MKHTML          If "no", don't build or install the HTML man pages.
 187                 Default: yes
 188
 189 MKIEEEFP        If "no", don't add code for IEEE754/IEC60559 conformance.
 190                 Has no effect on most platforms.
 191                 Default: yes
 192
 193 MKSTRIPIDENT    Strip the RCS IDs from program binaries and shared libraries.
 194                 Default: no
 195
 196 MKINET6         If "no", disables building of INET6 (IPv6) infrastructure
 197                 (libraries and support programs).
 198                 Default: yes
 199
 200 MKINFO          If "no", don't build or install Info documentation from
 201                 Texinfo source files.
 202                 Default: yes
 203
 204 MKIPFILTER      If "no", don't build or install the IP Filter programs and LKM.
 205                 Default: yes
 206
 207 MKISCSI         If "no", don't build or install iSCSI library or applications
 208                 (depends on libpthread.)
 209                 Default: yes
 210
 211 MKKERBEROS      If "no", disables building of Kerberos v5
 212                 infrastructure (libraries and support programs).
 213                 Default: yes
 214
 215 MKLDAP          If "no", disables building of LDAP infrastructure
 216                 (libraries and support programs).
 217                 Default: yes
 218
 219 MKLINKLIB       If "no", act as "MKLINT=no MKPICINSTALL=no MKPROFILE=no".
 220                 Also:
 221                         - don't install the .a libraries
 222                         - don't install _pic.a libraries on PIC systems
 223                         - don't build .a libraries on PIC systems
 224                         - don't install the .so symlink on ELF systems
 225                 I.e, only install the shared library (and the .so.major
 226                 symlink on ELF).
 227                 Default: yes
 228
 229 MKLINT          If "no", don't build or install the lint libraries.
 230                 Default: yes
 231
 232 MKLVM           If "no", don't build or install teh logical volume manager
 233                 and device mapper tools and libraries
 234                 Default: no
 235
 236 MKMAN           If "no", don't build or install the man or catman pages,
 237                 and also acts as "MKCATPAGES=no MKHTML=no".
 238                 Default: yes
 239
 240 MKMANZ          If not "no", compress manual pages at installation time.
 241                 Default: no
 242
 243 MKNLS           If "no", don't build or install the NLS files and locale
 244                 definition files.
 245                 Default: yes
 246
 247 MKOBJ           If "no", don't enable the rule which creates objdirs,
 248                 and also acts as "MKOBJDIRS=no".
 249                 Default: yes
 250
 251 MKOBJDIRS       If "no", don't create objdirs during a "make build".
 252                 Default: no
 253
 254 MKPAM           If "no", disables building of PAM authentication
 255                 infrastructure (libraries and support programs).
 256                 Default: yes
 257
 258 MKPCC           If "no", don't build pcc(1) or any of the PCC-related
 259                 libraries (libpcc, libpccsoftfloat).
 260                 Default: no
 261
 262 MKPCCCMDS       If "no", don't build pcc(1), but do build the PCC-related
 263                 libraries (libpcc, libpccsoftfloat).
 264                 Default: no
 265
 266 MKPF            If "no", don't build or install the pf programs and LKM.
 267                 Default: yes
 268
 269 MKPIC           If "no", don't build or install shared libraries, and
 270                 also acts as "MKPICLIB=no"
 271                 Default: yes (for MACHINE_ARCHs that support it)
 272
 273 MKPICINSTALL    If "no", don't install the *_pic.a libraries.
 274                 Default: yes
 275
 276 MKPICLIB        If "no", don't build *_pic.a libraries, and build the
 277                 shared object libraries from the .a libraries.
 278                 A symlink is installed in ${DESTDIR}/usr/lib for the
 279                 _pic.a library pointing to the .a library.
 280                 Default: yes
 281
 282 MKPIE           If "no", create regular executables. Otherwise create
 283                 PIE (Position Independent Executables).
 284                 Default: no
 285
 286 MKPOSTFIX       If "no", don't build or install postfix(1).
 287                 Default: yes
 288
 289 MKPROFILE       If "no", don't build or install the profiling (*_p.a) libraries.
 290                 Default: yes
 291
 292 MKSHARE         If "no", act as "MKCATPAGES=no MKDOC=no MKHTML=no MKINFO=no
 293                 MKMAN=no MKNLS=no".
 294                 I.e, don't build catman pages, documentation, Info
 295                 documentation, man pages, NLS files, ...
 296                 Default: yes
 297
 298 MKSKEY          If "no", disables building of S/key authentication
 299                 infrastructure (libraries and support programs).
 300                 Default: yes
 301
 302 MKSOFTFLOAT     If not "no", build with options to enable the compiler to
 303                 generate output containing library calls for floating
 304                 point and possibly soft-float library support.
 305                 Default: no
 306
 307 MKSTATICLIB     If "no", don't build or install the normal static (*.a)
 308                 libraries.
 309                 Default: yes
 310
 311 MKUNPRIVED      If not "no", don't set the owner/group/mode when installing
 312                 files or directories, and keep a metadata log of what
 313                 the owner/group/mode should be.  This allows a
 314                 non-root "make install".
 315                 Default: no
 316
 317 MKUPDATE        If not "no", 'make install' only installs targets that are
 318                 more recently modified in the source directories that their
 319                 installed counterparts.
 320                 Default: no
 321
 322 MKX11           If not "no", depending on the value of ${X11FLAVOUR},
 323                 'make build' also descends into either src/x11 (XFree86) or
 324                 src/external/mit/xorg (modular Xorg) to cross-build X11 and
 325                 automatically enables creation of X sets.
 326                 Default: no
 327
 328 MKX11FONTS      If not "no", if ${X11FLAVOUR} is "Xorg", do not build or
 329                 install the X fonts.  The xfont set is still created but
 330                 will be empty.
 331                 Default: yes
 332
 333 MKYP            If "no", disables building of YP (NIS)
 334                 infrastructure (libraries and support programs).
 335                 Default: yes
 336
 337 USE_HESIOD      If "no", disables building Hesiod support into
 338                 various system utilities/libraries that support it.
 339                 If ${MKHESIOD} is "no", USE_HESIOD will also be
 340                 forced to "no".
 341
 342 USE_INET6       If "no", disables building INET6 (IPv6) support into
 343                 various system utilities/libraries that support it.
 344                 If ${MKINET6} is "no", USE_INET6 will also be
 345                 forced to "no".
 346
 347 USE_JEMALLOC    If "no", disables building the "jemalloc" allocator
 348                 designed for improved performance with threaded
 349                 applications.  The "phkmalloc" allocator as used up
 350                 before NetBSD-5.0 will be substituted.
 351
 352 USE_KERBEROS    If "no", disables building Kerberos v5
 353                 support into various system utilities/libraries that
 354                 support it.  If ${MKKERBEROS} is "no", USE_KERBEROS
 355                 will also be forced to "no".
 356
 357 USE_LDAP        If "no", disables building LDAP support into various
 358                 system utilities/libraries that support it.
 359                 If ${MKLDAP} is "no", USE_LDAP will also be forced to "no".
 360
 361 USE_PAM         If "no", disables building PAM authentication support
 362                 into various system utilities/libraries that support it.
 363                 If ${MKPAM} is "no", USE_PAM will also be forced to "no".
 364
 365 USE_SKEY        If "no", disables building S/key authentication
 366                 support into various system utilities/libraries that
 367                 support it.  If ${MKSKEY} is "no", USE_SKEY will
 368                 also be forced to "no".
 369                 Default: no
 370
 371 USE_SSP         If "no", disables GCC stack protection code, which
 372                 detects stack overflows and aborts the program. This
 373                 imposes some performance penalty.
 374                 Default: no
 375
 376 USE_FORT        If "yes" turns on substitute wrappers for commonly used
 377                 functions that do not do bounds checking regularly, but
 378                 they could in some cases by using the gcc
 379                 __builtin_object_size() function to determine the buffer
 380                 size where it is known and detect buffer overflows.
 381                 These substitute functions are in /usr/include/ssp.
 382                 Default: no
 383
 384 USE_YP          If "no", disables building YP (NIS) support into
 385                 various system utilities/libraries that support it.
 386                 If ${MKYP} is "no", USE_YP will also be forced to "no".
 387
 388 X11FLAVOUR      Set to "Xorg" or "XFree86", depending on whether to build
 389                 XFree86 or modular Xorg.  Only matters if MKX11!=no.
 390                 Default: "Xorg" on amd64, i386, macppc, shark and sparc64,
 391                 "XFree86" on everything else.
 392
 393 COPTS.lib<lib>
 394 OBJCOPTS.lib<lib>
 395 LDADD.lib<lib>
 396 CPPFLAGS.lib<lib>
 397 CXXFLAGS.lib<lib>
 398 COPTS.<prog>
 399 OBJCCOPTS.<prog>
 400 LDADD.<prog>
 401 CPPFLAGS.<prog>
 402 CXXFLAGS.<prog> These provide a way to specify additions to the associated
 403                 variables in a way that applies only to a particular library
 404                 or program.  <lib> corresponds to the LIB variable set in
 405                 the library's makefile.  <prog> corresponds to either PROG
 406                 or PROG_CXX (if set).  For example, if COPTS.libcrypto is
 407                 set to "-g", "-g" will be added to COPTS only when compiling
 408                 the crypto library.
 409
 410 =-=-=-=-=   sys.mk   =-=-=-=-=
 411
 412 The include file <sys.mk> has the default rules for all makes, in the BSD
 413 environment or otherwise.  You probably don't want to touch this file.
 414
 415 =-=-=-=-=   bsd.own.mk   =-=-=-=-=
 416
 417 The include file <bsd.own.mk> contains source tree configuration parameters,
 418 such as the owners, groups, etc. for both manual pages and binaries, and
 419 a few global "feature configuration" parameters.
 420
 421 It has no targets.
 422
 423 To get system-specific configuration parameters, <bsd.own.mk> will try to
 424 include the file specified by the "MAKECONF" variable.  If MAKECONF is not
 425 set, or no such file exists, the system make configuration file, /etc/mk.conf
 426 is included.  These files may define any of the variables described below.
 427
 428 <bsd.own.mk> sets the following variables, if they are not already defined
 429 (defaults are in brackets):
 430
 431 NETBSDSRCDIR    Top of the NetBSD source tree.
 432                 If _SRC_TOP_ != "", that will be used as the default,
 433                 otherwise BSDSRCDIR will be used as the default.
 434                 Various makefiles within the NetBSD source tree will
 435                 use this to reference the top level of the source tree.
 436
 437 _SRC_TOP_       Top of the system source tree, as determined by <bsd.own.mk>
 438                 based on the presence of tools/ and build.sh.  This variable
 439                 is "internal" to <bsd.own.mk>, although its value is only
 440                 determined once and then propagated to all sub-makes.
 441
 442 BSDSRCDIR       The real path to the system sources, so that 'make obj'
 443                 will work correctly.  [/usr/src]
 444
 445 BSDOBJDIR       The real path to the system 'obj' tree, so that 'make obj'
 446                 will work correctly.  [/usr/obj]
 447
 448 BINGRP          Binary group.  [wheel]
 449
 450 BINOWN          Binary owner.  [root]
 451
 452 BINMODE         Binary mode.  [555]
 453
 454 NONBINMODE      Mode for non-executable files.  [444]
 455
 456 MANDIR          Base path for manual installation.  [/usr/share/man/cat]
 457
 458 MANGRP          Manual group.  [wheel]
 459
 460 MANOWN          Manual owner.  [root]
 461
 462 MANMODE         Manual mode.  [${NONBINMODE}]
 463
 464 MANINSTALL      Manual installation type.  Space separated list:
 465                         catinstall, htmlinstall, maninstall
 466                 [catinstall maninstall htmlinstall]
 467
 468 LDSTATIC        Control program linking; if set blank, link everything
 469                 dynamically.  If set to "-static", link everything statically.
 470                 If not set, programs link according to their makefile.
 471
 472 LIBDIR          Base path for library installation.  [/usr/lib]
 473
 474 LINTLIBDIR      Base path for lint(1) library installation.  [/usr/libdata/lint]
 475
 476 LIBGRP          Library group.  [${BINGRP}]
 477
 478 LIBOWN          Library owner.  [${BINOWN}]
 479
 480 LIBMODE         Library mode.  [${NONBINMODE}]
 481
 482 DOCDIR          Base path for system documentation (e.g. PSD, USD, etc.)
 483                 installation.  [/usr/share/doc]
 484
 485 HTMLDOCDIR      Base path for html system documentation installation.
 486                 [/usr/share/doc/html]
 487
 488 DOCGRP          Documentation group.  [wheel]
 489
 490 DOCOWN          Documentation owner.  [root]
 491
 492 DOCMODE         Documentation mode.  [${NONBINMODE}]
 493
 494 NLSDIR          Base path for Native Language Support files installation.
 495                 [/usr/share/nls]
 496
 497 NLSGRP          Native Language Support files group.  [wheel]
 498
 499 NLSOWN          Native Language Support files owner.  [root]
 500
 501 NLSMODE         Native Language Support files mode.  [${NONBINMODE}]
 502
 503 X11SRCDIR       The path to the xsrc tree.  [/usr/xsrc]
 504
 505 X11SRCDIR.xc    The path to the (old) X11 xc src tree.  [${X11SRCDIR}/xfree/xc]
 506
 507 X11SRCDIR.local The path to the local X11 src tree.  [${X11SRCDIR}/local]
 508
 509 X11SRCDIR.lib<package>
 510 X11SRCDIR.<package>
 511                 The path to the xorg src tree for the specificed package>.
 512                 [${X11SRCDIR}/external/mit/xorg/<package>/dist]
 513
 514 X11ROOTDIR      Root directory of the X11 installation.  [/usr/X11R6 or
 515                 [/usr/X11R7]
 516
 517 X11BINDIR       X11 bin directory.  [${X11ROOTDIR}/bin]
 518
 519 X11FONTDIR      X11 font directory.  [${X11ROOTDIR}/lib/X11/fonts]
 520
 521 X11INCDIR       X11 include directory.  [${X11ROOTDIR}/include]
 522
 523 X11LIBDIR       X11 lib/x11 (config) directory.  [${X11ROOTDIR}/lib/X11]
 524
 525 X11MANDIR       X11 manual directory.  [${X11ROOTDIR}/man]
 526
 527 X11USRLIBDIR    X11 library directory.  [${X11ROOTDIR}/lib]
 528
 529 STRIPFLAG       The flag passed to the install program to cause the binary
 530                 to be stripped.  This is to be used when building your
 531                 own install script so that the entire system can be made
 532                 stripped/not-stripped using a single knob.  []
 533
 534 COPY            The flag passed to the install program to cause the binary
 535                 to be copied rather than moved.  This is to be used when
 536                 building our own install script so that the entire system
 537                 can either be installed with copies, or with moves using
 538                 a single knob.  [-c]
 539
 540 MAKEDIRTARGET dir target [params]
 541                 Runs "cd $${dir} && ${MAKE} [params] $${target}",
 542                 displaying a "pretty" message whilst doing so.
 543
 544 RELEASEMACHINEDIR
 545                 Subdirectory used below RELEASEDIR when building
 546                 a release.  [${MACHINE}]
 547
 548 RELEASEMACHINE  Subdirectory or path component used for the following
 549                 paths:
 550                         distrib/${RELEASEMACHINE}
 551                         distrib/notes/${RELEASEMACHINE}
 552                         etc/etc.${RELEASEMACHINE}
 553                 Used when building a release.  [${MACHINE}]
 554
 555 Additionally, the following variables may be set by <bsd.own.mk> or in a
 556 make configuration file to modify the behavior of the system build
 557 process (default values are in brackets along with comments, if set by
 558 <bsd.own.mk>):
 559
 560 USETOOLS        Indicates whether the tools specified by ${TOOLDIR} should
 561                 be used as part of a build in progress.
 562                 Supported values:
 563
 564                 yes     Use the tools from TOOLDIR.
 565                         Must be set to this if cross-compiling.
 566
 567                 no      Do not use the tools from TOOLDIR, but refuse to
 568                         build native compilation tool components that are
 569                         version-specific for that tool.
 570
 571                 never   Do not use the tools from TOOLDIR, even when
 572                         building native tool components.  This is similar to
 573                         the traditional NetBSD build method, but does not
 574                         verify that the compilation tools in use are
 575                         up-to-date enough in order to build the tree
 576                         successfully.  This may cause build or runtime
 577                         problems when building the whole NetBSD source tree.
 578
 579                 Default: "yes" if building all or part of a whole NetBSD
 580                 source tree (detected automatically); "no" otherwise
 581                 (to preserve traditional semantics of the <bsd.*.mk>
 582                 make(1) include files).
 583
 584 OBJECT_FMT      Object file format.  [set to "ELF" on architectures that
 585                 use ELF -- currently all architectures].
 586
 587 TOOLCHAIN_MISSING
 588                 If not "no", this indicates that the platform being built
 589                 does not have a working in-tree toolchain.  If the
 590                 ${MACHINE_ARCH} in question falls into this category,
 591                 TOOLCHAIN_MISSING is conditionally assigned the value "yes".
 592                 Otherwise, the variable is unconditionally assigned the
 593                 value "no".
 594                 If not "no", ${MKBFD}, ${MKGCC}, and ${MKGDB} are
 595                 unconditionally assigned the value "no".
 596
 597 EXTERNAL_TOOLCHAIN
 598                 This variable is not directly set by <bsd.own.mk>, but
 599                 including <bsd.own.mk> is the canonical way to gain
 600                 access to this variable.  The variable should be defined
 601                 either in the user's environment or in the user's mk.conf
 602                 file.  If defined, this variable indicates the root of
 603                 an external toolchain which will be used to build the
 604                 tree.  For example, if a platform is a ${TOOLCHAIN_MISSING}
 605                 platform, EXTERNAL_TOOLCHAIN can be used to re-enable the
 606                 cross-compile framework.
 607
 608                 If EXTERNAL_TOOLCHAIN is defined, ${MKGCC} is unconditionally
 609                 assigned the value "no", since the external version of the
 610                 compiler may not be able to build the library components of
 611                 the in-tree compiler.
 612
 613                 NOTE: This variable is not yet used in as many places as
 614                 it should be.  Expect the exact semantics of this variable
 615                 to change in the short term as parts of the cross-compile
 616                 framework continue to be cleaned up.
 617
 618 The following variables are defined to commands to perform the
 619 appropriate operation, with the default in [brackets].  Note that
 620 the defaults change if USETOOLS == "yes":
 621
 622 TOOL_AMIGAAOUT2BB       aout to Amiga bootblock converter.  [amiga-aout2bb]
 623
 624 TOOL_AMIGAELF2BB        ELF to Amiga bootblock converter.  [amiga-elf2bb]
 625
 626 TOOL_AMIGATXLT          Amige assembly language format translator.  [amiga-txlt]
 627
 628 TOOL_ASN1_COMPILE       ASN1 compiler.  [asn1_compile]
 629
 630 TOOL_ATF_COMPILE        Generate POSIX shell test programs.  [atf-compile]
 631
 632 TOOL_AWK                Pattern-directed scanning/processing language.  [awk]
 633
 634 TOOL_CAP_MKDB           Create capability database.  [cap_mkdb]
 635
 636 TOOL_CAT                Concatenate and print files.  [cat]
 637
 638 TOOL_CKSUM              Display file checksums.  [cksum]
 639
 640 TOOL_COMPILE_ET         Error table compiler.  [compile_et]
 641
 642 TOOL_CONFIG             Build kernel compilation directories.  [config]
 643
 644 TOOL_CRUNCHGEN          Generate crunched binary build environment.  [crunchgen]
 645
 646 TOOL_CTAGS              Create a tags file.  [ctags]
 647
 648 TOOL_DB                 Manipulate db(3) databases.  [db]
 649
 650 TOOL_DISKLABEL          Read and write disk pack label.  [disklabel]
 651
 652 TOOL_EQN                Format equations for groff.  [eqn]
 653
 654 TOOL_FDISK              MS-DOS partition maintenance program.  [fdisk]
 655
 656 TOOL_FGEN               IEEE 1275 Open Firmware FCode Tokenizer.  [fgen]
 657
 658 TOOL_GENASSYM           Generate constants for assembly files.  [genassym]
 659
 660 TOOL_GENCAT             Generate NLS message catalogs.  [gencat]
 661
 662 TOOL_GMAKE              GNU make utility.  [gmake]
 663
 664 TOOL_GREP               Print lines matching a pattern.  [grep]
 665
 666 TOOL_GROFF              Front end for groff document formatting system.  [groff]
 667
 668 TOOL_HEXDUMP            Ascii, decimal, hexadecimal, octal dump.  [hexdump]
 669
 670 TOOL_HP300MKBOOT        Make bootable image for hp300.  [hp300-mkboot]
 671
 672 TOOL_HP700MKBOOT        Make bootable image for hp700.  [hp700-mkboot]
 673
 674 TOOL_INDXBIB            Make bibliographic database's inverted index.  [indxbib]
 675
 676 TOOL_INSTALLBOOT        Install disk bootstrap software.  [installboot]
 677
 678 TOOL_INSTALL_INFO       Update info/dir entries.  [install-info]
 679
 680 TOOL_JOIN               Relational database operator.  [join]
 681
 682 TOOL_M4                 M4 macro language processor.  [m4]
 683
 684 TOOL_MACPPCFIXCOFF      Fix up xcoff headers for macppc.  [macppc-fixcoff]
 685
 686 TOOL_MAKEFS             Create file system image from directory tree.  [makefs]
 687
 688 TOOL_MAKEINFO           Translate Texinfo documents.  [makeinfo]
 689
 690 TOOL_MAKEWHATIS         Create a whatis.db database.  [makewhatis]
 691
 692 TOOL_MDSETIMAGE         Set kernel RAM disk image.  [mdsetimage]
 693
 694 TOOL_MENUC              Menu compiler.  [menuc]
 695
 696 TOOL_MIPSELF2ECOFF      Convert ELF-format executable to ECOFF for mips.
 697                         [mips-elf2ecoff]
 698
 699 TOOL_MKCSMAPPER         Make charset mapping table.  [mkcsmapper]
 700
 701 TOOL_MKESDB             Make encoding scheme database.  [mkesdb]
 702
 703 TOOL_MKLOCALE           Make LC_CTYPE locale files.  [mklocale]
 704
 705 TOOL_MKMAGIC            Create database for file(1).  [file]
 706
 707 TOOL_MKTEMP             Make (unique) temporary file name.  [mktemp]
 708
 709 TOOL_MSGC               Simple message list compiler.  [msgc]
 710
 711 TOOL_MTREE              Map a directory hierarchy.  [mtree]
 712
 713 TOOL_PAX                Manipulate file archives and copy directories.  [pax]
 714
 715 TOOL_PIC                Compile pictures for groff.  [pic]
 716
 717 TOOL_POWERPCMKBOOTIMAGE Make bootable image for powerpc.  [powerpc-mkbootimage]
 718
 719 TOOL_PWD_MKDB           Generate the password databases.  [pwd_mkdb]
 720
 721 TOOL_REFER              Preprocess bibliographic references for groff.  [refer]
 722
 723 TOOL_ROFF_ASCII         Generate ASCII groff output.  [nroff]
 724
 725 TOOL_ROFF_DVI           Generate DVI groff output.  [${TOOL_GROFF} -Tdvi]
 726
 727 TOOL_ROFF_HTML          Generate HTML groff output.
 728                         [${TOOL_GROFF} -Tlatin1 -mdoc2html]
 729
 730 TOOL_ROFF_PS            Generate PS groff output.  [${TOOL_GROFF} -Tps]
 731
 732 TOOL_ROFF_RAW           Generate "raw" groff output.  [${TOOL_GROFF} -Z]
 733
 734 TOOL_RPCGEN             Remote Procedure Call (RPC) protocol compiler.  [rpcgen]
 735
 736 TOOL_SED                Stream editor.  [sed]
 737
 738 TOOL_SOELIM             Eliminate .so's from groff input.  [soelim]
 739
 740 TOOL_SPARKCRC           Generate a crc suitable for use in a sparkive file.
 741                         [sparkcrc]
 742
 743 TOOL_STAT               Display file status.  [stat]
 744
 745 TOOL_STRFILE            Create a random access file for storing strings.
 746                         [strfile]
 747
 748 TOOL_SUNLABEL           Read or modify a SunOS disk label.  [sunlabel]
 749
 750 TOOL_TBL                Format tables for groff.  [tbl]
 751
 752 TOOL_UUDECODE           Uudecode a binary file.  [uudecode]
 753
 754 TOOL_VGRIND             Grind nice listings of programs.  [vgrind -f]
 755
 756 TOOL_ZIC                Time zone compiler.  [zic]
 757
 758 <bsd.own.mk> is generally useful when building your own Makefiles so that
 759 they use the same default owners etc. as the rest of the tree.
 760
 761
 762 =-=-=-=-=   bsd.dep.mk   =-=-=-=-=
 763
 764 The include file <bsd.dep.mk> contains the default targets for building
 765 .depend files.  It creates .d files from entries in SRCS and DPSRCS
 766 that are C, C++, or Objective C source files, and builds .depend from the
 767 .d files.  All other files in SRCS and all of DPSRCS will be used as
 768 dependencies for the .d files.  In order for this to function correctly,
 769 it should be .included after all other .mk files and directives that may
 770 modify SRCS or DPSRCS.  It uses the following variables:
 771
 772 SRCS            List of source files to build the program.
 773
 774 DPSRCS          List of source files which are needed for generating
 775                 dependencies, but are not needed in ${SRCS}.
 776
 777
 778 =-=-=-=-=   bsd.files.mk   =-=-=-=-=
 779
 780 The include file <bsd.files.mk> handles the FILES variables and is included
 781 from <bsd.lib.mk> and <bsd.prog.mk>, and uses the following variables:
 782
 783 FILES           The list of files to install.
 784
 785 CONFIGFILES     Similar semantics to FILES, except that the files
 786                 are installed by the `configinstall' target,
 787                 not the `install' target.
 788                 The FILES* variables documented below also apply.
 789
 790 FILESOWN        File owner.  [${BINOWN}]
 791
 792 FILESGRP        File group.  [${BINGRP}]
 793
 794 FILESMODE       File mode.  [${NONBINMODE}]
 795
 796 FILESDIR        The location to install the files.
 797
 798 FILESNAME       Optional name to install each file as.
 799
 800 FILESOWN_<fn>   File owner of the specific file <fn>.
 801
 802 FILESGRP_<fn>   File group of the specific file <fn>.
 803
 804 FILESMODE_<fn>  File mode of the specific file <fn>.
 805
 806 FILESDIR_<fn>   The location to install the specific file <fn>.
 807
 808 FILESNAME_<fn>  Optional name to install <fn> as.
 809
 810 FILESBUILD_<fn> A value different from "no" will add the file to the list of
 811                 targets to be built by `realall'.  Users of that variable
 812                 should provide a target to build the file.
 813
 814
 815 BUILDSYMLINKS   List of two word items:
 816                         lnsrc lntgt
 817                 For each lnsrc item, create a symlink named lntgt.
 818                 The lntgt symlinks are removed by the cleandir target.
 819
 820 UUDECODE_FILES  List of files which are stored as <file>.uue in the source
 821                 tree. Each one will be decoded with ${TOOL_UUDECODE}.
 822                 The source files have a `.uue' suffix, the generated files do
 823                 not.
 824
 825 UUDECODE_FILES_RENAME_<fn>
 826                 Rename the output from the decode to the provided name.
 827
 828                 *NOTE: These files are simply decoded, with no install or other
 829                        rule applying implicitly except being added to the clean
 830                        target.
 831
 832 =-=-=-=-=   bsd.gcc.mk   =-=-=-=-=
 833
 834 The include file <bsd.gcc.mk> computes various parameters related to GCC
 835 support libraries.  It defines no targets.  <bsd.own.mk> MUST be included
 836 before <bsd.gcc.mk>.
 837
 838 The primary users of <bsd.gcc.mk> are <bsd.prog.mk> and <bsd.lib.mk>, each
 839 of which need to know where to find certain GCC support libraries.
 840
 841 The behavior of <bsd.gcc.mk> is influenced by the EXTERNAL_TOOLCHAIN variable,
 842 which is generally set by the user.  If EXTERNAL_TOOLCHAIN it set, then
 843 the compiler is asked where to find the support libraries, otherwise the
 844 support libraries are found in ${DESTDIR}/usr/lib.
 845
 846 <bsd.gcc.mk> sets the following variables:
 847
 848 _GCC_CRTBEGIN   The full path name to crtbegin.o.
 849
 850 _GCC_CRTBEGINS  The full path name to crtbeginS.o.
 851
 852 _GCC_CRTEND     The full path name to crtend.o.
 853
 854 _GCC_CRTENDS    The full path name to crtendS.o.
 855
 856 _GCC_LIBGCCDIR  The directory where libgcc.a is located.
 857
 858
 859 =-=-=-=-=   bsd.inc.mk   =-=-=-=-=
 860
 861 The include file <bsd.inc.mk> defines the includes target and uses the
 862 variables:
 863
 864 INCS            The list of include files.
 865
 866 INCSDIR         The location to install the include files.
 867
 868 INCSNAME        Target name of the include file, if only one; same as
 869                 FILESNAME, but for include files.
 870
 871 INCSYMLINKS     Similar to SYMLINKS in <bsd.links.mk>, except that these
 872                 are installed in the 'includes' target and not the
 873                 (much later) 'install' target.
 874
 875 INCSNAME_<file> The name file <file> should be installed as, if not <file>,
 876                 same as FILESNAME_<file>, but for include files.
 877
 878
 879 =-=-=-=-=   bsd.info.mk   =-=-=-=-=
 880
 881 The include file <bsd.info.mk> is used to generate and install GNU Info
 882 documentation from respective Texinfo source files.  It defines three
 883 implicit targets (.txi.info, .texi.info, and .texinfo.info), and uses the
 884 following variables:
 885
 886 TEXINFO         List of Texinfo source files.  Info documentation will
 887                 consist of single files with the extension replaced by
 888                 .info.
 889
 890 INFOFLAGS       Flags to pass to makeinfo.  []
 891
 892
 893 =-=-=-=-=   bsd.kernobj.mk   =-=-=-=-=
 894
 895 The include file <bsd.kernobj.mk> defines variables related to the
 896 location of kernel sources and object directories.
 897
 898 KERNSRCDIR      Is the location of the top of the kernel src.
 899                 [${_SRC_TOP_}/sys]
 900
 901 KERNARCHDIR     Is the location of the machine dependent kernel sources.
 902                 [arch/${MACHINE}]
 903
 904 KERNCONFDIR     Is where the configuration files for kernels are found.
 905                 [${KERNSRCDIR}/${KERNARCHDIR}/conf]
 906
 907 KERNOBJDIR      Is the kernel build directory.  The kernel GENERIC for
 908                 instance will be compiled in ${KERNOBJDIR}/GENERIC.
 909                 The default value is
 910                 ${MAKEOBJDIRPREFIX}${KERNSRCDIR}/${KERNARCHDIR}/compile
 911                 if it exists or the target 'obj' is being made.
 912                 Otherwise the default is
 913                 ${KERNSRCDIR}/${KERNARCHDIR}/compile.
 914
 915 It is important that Makefiles (such as those under src/distrib) that
 916 wish to find compiled kernels use <bsd.kernobj.mk> and ${KERNOBJDIR}
 917 rather than make assumptions about the location of the compiled kernel.
 918
 919
 920 =-=-=-=-=   bsd.kinc.mk   =-=-=-=-=
 921
 922 The include file <bsd.kinc.mk> defines the many targets (includes,
 923 subdirectories, etc.), and is used by kernel makefiles to handle
 924 include file installation.  It is intended to be included alone, by
 925 kernel Makefiles.  It uses similar variables to <bsd.inc.mk>.
 926 Please see <bsd.kinc.mk> for more details, and keep the documentation
 927 in that file up to date.
 928
 929
 930 =-=-=-=-=   bsd.lib.mk   =-=-=-=-=
 931
 932 The include file <bsd.lib.mk> has support for building libraries.  It has
 933 the same eight targets as <bsd.prog.mk>: all, clean, cleandir, depend,
 934 includes, install, lint, and tags.  Additionally, it has a checkver target
 935 which checks for installed shared object libraries whose version is greater
 936 that the version of the source. It has a limited number of suffixes,
 937 consistent with the current needs of the BSD tree.  <bsd.lib.mk> includes
 938 <bsd.shlib.mk> to get shared library parameters.
 939
 940 It sets/uses the following variables:
 941
 942 LIB             The name of the library to build.
 943
 944 LIBDIR          Target directory for libraries.
 945
 946 MKARZERO        Normally, ar(1) sets the timestamps, uid, gid and
 947                 permissions in files inside its archives to those of
 948                 the file it was fed. This leads to non-reproduceable
 949                 builds. If MKARZERO is set to "yes" (default is "no")
 950                 then the "D" flag is passed to ar, causing the
 951                 timestamp, uid and gid to be zeroed and the file
 952                 permissions to be set to 644. This allows .a files
 953                 from different builds to be bit identical.
 954
 955 SHLIBINSTALLDIR Target directory for shared libraries if ${USE_SHLIBDIR}
 956                 is not "no".
 957
 958 USE_SHLIBDIR    If not "no", use ${SHLIBINSTALLDIR} instead of ${LIBDIR}
 959                 as the path to install shared libraries to.
 960                 USE_SHLIBDIR must be defined before <bsd.own.mk> is included.
 961                 Default: no
 962
 963 LIBISMODULE     If not "no", install as ${LIB}.so (without the "lib" prefix),
 964                 and act as "MKDEBUGLIB=no MKLINT=no MKPICINSTALL=no
 965                 MKPROFILE=no MKSTATICLIB=no".
 966                 Default: no
 967
 968 LIBISPRIVATE    If not "no", act as "MKDEBUGLIB=no MKLINT=no MKPIC=no
 969                 MKPROFILE=no", and don't install the (.a) library.
 970                 This is useful for "build only" helper libraries.
 971                 Default: no
 972
 973 LIBISCXX        If not "no", Use ${CXX} instead of ${CC} to link
 974                 shared libraries.
 975                 This is useful for C++ libraries.
 976                 Default: no
 977
 978 LINTLIBDIR      Target directory for lint libraries.
 979
 980 LIBGRP          Library group.
 981
 982 LIBOWN          Library owner.
 983
 984 LIBMODE         Library mode.
 985
 986 LDADD           Additional loader objects.
 987
 988 MAN             The manual pages to be installed (use a .1 - .9 suffix).
 989
 990 NOCHECKVER_<library>
 991 NOCHECKVER      If set, disables checking for installed shared object
 992                 libraries with versions greater than the source.  A
 993                 particular library name, without the "lib" prefix, may
 994                 be appended to the variable name to disable the check for
 995                 only that library.
 996
 997 SRCS            List of source files to build the library.  Suffix types
 998                 .s, .c, and .f are supported.  Note, .s files are preferred
 999                 to .c files of the same name.  (This is not the default for
1000                 versions of make.)
1001
1002 LIBDPLIBS       A list of the tuples:
1003                         libname  path-to-srcdir-of-libname
1004
1005                 For each tuple;
1006                      *  LIBDO.libname contains the .OBJDIR of the library
1007                         `libname', and if it is not set it is determined
1008                         from the srcdir and added to MAKEOVERRIDES (the
1009                         latter is to allow for build time optimization).
1010                      *  LDADD gets  -L${LIBDO.libname} -llibname    added.
1011                      *  DPADD gets  ${LIBDO.libname}/liblibname.so  or
1012                                     ${LIBDO.libname}/liblibname.a   added.
1013
1014                 This variable may be used for individual libraries, as
1015                 well as in parent directories to cache common libraries
1016                 as a build-time optimization.
1017
1018 The include file <bsd.lib.mk> includes the file named "../Makefile.inc"
1019 if it exists, as well as the include file <bsd.man.mk>.
1020
1021 It has rules for building profiled objects; profiled libraries are
1022 built by default.
1023
1024 Libraries are ranlib'd when made.
1025
1026
1027 =-=-=-=-=   bsd.links.mk   =-=-=-=-=
1028
1029 The include file <bsd.links.mk> handles the LINKS and SYMLINKS variables
1030 and is included from from <bsd.lib.mk> and <bsd.prog.mk>.
1031
1032 LINKSOWN, LINKSGRP, and LINKSMODE, are relevant only if a metadata log
1033 is used. The defaults may be modified by other bsd.*.mk files which
1034 include bsd.links.mk.  In the future, these variables may be replaced
1035 by a method for explicitly recording hard links in a metadata log.
1036
1037 LINKS           The list of hard links, consisting of pairs of paths:
1038                         source-file target-file
1039                 ${DESTDIR} is prepended to both paths before linking.
1040                 For example, to link /bin/test and /bin/[, use:
1041                         LINKS=/bin/test /bin/[
1042
1043 CONFIGLINKS     Similar semantics to LINKS, except that the links
1044                 are installed by the `configinstall' target,
1045                 not the `install' target.
1046
1047 SYMLINKS        The list of symbolic links, consisting of pairs of paths:
1048                         source-file target-file
1049                 ${DESTDIR} is only prepended to target-file before linking.
1050                 For example, to symlink /usr/bin/tar to /bin/tar resulting
1051                 in ${DESTDIR}/usr/bin/tar -> /bin/tar:
1052                         SYMLINKS=/bin/tar /usr/bin/tar
1053
1054 CONFIGSYMLINKS  Similar semantics to SYMLINKS, except that the symbolic links
1055                 are installed by the `configinstall' target,
1056                 not the `install' target.
1057
1058 LINKSOWN        Link owner.  [${BINOWN}]
1059
1060 LINKSGRP        Link group.  [${BINGRP}]
1061
1062 LINKSMODE       Link mode.  [${NONBINMODE}]
1063
1064 LINKSOWN_<fn>   Link owner of the specific file <fn>.
1065
1066 LINKSGRP_<fn>   Link group of the specific file <fn>.
1067
1068 LINKSMODE_<fn>  Link mode of the specific file <fn>.
1069
1070
1071 =-=-=-=-=   bsd.man.mk   =-=-=-=-=
1072
1073 The include file <bsd.man.mk> handles installing manual pages and their
1074 links.
1075
1076 It has a three targets:
1077
1078         catinstall:
1079                 Install the preformatted manual pages and their links.
1080         htmlinstall:
1081                 Install the HTML manual pages and their links.
1082         maninstall:
1083                 Install the manual page sources and their links.
1084
1085 It sets/uses the following variables:
1086
1087 MANDIR          Base path for manual installation.
1088
1089 MANGRP          Manual group.
1090
1091 MANOWN          Manual owner.
1092
1093 MANMODE         Manual mode.
1094
1095 MANSUBDIR       Subdirectory under the manual page section, i.e. "/vax"
1096                 or "/tahoe" for machine specific manual pages.
1097
1098 MAN             The manual pages to be installed (use a .1 - .9 suffix).
1099
1100 MLINKS          List of manual page links (using a .1 - .9 suffix).  The
1101                 linked-to file must come first, the linked file second,
1102                 and there may be multiple pairs.  The files are soft-linked.
1103
1104 The include file <bsd.man.mk> includes a file named "../Makefile.inc" if
1105 it exists.
1106
1107
1108 =-=-=-=-=   bsd.obj.mk   =-=-=-=-=
1109
1110 The include file <bsd.obj.mk> defines targets related to the creation
1111 and use of separated object and source directories.
1112
1113 If an environment variable named MAKEOBJDIRPREFIX is set, make(1) uses
1114 ${MAKEOBJDIRPREFIX}${.CURDIR} as the name of the object directory if
1115 it exists.  Otherwise make(1) looks for the existence of a
1116 subdirectory (or a symlink to a directory) of the source directory
1117 into which built targets should be placed.  If an environment variable
1118 named MAKEOBJDIR is set, make(1) uses its value as the name of the
1119 object directory; failing that, make first looks for a subdirectory
1120 named "obj.${MACHINE}", and if that doesn't exist, it looks for "obj".
1121
1122 Object directories are not created automatically by make(1) if they
1123 don't exist; you need to run a separate "make obj".  (This will happen
1124 during a top-level build if "MKOBJDIRS" is set to a value other than
1125 "no").  When the source directory is a subdirectory of ${BSDSRCDIR} --
1126 and this is determined by a simple string prefix comparison -- object
1127 directories are created in a separate object directory tree, and a
1128 symlink to the object directory in that tree is created in the source
1129 directory; otherwise, "make obj" assumes that you're not in the main
1130 source tree and that it's not safe to use a separate object tree.
1131
1132 Several variables used by <bsd.obj.mk> control exactly what
1133 directories and links get created during a "make obj":
1134
1135 MAKEOBJDIR      If set, this is the component name of the object
1136                 directory.
1137
1138 OBJMACHINE      If this is set but MAKEOBJDIR is not set, creates
1139                 object directories or links named "obj.${MACHINE}";
1140                 otherwise, just creates ones named "obj".
1141
1142 USR_OBJMACHINE  If set, and the current directory is a subdirectory of
1143                 ${BSDSRCDIR}, create object directory in the
1144                 corresponding subdirectory of ${BSDOBJDIR}.${MACHINE};
1145                 otherwise, create it in the corresponding subdirectory
1146                 of ${BSDOBJDIR}
1147
1148 BUILDID         If set, the contents of this variable are appended
1149                 to the object directory name.  If OBJMACHINE is also
1150                 set, ".${BUILDID}" is added after ".${MACHINE}".
1151
1152
1153 =-=-=-=-=   bsd.prog.mk   =-=-=-=-=
1154
1155 The include file <bsd.prog.mk> handles building programs from one or
1156 more source files, along with their manual pages.  It has a limited number
1157 of suffixes, consistent with the current needs of the BSD tree.
1158 <bsd.prog.mk> includes <bsd.shlib.mk> to get shared library parameters.
1159
1160 It has eight targets:
1161
1162         all:
1163                 build the program and its manual page.  This also
1164                 creates a GDB initialization file (.gdbinit) in
1165                 the objdir.  The .gdbinit file sets the shared library
1166                 prefix to ${DESTDIR} to facilitate cross-debugging.
1167         clean:
1168                 remove the program, any object files and the files a.out,
1169                 Errs, errs, mklog, and ${PROG}.core.
1170         cleandir:
1171                 remove all of the files removed by the target clean, as
1172                 well as .depend, tags, and any manual pages.
1173                 `distclean' is a synonym for `cleandir'.
1174         depend:
1175                 make the dependencies for the source files, and store
1176                 them in the file .depend.
1177         includes:
1178                 install any header files.
1179         install:
1180                 install the program and its manual pages; if the Makefile
1181                 does not itself define the target install, the targets
1182                 beforeinstall and afterinstall may also be used to cause
1183                 actions immediately before and after the install target
1184                 is executed.
1185         lint:
1186                 run lint on the source files
1187         tags:
1188                 create a tags file for the source files.
1189
1190 It sets/uses the following variables:
1191
1192 BINGRP          Binary group.
1193
1194 BINOWN          Binary owner.
1195
1196 BINMODE         Binary mode.
1197
1198 CLEANFILES      Additional files to remove for the clean and cleandir targets.
1199
1200 COPTS           Additional flags to the compiler when creating C objects.
1201
1202 COPTS.<fn>      Additional flags to the compiler when creating the
1203                 C objects for <fn>.
1204                 For <fn>.[ly], "<fn>.c" must be used.
1205
1206 CPUFLAGS        Additional flags to the compiler/assembler to select
1207                 CPU instruction set options, CPU tuning options, etc.
1208
1209 CPUFLAGS.<fn>   Additional flags to the compiler/assembler for <fn>.
1210                 For <fn>.[ly], "<fn>.c" must be used.
1211
1212 CPPFLAGS        Additional flags to the C pre-processor.
1213
1214 CPPFLAGS.<fn>   Additional flags to the C pre-processor for <fn>.
1215                 For <fn>.[ly], "<fn>.c" must be used.
1216
1217 GDBINIT         List of GDB initialization files to add to "source"
1218                 directives in the .gdbinit file that is created in the
1219                 objdir.
1220
1221 LDADD           Additional loader objects.  Usually used for libraries.
1222                 For example, to load with the compatibility and utility
1223                 libraries, use:
1224
1225                         LDADD+=-lutil -lcompat
1226
1227 LDFLAGS         Additional linker flags (passed to ${CC} during link).
1228
1229 LINKS           See <bsd.links.mk>
1230
1231 OBJCOPTS        Additional flags to the compiler when creating ObjC objects.
1232
1233 OBJCOPTS.<fn>   Additional flags to the compiler when creating the
1234                 ObjC objects for <fn>.
1235                 For <fn>.[ly], "<fn>.c" must be used.
1236
1237 SYMLINKS        See <bsd.links.mk>
1238
1239 MAN             Manual pages (should end in .1 - .9).  If no MAN variable is
1240                 defined, "MAN=${PROG}.1" is assumed.
1241
1242 PAXCTL_FLAGS    If defined, run paxctl(1) on the program binary after link
1243                 time, with the value of this variable as args to paxctl(1).
1244
1245 PAXCTL_FLAGS.${PROG} Custom override for PAXCTL_FLAGS.
1246
1247 PROG            The name of the program to build.  If not supplied, nothing
1248                 is built.
1249
1250 PROG_CXX        If defined, the name of the program to build.  Also
1251                 causes <bsd.prog.mk> to link the program with the C++
1252                 compiler rather than the C compiler.  PROG_CXX overrides
1253                 the value of PROG if PROG is also set.
1254
1255 PROGNAME        The name that the above program will be installed as, if
1256                 different from ${PROG}.
1257
1258 SRCS            List of source files to build the program.  If SRCS is not
1259                 defined, it's assumed to be ${PROG}.c.
1260
1261 DPSRCS          List of source files which are needed for generating
1262                 dependencies, but are not needed in ${SRCS}.
1263
1264 DPADD           Additional dependencies for the program.  Usually used for
1265                 libraries.  For example, to depend on the compatibility and
1266                 utility libraries use:
1267
1268                         DPADD+=${LIBCOMPAT} ${LIBUTIL}
1269
1270                 The following libraries are predefined for DPADD:
1271
1272                 LIBCRT0?=       ${DESTDIR}/usr/lib/crt0.o
1273                 LIBARCHIVE?=    ${DESTDIR}/usr/lib/libarchive.a
1274                 LIBASN1?=       ${DESTDIR}/usr/lib/libasn1.a
1275                 LIBBLUETOOTH?=  ${DESTDIR}/usr/lib/libbluetooth.a
1276                 LIBBSDMALLOC?=  ${DESTDIR}/usr/lib/libbsdmalloc.a
1277                 LIBBZ2?=        ${DESTDIR}/usr/lib/libbz2.a
1278                 LIBC?=          ${DESTDIR}/usr/lib/libc.a
1279                 LIBC_PIC?=      ${DESTDIR}/usr/lib/libc_pic.a
1280                 LIBCOM_ERR?=    ${DESTDIR}/usr/lib/libcom_err.a
1281                 LIBCOMPAT?=     ${DESTDIR}/usr/lib/libcompat.a
1282                 LIBCRYPT?=      ${DESTDIR}/usr/lib/libcrypt.a
1283                 LIBCRYPTO?=     ${DESTDIR}/usr/lib/libcrypto.a
1284                 LIBCRYPTO_IDEA?=${DESTDIR}/usr/lib/libcrypto_idea.a
1285                 LIBCRYPTO_MDC2?=${DESTDIR}/usr/lib/libcrypto_mdc2.a
1286                 LIBCRYPTO_RC5?= ${DESTDIR}/usr/lib/libcrypto_rc5.a
1287                 LIBCURSES?=     ${DESTDIR}/usr/lib/libcurses.a
1288                 LIBDBM?=        ${DESTDIR}/usr/lib/libdbm.a
1289                 LIBDES?=        ${DESTDIR}/usr/lib/libdes.a
1290                 LIBEDIT?=       ${DESTDIR}/usr/lib/libedit.a
1291                 LIBEVENT?=      ${DESTDIR}/usr/lib/libevent.a
1292                 LIBFETCH?=      ${DESTDIR}/usr/lib/libfetch.a
1293                 LIBFORM?=       ${DESTDIR}/usr/lib/libform.a
1294                 LIBGCC?=        ${DESTDIR}/usr/lib/libgcc.a
1295                 LIBGNUMALLOC?=  ${DESTDIR}/usr/lib/libgnumalloc.a
1296                 LIBGSSAPI?=     ${DESTDIR}/usr/lib/libgssapi.a
1297                 LIBHDB?=        ${DESTDIR}/usr/lib/libhdb.a
1298                 LIBINTL?=       ${DESTDIR}/usr/lib/libintl.a
1299                 LIBIPSEC?=      ${DESTDIR}/usr/lib/libipsec.a
1300                 LIBKADM5CLNT?=  ${DESTDIR}/usr/lib/libkadm5clnt.a
1301                 LIBKADM5SRV?=   ${DESTDIR}/usr/lib/libkadm5srv.a
1302                 LIBKAFS?=       ${DESTDIR}/usr/lib/libkafs.a
1303                 LIBKRB5?=       ${DESTDIR}/usr/lib/libkrb5.a
1304                 LIBKVM?=        ${DESTDIR}/usr/lib/libkvm.a
1305                 LIBL?=          ${DESTDIR}/usr/lib/libl.a
1306                 LIBLBER?=       ${DESTDIR}/usr/lib/liblber.a
1307                 LIBLDAP?=       ${DESTDIR}/usr/lib/libldap.a
1308                 LIBLDAP_R?=     ${DESTDIR}/usr/lib/libldap_r.a
1309                 LIBM?=          ${DESTDIR}/usr/lib/libm.a
1310                 LIBMENU?=       ${DESTDIR}/usr/lib/libmenu.a
1311                 LIBOBJC?=       ${DESTDIR}/usr/lib/libobjc.a
1312                 LIBOSSAUDIO?=   ${DESTDIR}/usr/lib/libossaudio.a
1313                 LIBPAM?=        ${DESTDIR}/usr/lib/libpam.a
1314                 LIBPCAP?=       ${DESTDIR}/usr/lib/libpcap.a
1315                 LIBPCI?=        ${DESTDIR}/usr/lib/libpci.a
1316                 LIBPMC?=        ${DESTDIR}/usr/lib/libpmc.a
1317                 LIBPOSIX?=      ${DESTDIR}/usr/lib/libposix.a
1318                 LIBPTHREAD?=    ${DESTDIR}/usr/lib/libpthread.a
1319                 LIBPTHREAD_DBG?=${DESTDIR}/usr/lib/libpthread_dbg.a
1320                 LIBRADIUS?=     ${DESTDIR}/usr/lib/libradius.a
1321                 LIBRESOLV?=     ${DESTDIR}/usr/lib/libresolv.a
1322                 LIBRMT?=        ${DESTDIR}/usr/lib/librmt.a
1323                 LIBROKEN?=      ${DESTDIR}/usr/lib/libroken.a
1324                 LIBRPCSVC?=     ${DESTDIR}/usr/lib/librpcsvc.a
1325                 LIBRT?=         ${DESTDIR}/usr/lib/librt.a
1326                 LIBSKEY?=       ${DESTDIR}/usr/lib/libskey.a
1327                 LIBSL?=         ${DESTDIR}/usr/lib/libsl.a
1328                 LIBSS?=         ${DESTDIR}/usr/lib/libss.a
1329                 LIBSSH?=        ${DESTDIR}/usr/lib/libssh.a
1330                 LIBSSL?=        ${DESTDIR}/usr/lib/libssl.a
1331                 LIBSSP?=        ${DESTDIR}/usr/lib/libssp.a
1332                 LIBSTDCXX?=     ${DESTDIR}/usr/lib/libstdc++.a
1333                 LIBSUPCXX?=     ${DESTDIR}/usr/lib/libsupc++.a
1334                 LIBTERMCAP?=    ${DESTDIR}/usr/lib/libtermcap.a
1335                 LIBUSBHID?=     ${DESTDIR}/usr/lib/libusbhid.a
1336                 LIBUTIL?=       ${DESTDIR}/usr/lib/libutil.a
1337                 LIBWRAP?=       ${DESTDIR}/usr/lib/libwrap.a
1338                 LIBY?=          ${DESTDIR}/usr/lib/liby.a
1339                 LIBZ?=          ${DESTDIR}/usr/lib/libz.a
1340
1341 SHAREDSTRINGS   If defined, a new .c.o rule is used that results in shared
1342                 strings, using xstr(1). Note that this will not work with
1343                 parallel makes.
1344
1345 STRIPFLAG       The flag passed to the install program to cause the binary
1346                 to be stripped.
1347
1348 SUBDIR          A list of subdirectories that should be built as well.
1349                 Each of the targets will execute the same target in the
1350                 subdirectories.
1351
1352 SCRIPTS         A list of interpreter scripts [file.{sh,csh,pl,awk,...}].
1353                 These are installed exactly like programs.
1354
1355 SCRIPTSDIR      The location to install the scripts.  Each script can be
1356                 installed to a separate path by setting SCRIPTSDIR_<script>.
1357
1358 SCRIPTSNAME     The name that the above program will be installed as, if
1359                 different from ${SCRIPTS}. These can be further specialized
1360                 by setting SCRIPTSNAME_<script>.
1361
1362 FILES           See description of <bsd.files.mk>.
1363
1364 SHLINKDIR       Target directory for shared linker.  See description of
1365                 <bsd.own.mk> for additional information about this variable.
1366
1367 The include file <bsd.prog.mk> includes the file named "../Makefile.inc"
1368 if it exists, as well as the include file <bsd.man.mk>.
1369
1370 Some simple examples:
1371
1372 To build foo from foo.c with a manual page foo.1, use:
1373
1374         PROG=   foo
1375
1376         .include <bsd.prog.mk>
1377
1378 To build foo from foo.c with a manual page foo.2, add the line:
1379
1380         MAN=    foo.2
1381
1382 If foo does not have a manual page at all, add the line:
1383
1384         MKMAN=  no
1385
1386 If foo has multiple source files, add the line:
1387
1388         SRCS=   a.c b.c c.c d.c
1389
1390
1391 =-=-=-=-=   bsd.rpc.mk   =-=-=-=-=
1392
1393 The include file <bsd.rpc.mk> contains a makefile fragment used to
1394 construct source files built by rpcgen.
1395
1396 The following macros may be defined in makefiles which include
1397 <bsd.rpc.mk> in order to control which files get built and how they
1398 are to be built:
1399
1400 RPC_INCS:       construct .h file from .x file
1401 RPC_XDRFILES:   construct _xdr.c from .x file
1402                 (for marshalling/unmarshalling data types)
1403 RPC_SVCFILES:   construct _svc.c from .x file
1404                 (server-side stubs)
1405 RPC_SVCFLAGS:   Additional flags passed to builds of RPC_SVCFILES.
1406
1407 RPC_XDIR:       Directory containing .x/.h files
1408
1409
1410 =-=-=-=-=   bsd.shlib.mk   =-=-=-=-=
1411
1412 The include file <bsd.shlib.mk> computes parameters for shared library
1413 installation and use.  It defines no targets.  <bsd.own.mk> MUST be
1414 included before <bsd.shlib.mk>.
1415
1416 <bsd.own.mk> sets the following variables, if they are not already defined
1417 (defaults are in brackets):
1418
1419 SHLIBINSTALLDIR If ${USE_SHLIBDIR} is not "no", use ${SHLIBINSTALLDIR}
1420                 instead of ${LIBDIR} as the base path for shared library
1421                 installation.  [/lib]
1422
1423 SHLIBDIR        The path to USE_SHLIBDIR shared libraries to use when building
1424                 a program.  [/lib for programs in /bin and /sbin, /usr/lib
1425                 for all others.]
1426
1427 _LIBSODIR       Set to ${SHLIBINSTALLDIR} if ${USE_SHLIBDIR} is not "no",
1428                 otherwise set to ${LIBDIR}
1429
1430 SHLINKINSTALLDIR Base path for shared linker.  [/libexec]
1431
1432 SHLINKDIR       Path to use for shared linker when building a program.
1433                 [/libexec for programs in /bin and /sbin, /usr/libexec for
1434                 all others.]
1435
1436
1437 =-=-=-=-=   bsd.subdir.mk   =-=-=-=-=
1438
1439 The include file <bsd.subdir.mk> contains the default targets for building
1440 subdirectories.  It has the same eight targets as <bsd.prog.mk>: all,
1441 clean, cleandir, depend, includes, install, lint, and tags.  It uses the
1442 following variables:
1443
1444 NOSUBDIR        If this variable is defined, then the SUBDIR variable
1445                 will be ignored and subdirectories will not be processed.
1446
1447 SUBDIR          For all of the directories listed in ${SUBDIR}, the
1448                 specified directory will be visited and the target made.
1449                 There is also a default target which allows the command
1450                 "make subdir" where subdir is any directory listed in
1451                 ${SUBDIR}.
1452
1453                 As a special case, the use of a token .WAIT as an
1454                 entry in SUBDIR acts as a synchronization barrier
1455                 when multiple make jobs are run; subdirs before the
1456                 .WAIT must complete before any subdirs after .WAIT are
1457                 started.  See make(1) for some caveats on use of .WAIT
1458                 and other special sources.
1459
1460
1461 =-=-=-=-=   bsd.sys.mk   =-=-=-=-=
1462
1463 The include file <bsd.sys.mk> is used by <bsd.prog.mk> and
1464 <bsd.lib.mk>.  It contains overrides that are used when building
1465 the NetBSD source tree.
1466
1467 The following variables control how various files are compiled/built.
1468 (Note that these may be overridden in <bsd.own.mk> if USETOOLS == "yes"):
1469
1470 AR              Create, modify, and extract from archives.  [ar]
1471
1472 ARFLAGS         Options to ${AR}.  [rl]
1473
1474 AS              Assembler.  [as]
1475
1476 AFLAGS          Options to ${CC} when compiling or linking .s or .S
1477                 assembly source files.  []
1478
1479 BUILDSEED       GCC uses random numbers when compiling C++ code.
1480                 If this option is present, seed the random number
1481                 generator based on the value, source file names and
1482                 the output file name to make builds more deterministic.
1483                 Additional information is available in the GCC
1484                 documentation of -frandom-seed.
1485
1486 CC              C compiler.  [cc]
1487
1488 CFLAGS          Options to ${CC}.  [Usually -O or -O2]
1489
1490 CPP             C Pre-Processor.  [cpp]
1491
1492 CPPFLAGS        Options to ${CPP}.  []
1493
1494 CPUFLAGS        Optimization flags for ${CC}.  []
1495
1496 CXX             C++ compiler.  [c++]
1497
1498 CXXFLAGS        Options to ${CXX}.  [${CFLAGS}]
1499
1500 ELF2ECOFF       Convert ELF-format executable to ECOFF.  [elf2ecoff]
1501
1502 FC              Fortran compiler.  [f77]
1503
1504 FFLAGS          Options to {$FC}.  [-O]
1505
1506 HOST_SH         Shell.  This must be an absolute path, because it may be
1507                 substituted into "#!" lines in scripts.  [/bin/sh]
1508
1509 INSTALL         install(1) command.  [install]
1510
1511 LEX             Lexical analyzer.  [lex]
1512
1513 LFLAGS          Options to ${LEX}.  []
1514
1515 LPREFIX         Symbol prefix for ${LEX} (see -P option in lex(1)) [yy]
1516
1517 LD              Linker.  [ld]
1518
1519 LDFLAGS         Options to ${CC} during the link process.  []
1520
1521 LINT            C program verifier.  [lint]
1522
1523 LINTFLAGS       Options to ${LINT}.  [-chapbxzFS]
1524
1525 LORDER          List dependencies for object files.  [lorder]
1526
1527 MAKE            make(1).  [make]
1528
1529 MKDEP           Construct Makefile dependency list.  [mkdep]
1530
1531 NM              List symbols from object files.  [nm]
1532
1533 PC              Pascal compiler.  [pc]  (Not present)
1534
1535 PFLAGS          Options to ${PC}.  []
1536
1537 OBJC            Objective C compiler.  [${CC}]
1538
1539 OBJCFLAGS       Options to ${OBJC}.  [${CFLAGS}]
1540
1541 OBJCOPY         Copy and translate object files.  [objcopy]
1542
1543 OBJDUMP         Display information from object files.  [objdump]
1544
1545 RANLIB          Generate index to archive.  [ranlib]
1546
1547 SIZE            List section sizes and total size.  [size]
1548
1549 STRIP           Discard symbols from object files.  [strip]
1550
1551 TSORT           Topological sort of a directed graph.  [tsort -q]
1552
1553 YACC            LALR(1) parser generator.  [yacc]
1554
1555 YFLAGS          Options to ${YACC}.  []
1556
1557 YHEADER         If defined, add "-d" to YFLAGS, and add dependencies
1558                 from <file>.y to <file>.h and <file>.c, and add
1559                 <foo>.h to CLEANFILES.
1560
1561 YPREFIX         If defined, add "-p ${YPREFIX}" to YFLAGS.
1562
1563
1564 Other variables of note (incomplete list):
1565
1566 NOGCCERROR      If defined, prevents passing certain ${CFLAGS} to GCC
1567                 that cause warnings to be fatal, such as:
1568                         -Werror -Wa,--fatal-warnings
1569                 (The latter being for as(1).)
1570
1571 WARNS           Crank up GCC warning options; the distinct levels are:
1572                         WARNS=1
1573                         WARNS=2
1574                         WARNS=3
1575                         WARNS=4
1576
1577 =-=-=-=-=   bsd.x11.mk   =-=-=-=-=
1578
1579 The include file <bsd.x11.mk> contains parameters and targets for
1580 cross-building X11 from ${X11SRCDIR.xc} / ${X11MITSRCDIR.*}.
1581 It should be included after the general Makefile contents but before
1582 the include files such as <bsd.prog.mk> and <bsd.lib.mk>.
1583
1584 It provides the following targets:
1585         .man.1 .man.3 .man.4 .man.5 .man.7:
1586                 If ${MAN} or ${PROG} is set and ${MKMAN} != "no",
1587                 these rules convert from X11's manual page source
1588                 into an mdoc.old source file.
1589         cleanx11man:
1590                 Clean up the mdoc.old files generated by the above.
1591
1592 It sets the following variables:
1593
1594 BINDIR                  Set to ${X11BINDIR}.
1595                         To override, define after including <bsd.x11.mk>
1596
1597 LIBDIR                  Set to ${X11USRLIBDIR}.
1598                         To override, define after including <bsd.x11.mk>
1599
1600 MANDIR                  Set to ${X11MANDIR}.
1601                         To override, define after including <bsd.x11.mk>
1602
1603 CPPFLAGS                Appended with definitions to include from
1604                         ${DESTDIR}${X11INCDIR}
1605
1606 LDFLAGS                 Appended with definitions to link from
1607                         ${DESTDIR}${X11USRLIBDIR}
1608
1609 X11FLAGS.CONNECTION     Equivalent to X11's CONNECTION_FLAGS.
1610
1611 X11FLAGS.EXTENSION      Equivalent to X11's EXT_DEFINES.
1612
1613 X11FLAGS.LOADABLE       Equivalent to X11's LOADABLE.
1614
1615 X11FLAGS.OS_DEFINES     Equivalent to X11's OS_DEFINES.
1616
1617 X11FLAGS.SERVER         Equivalent to X11's ServerDefines.
1618
1619 X11FLAGS.THREADLIB      Equivalent to X11's THREADS_DEFINES for libraries.
1620
1621 X11FLAGS.THREADS        Equivalent to X11's THREADS_DEFINES.
1622
1623 X11FLAGS.VERSION        cpp(1) definitions of OSMAJORVERSION and OSMINORVERSION.
1624
1625 X11FLAGS.DIX            Equivalent to X11's DIX_DEFINES.
1626
1627 X11TOOL_UNXCOMM         Commandline to convert `XCOMM' comments to `#'
1628
1629 It uses the following variables:
1630
1631 APPDEFS                 List of app-default files to install.
1632
1633 CPPSCRIPTS              List of files/scripts to run through cpp(1)
1634                         and then ${X11TOOL_UNXCOMM}.  The source files
1635                         have a `.cpp' suffix, the generated files do not.
1636
1637 CPPSCRIPTFLAGS          Additional flags to cpp(1) when building CPPSCRIPTS.
1638
1639 CPPSCRIPTFLAGS_<fn>     Additional flags to cpp(1) when building CPPSCRIPT <fn>.
1640
1641
1642 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=