share/mk/bsd.README

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