share/man/man7/build.7

   1 .\" Copyright (c) 2000
   2 .\"     Mike W. Meyer
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd March 22, 2017
  28 .Dt BUILD 7
  29 .Os
  30 .Sh NAME
  31 .Nm build
  32 .Nd information on how to build the system
  33 .Sh DESCRIPTION
  34 The sources for the
  35 .Fx
  36 system and its applications are contained in three different directories,
  37 normally
  38 .Pa /usr/src ,
  39 .Pa /usr/doc ,
  40 and
  41 .Pa /usr/ports .
  42 These directories may be initially empty or non-existent until updated with
  43 .Xr svn 1
  44 or
  45 .Xr portsnap 8 .
  46 Directory
  47 .Pa /usr/src
  48 contains the
  49 .Dq "base system"
  50 sources, which is loosely defined as the things required to rebuild
  51 the system to a useful state.
  52 Directory
  53 .Pa /usr/doc
  54 contains the source for the system documentation, excluding the manual
  55 pages.
  56 Directory
  57 .Pa /usr/ports
  58 contains a tree that provides a consistent interface for building and
  59 installing third party applications.
  60 For more information about the ports build process, see
  61 .Xr ports 7 .
  62 .Pp
  63 The
  64 .Xr make 1
  65 command is used in each of these directories to build and install the
  66 things in that directory.
  67 Issuing the
  68 .Xr make 1
  69 command in any directory or
  70 subdirectory of those directories has the same effect as issuing the
  71 same command in all subdirectories of that directory.
  72 With no target specified, the things in that directory are just built.
  73 .Pp
  74 A source tree is allowed to be read-only.
  75 As described in
  76 .Xr make 1 ,
  77 objects are usually built in a separate object directory hierarchy
  78 specified by the environment variable
  79 .Va MAKEOBJDIRPREFIX ,
  80 or under
  81 .Pa /usr/obj
  82 if variable
  83 .Va MAKEOBJDIRPREFIX
  84 is not set.
  85 For a given source directory, its canonical object directory
  86 would be
  87 .Pa ${MAKEOBJDIRPREFIX}${.CURDIR}
  88 if
  89 .Xr make 1
  90 variable
  91 .Va MAKEOBJDIRPREFIX
  92 is set, or
  93 .Pa /usr/obj${.CURDIR}
  94 if this variable is not set.
  95 Cross-builds set the object directory as described in the
  96 documentation for the
  97 .Cm buildworld
  98 target below.
  99 .Pp
 100 The build may be controlled by defining
 101 .Xr make 1
 102 variables described in the
 103 .Sx ENVIRONMENT
 104 section below, and by the variables documented in
 105 .Xr make.conf 5 .
 106 .Pp
 107 The following list provides the names and actions for the targets
 108 supported by the build system:
 109 .Bl -tag -width ".Cm cleandepend"
 110 .It Cm check
 111 Run tests for a given subdirectory.
 112 The default directory used is
 113 .Pa ${.OBJDIR} ,
 114 but the check directory can be changed with
 115 .Pa ${CHECKDIR} .
 116 .It Cm checkworld
 117 Run the
 118 .Fx
 119 test suite on installed world.
 120 .It Cm clean
 121 Remove any files created during the build process.
 122 .It Cm cleandepend
 123 Remove the file
 124 .Pa ${.OBJDIR}/${DEPENDFILE}
 125 generated by a prior
 126 .Dq Li "make depend"
 127 step.
 128 .It Cm cleandir
 129 Remove the canonical object directory if it exists, or perform
 130 actions equivalent to
 131 .Dq Li "make clean cleandepend"
 132 if it does not.
 133 This target will also remove an
 134 .Pa obj
 135 link in
 136 .Pa ${.CURDIR}
 137 if that exists.
 138 .Pp
 139 It is advisable to run
 140 .Dq Li "make cleandir"
 141 twice: the first invocation will remove the canonical object directory
 142 and the second one will clean up
 143 .Pa ${.CURDIR} .
 144 .It Cm depend
 145 Generate a list of build dependencies in file
 146 .Pa ${.OBJDIR}/${DEPENDFILE} .
 147 .It Cm install
 148 Install the results of the build to the appropriate location in the
 149 installation directory hierarchy specified in variable
 150 .Va DESTDIR .
 151 .It Cm obj
 152 Create the canonical object directory associated with the current
 153 directory.
 154 .It Cm objlink
 155 Create a symbolic link to the canonical object directory in
 156 .Pa ${.CURDIR} .
 157 .It Cm tags
 158 Generate a tags file using the program specified in the
 159 .Xr make 1
 160 variable
 161 .Va CTAGS .
 162 The build system supports
 163 .Xr ctags 1
 164 and
 165 .Nm "GNU Global" .
 166 .El
 167 .Pp
 168 The other supported targets under directory
 169 .Pa /usr/src
 170 are:
 171 .Bl -tag -width ".Cm distributeworld"
 172 .It Cm buildenv
 173 Spawn an interactive shell with environment variables set up for
 174 cross-building the system.
 175 The target architecture needs to be specified with
 176 .Xr make 1
 177 variables
 178 .Va TARGET_ARCH
 179 and
 180 .Va TARGET .
 181 .Pp
 182 This target is only useful after a complete cross-toolchain including
 183 the compiler, linker, assembler, headers and libraries has been
 184 built; see the
 185 .Cm toolchain
 186 target below.
 187 .It Cm buildworld
 188 Build everything but the kernel, configure files in
 189 .Pa etc ,
 190 and
 191 .Pa release .
 192 The object directory can be changed from the default
 193 .Pa /usr/obj
 194 by setting the
 195 .Pa MAKEOBJDIRPREFIX
 196 .Xr make 1
 197 variable.
 198 The actual build location prefix used is
 199 .Pa ${MAKEOBJDIRPREFIX}${.CURDIR}
 200 for native builds, and
 201 .Pa ${MAKEOBJDIRPREFIX}/${TARGET}${.CURDIR}
 202 for cross builds and native builds with variable
 203 .Va CROSS_BUILD_TESTING
 204 set.
 205 .It Cm cleanworld
 206 Attempt to clean up targets built by a preceding
 207 .Cm buildworld
 208 step.
 209 .It Cm distributeworld
 210 Distribute everything compiled by a preceding
 211 .Cm buildworld
 212 step.
 213 Files are placed in the directory hierarchy specified by
 214 .Xr make 1
 215 variable
 216 .Va DISTDIR .
 217 This target is used while building a release; see
 218 .Xr release 7 .
 219 .It Cm packageworld
 220 Archive the results of
 221 .Cm distributeworld ,
 222 placing the results in
 223 .Va DISTDIR .
 224 This target is used while building a release; see
 225 .Xr release 7 .
 226 .It Cm installworld
 227 Install everything built by a preceding
 228 .Cm buildworld
 229 step into the directory hierarchy pointed to by
 230 .Xr make 1
 231 variable
 232 .Va DESTDIR .
 233 .Pp
 234 If installing onto an NFS file system and running
 235 .Xr make 1
 236 with the
 237 .Fl j
 238 option, make sure that
 239 .Xr rpc.lockd 8
 240 is running on both client and server.
 241 See
 242 .Xr rc.conf 5
 243 on how to make it start at boot time.
 244 .It Cm toolchain
 245 Create the build toolchain needed to build the rest of the system.
 246 For cross-architecture builds, this step creates a cross-toolchain.
 247 .It Cm universe
 248 For each architecture,
 249 execute a
 250 .Cm buildworld
 251 followed by a
 252 .Cm buildkernel
 253 for all kernels for that architecture,
 254 including
 255 .Pa LINT .
 256 This command takes a long time.
 257 .It Cm update
 258 Get updated sources as configured in
 259 .Xr make.conf 5 .
 260 .It Cm targets
 261 Print a list of supported
 262 .Va TARGET
 263 /
 264 .Va TARGET_ARCH
 265 pairs for world and kernel targets.
 266 .It Cm tinderbox
 267 Execute the same targets as
 268 .Cm universe .
 269 In addition print a summary of all failed targets at the end and
 270 exit with an error if there were any.
 271 .It Cm toolchains
 272 Create a build toolchain for each architecture supported by the build system.
 273 .El
 274 .Pp
 275 Kernel specific build targets in
 276 .Pa /usr/src
 277 are:
 278 .Bl -tag -width ".Cm distributekernel"
 279 .It Cm buildkernel
 280 Rebuild the kernel and the kernel modules.
 281 The object directory can be changed from the default
 282 .Pa /usr/obj
 283 by setting the
 284 .Pa MAKEOBJDIRPREFIX
 285 .Xr make 1
 286 variable.
 287 .It Cm installkernel
 288 Install the kernel and the kernel modules to directory
 289 .Pa ${DESTDIR}/boot/kernel ,
 290 renaming any pre-existing directory with this name to
 291 .Pa kernel.old
 292 if it contained the currently running kernel.
 293 The target directory under
 294 .Pa ${DESTDIR}
 295 may be modified using the
 296 .Va INSTKERNNAME
 297 and
 298 .Va KODIR
 299 .Xr make 1
 300 variables.
 301 .It Cm distributekernel
 302 Install the kernel to the directory
 303 .Pa ${DISTDIR}/kernel/boot/kernel .
 304 This target is used while building a release; see
 305 .Xr release 7 .
 306 .It Cm packagekernel
 307 Archive the results of
 308 .Cm distributekernel ,
 309 placing the results in
 310 .Va DISTDIR .
 311 This target is used while building a release; see
 312 .Xr release 7 .
 313 .It Cm kernel
 314 Equivalent to
 315 .Cm buildkernel
 316 followed by
 317 .Cm installkernel
 318 .It Cm kernel-toolchain
 319 Rebuild the tools needed for kernel compilation.
 320 Use this if you did not do a
 321 .Cm buildworld
 322 first.
 323 .It Cm reinstallkernel
 324 Reinstall the kernel and the kernel modules, overwriting the contents
 325 of the target directory.
 326 As with the
 327 .Cm installkernel
 328 target, the target directory can be specified using the
 329 .Xr make 1
 330 variable
 331 .Va INSTKERNNAME .
 332 .El
 333 .Pp
 334 Convenience targets for cleaning up the install destination directory
 335 denoted by variable
 336 .Va DESTDIR
 337 include:
 338 .Bl -tag -width ".Cm delete-old-libs"
 339 .It Cm check-old
 340 Print a list of old files and directories in the system.
 341 .It Cm delete-old
 342 Delete obsolete base system files and directories interactively.
 343 When
 344 .Li -DBATCH_DELETE_OLD_FILES
 345 is specified at the command line, the delete operation will be
 346 non-interactive.
 347 The variables
 348 .Va DESTDIR ,
 349 .Va TARGET_ARCH
 350 and
 351 .Va TARGET
 352 should be set as with
 353 .Dq Li "make installworld" .
 354 .It Cm delete-old-libs
 355 Delete obsolete base system libraries interactively.
 356 This target should only be used if no third party software uses these
 357 libraries.
 358 When
 359 .Li -DBATCH_DELETE_OLD_FILES
 360 is specified at the command line, the delete operation will be
 361 non-interactive.
 362 The variables
 363 .Va DESTDIR ,
 364 .Va TARGET_ARCH
 365 and
 366 .Va TARGET
 367 should be set as with
 368 .Dq Li "make installworld" .
 369 .El
 370 .Sh ENVIRONMENT
 371 Variables that influence all builds include:
 372 .Bl -tag -width ".Va MAKEOBJDIRPREFIX"
 373 .It Va DEBUG_FLAGS
 374 Defines a set of debugging flags that will be used to build all userland
 375 binaries under
 376 .Pa /usr/src .
 377 When
 378 .Va DEBUG_FLAGS
 379 is defined, the
 380 .Cm install
 381 and
 382 .Cm installworld
 383 targets install binaries from the current
 384 .Va MAKEOBJDIRPREFIX
 385 without stripping,
 386 so that debugging information is retained in the installed binaries.
 387 .It Va DESTDIR
 388 The directory hierarchy prefix where built objects will be installed.
 389 If not set,
 390 .Va DESTDIR
 391 defaults to the empty string.
 392 .It Va MAKEOBJDIRPREFIX
 393 Defines the prefix for directory names in the tree of built objects.
 394 Defaults to
 395 .Pa /usr/obj
 396 if not defined.
 397 This variable should only be set in the environment and not via
 398 .Pa /etc/make.conf
 399 or the command line.
 400 .It Va NO_WERROR
 401 If defined, compiler warnings will not cause the build to halt,
 402 even if the makefile says otherwise.
 403 .It Va WITH_CTF
 404 If defined, the build process will run the DTrace CTF conversion
 405 tools on built objects.
 406 .El
 407 .Pp
 408 Additionally, builds in
 409 .Pa /usr/src
 410 are influenced by the following
 411 .Xr make 1
 412 variables:
 413 .Bl -tag -width ".Va SUBDIR_OVERRIDE"
 414 .It Va KERNCONF
 415 Overrides which kernel to build and install for the various kernel
 416 make targets.
 417 It defaults to
 418 .Cm GENERIC .
 419 .It Va KERNFAST
 420 If set, the build target
 421 .Cm buildkernel
 422 defaults to setting
 423 .Va NO_KERNELCLEAN ,
 424 .Va NO_KERNELCONFIG ,
 425 .Va NO_KERNELDEPEND
 426 and
 427 .Va NO_KERNELOBJ .
 428 When set to a value other than
 429 .Cm 1
 430 then
 431 .Va KERNCONF
 432 is set to the value of
 433 .Va KERNFAST .
 434 .It Va LOCAL_DIRS
 435 If set, this variable supplies a list of additional directories relative to
 436 the root of the source tree to build as part of the
 437 .Cm everything
 438 target.
 439 .It Va LOCAL_ITOOLS
 440 If set, this variable supplies a list of additional tools that are used by the
 441 .Cm installworld
 442 and
 443 .Cm distributeworld
 444 targets.
 445 .It Va LOCAL_LIB_DIRS
 446 If set, this variable supplies a list of additional directories relative to
 447 the root of the source tree to build as part of the
 448 .Cm libraries
 449 target.
 450 .It Va LOCAL_MTREE
 451 If set, this variable supplies a list of additional mtrees relative to the
 452 root of the source tree to use as part of the
 453 .Cm hierarchy
 454 target.
 455 .It Va LOCAL_TOOL_DIRS
 456 If set, this variable supplies a list of additional directories relative to
 457 the root of the source tree to build as part of the
 458 .Cm build-tools
 459 target.
 460 .It Va PORTS_MODULES
 461 A list of ports with kernel modules that should be built and installed
 462 as part of the
 463 .Cm buildkernel
 464 and
 465 .Cm installkernel
 466 process.
 467 .Bd -literal -offset indent
 468 make PORTS_MODULES=emulators/kqemu-kmod kernel
 469 .Ed
 470 .It Va STRIPBIN
 471 Command to use at install time when stripping binaries.
 472 Be sure to add any additional tools required to run
 473 .Va STRIPBIN
 474 to the
 475 .Va LOCAL_ITOOLS
 476 .Xr make 1
 477 variable before running the
 478 .Cm distributeworld
 479 or
 480 .Cm installworld
 481 targets.
 482 See
 483 .Xr install 1
 484 for more details.
 485 .It Va SUBDIR_OVERRIDE
 486 Override the default list of sub-directories and only build the
 487 sub-directory named in this variable.
 488 This variable is useful when debugging failed builds.
 489 .Bd -literal -offset indent
 490 make some-target SUBDIR_OVERRIDE=foo/bar
 491 .Ed
 492 .It Va TARGET
 493 The target hardware platform.
 494 This is analogous to the
 495 .Dq Nm uname Fl m
 496 output.
 497 This is necessary to cross-build some target architectures.
 498 For example, cross-building for PC98 machines requires
 499 .Va TARGET_ARCH Ns = Ns Li i386
 500 and
 501 .Va TARGET Ns = Ns Li pc98 .
 502 If not set,
 503 .Va TARGET
 504 defaults to the current hardware platform.
 505 .It Va TARGET_ARCH
 506 The target machine processor architecture.
 507 This is analogous to the
 508 .Dq Nm uname Fl p
 509 output.
 510 Set this to cross-build for a different architecture.
 511 If not set,
 512 .Va TARGET_ARCH
 513 defaults to the current machine architecture, unless
 514 .Va TARGET
 515 is also set, in which case it defaults to the appropriate
 516 value for that platform.
 517 Typically, one only needs to set
 518 .Va TARGET .
 519 .El
 520 .Pp
 521 Builds under directory
 522 .Pa /usr/src
 523 are also influenced by defining one or more of the following symbols,
 524 using the
 525 .Fl D
 526 option of
 527 .Xr make 1 :
 528 .Bl -tag -width ".Va -DNO_KERNELDEPEND"
 529 .It Va NO_CLEANDIR
 530 If set, the build targets that clean parts of the object tree use the
 531 equivalent of
 532 .Dq make clean
 533 instead of
 534 .Dq make cleandir .
 535 .It Va NO_CLEAN
 536 If set, no object tree files are cleaned at all.
 537 Setting
 538 .Va NO_CLEAN
 539 implies
 540 .Va NO_KERNELCLEAN ,
 541 so when
 542 .Va NO_CLEAN
 543 is set no kernel objects are cleaned either.
 544 .It Va NO_CTF
 545 If set, the build process does not run the DTrace CTF conversion tools
 546 on built objects.
 547 .It Va NO_SHARE
 548 If set, the build does not descend into the
 549 .Pa /usr/src/share
 550 subdirectory (i.e., manual pages, locale data files, timezone data files and
 551 other
 552 .Pa /usr/src/share
 553 files will not be rebuild from their sources).
 554 .It Va NO_KERNELCLEAN
 555 If set, the build process does not run
 556 .Dq make clean
 557 as part of the
 558 .Cm buildkernel
 559 target.
 560 .It Va NO_KERNELCONFIG
 561 If set, the build process does not run
 562 .Xr config 8
 563 as part of the
 564 .Cm buildkernel
 565 target.
 566 .It Va NO_KERNELDEPEND
 567 If set, the build process does not run
 568 .Dq make depend
 569 as part of the
 570 .Cm buildkernel
 571 target.
 572 .It Va NO_KERNELOBJ
 573 If set, the build process does not run
 574 .Dq make obj
 575 as part of the
 576 .Cm buildkernel
 577 target.
 578 .It Va NO_DOCUPDATE
 579 If set, the update process does not update the source of the
 580 .Fx
 581 documentation as part of the
 582 .Dq make update
 583 target.
 584 .It Va NO_PORTSUPDATE
 585 If set, the update process does not update the Ports tree as part of the
 586 .Dq make update
 587 target.
 588 .It Va NO_WWWUPDATE
 589 If set, the update process does not update the www tree as part of the
 590 .Dq make update
 591 target.
 592 .El
 593 .Pp
 594 Builds under directory
 595 .Pa /usr/doc
 596 are influenced by the following
 597 .Xr make 1
 598 variables:
 599 .Bl -tag -width ".Va DOC_LANG"
 600 .It Va DOC_LANG
 601 If set, restricts the documentation build to the language subdirectories
 602 specified as its content.
 603 The default action is to build documentation for all languages.
 604 .El
 605 .Pp
 606 Builds using the
 607 .Cm universe
 608 target are influenced by the following
 609 .Xr make 1
 610 variables:
 611 .Bl -tag -width ".Va MAKE_JUST_KERNELS"
 612 .It Va JFLAG
 613 Pass the value of this variable to each
 614 .Xr make 1
 615 invocation used to build worlds and kernels.
 616 This can be used to enable multiple jobs within a single architecture's build
 617 while still building each architecture serially.
 618 .It Va MAKE_JUST_KERNELS
 619 Only build kernels for each supported architecture.
 620 .It Va MAKE_JUST_WORLDS
 621 Only build worlds for each supported architecture.
 622 .It Va UNIVERSE_TARGET
 623 Execute the specified
 624 .Xr make 1
 625 target for each supported architecture instead of the default action of
 626 building a world and one or more kernels.
 627 .El
 628 .Sh FILES
 629 .Bl -tag -width ".Pa /usr/share/examples/etc/make.conf" -compact
 630 .It Pa /usr/doc/Makefile
 631 .It Pa /usr/doc/share/mk/doc.project.mk
 632 .It Pa /usr/ports/Mk/bsd.port.mk
 633 .It Pa /usr/ports/Mk/bsd.sites.mk
 634 .It Pa /usr/share/examples/etc/make.conf
 635 .It Pa /usr/src/Makefile
 636 .It Pa /usr/src/Makefile.inc1
 637 .El
 638 .Sh EXAMPLES
 639 For an
 640 .Dq approved
 641 method of updating your system from the latest sources, please see the
 642 .Sx COMMON ITEMS
 643 section in
 644 .Pa src/UPDATING .
 645 .Pp
 646 The following sequence of commands can be used to cross-build the
 647 system for the sparc64 architecture on an i386 host:
 648 .Bd -literal -offset indent
 649 cd /usr/src
 650 make TARGET=sparc64 buildworld
 651 make TARGET=sparc64 DESTDIR=/clients/sparc64 installworld
 652 .Ed
 653 .Sh SEE ALSO
 654 .Xr cc 1 ,
 655 .Xr install 1 ,
 656 .Xr make 1 ,
 657 .Xr svn 1 ,
 658 .Xr make.conf 5 ,
 659 .Xr src.conf 5 ,
 660 .Xr ports 7 ,
 661 .Xr release 7 ,
 662 .Xr tests 7 ,
 663 .Xr config 8 ,
 664 .Xr mergemaster 8 ,
 665 .Xr portsnap 8 ,
 666 .Xr reboot 8 ,
 667 .Xr shutdown 8
 668 .Sh AUTHORS
 669 .An Mike W. Meyer Aq mwm@mired.org .