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 April 28, 2016
  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 clean
 111 Remove any files created during the build process.
 112 .It Cm cleandepend
 113 Remove the file
 114 .Pa ${.OBJDIR}/${DEPENDFILE}
 115 generated by a prior
 116 .Dq Li "make depend"
 117 step.
 118 .It Cm cleandir
 119 Remove the canonical object directory if it exists, or perform
 120 actions equivalent to
 121 .Dq Li "make clean cleandepend"
 122 if it does not.
 123 This target will also remove an
 124 .Pa obj
 125 link in
 126 .Pa ${.CURDIR}
 127 if that exists.
 128 .Pp
 129 It is advisable to run
 130 .Dq Li "make cleandir"
 131 twice: the first invocation will remove the canonical object directory
 132 and the second one will clean up
 133 .Pa ${.CURDIR} .
 134 .It Cm depend
 135 Generate a list of build dependencies in file
 136 .Pa ${.OBJDIR}/${DEPENDFILE} .
 137 .It Cm install
 138 Install the results of the build to the appropriate location in the
 139 installation directory hierarchy specified in variable
 140 .Va DESTDIR .
 141 .It Cm obj
 142 Create the canonical object directory associated with the current
 143 directory.
 144 .It Cm objlink
 145 Create a symbolic link to the canonical object directory in
 146 .Pa ${.CURDIR} .
 147 .It Cm tags
 148 Generate a tags file using the program specified in the
 149 .Xr make 1
 150 variable
 151 .Va CTAGS .
 152 The build system supports
 153 .Xr ctags 1
 154 and
 155 .Nm "GNU Global" .
 156 .El
 157 .Pp
 158 The other supported targets under directory
 159 .Pa /usr/src
 160 are:
 161 .Bl -tag -width ".Cm distributeworld"
 162 .It Cm buildenv
 163 Spawn an interactive shell with environment variables set up for
 164 cross-building the system.
 165 The target architecture needs to be specified with
 166 .Xr make 1
 167 variables
 168 .Va TARGET_ARCH
 169 and
 170 .Va TARGET .
 171 .Pp
 172 This target is only useful after a complete cross-toolchain including
 173 the compiler, linker, assembler, headers and libraries has been
 174 built; see the
 175 .Cm toolchain
 176 target below.
 177 .It Cm buildworld
 178 Build everything but the kernel, configure files in
 179 .Pa etc ,
 180 and
 181 .Pa release .
 182 The object directory can be changed from the default
 183 .Pa /usr/obj
 184 by setting the
 185 .Pa MAKEOBJDIRPREFIX
 186 .Xr make 1
 187 variable.
 188 The actual build location prefix used is
 189 .Pa ${MAKEOBJDIRPREFIX}${.CURDIR}
 190 for native builds, and
 191 .Pa ${MAKEOBJDIRPREFIX}/${TARGET}${.CURDIR}
 192 for cross builds and native builds with variable
 193 .Va CROSS_BUILD_TESTING
 194 set.
 195 .It Cm cleanworld
 196 Attempt to clean up targets built by a preceding
 197 .Cm buildworld
 198 step.
 199 .It Cm distributeworld
 200 Distribute everything compiled by a preceding
 201 .Cm buildworld
 202 step.
 203 Files are placed in the directory hierarchy specified by
 204 .Xr make 1
 205 variable
 206 .Va DISTDIR .
 207 This target is used while building a release; see
 208 .Xr release 7 .
 209 .It Cm packageworld
 210 Archive the results of
 211 .Cm distributeworld ,
 212 placing the results in
 213 .Va DISTDIR .
 214 This target is used while building a release; see
 215 .Xr release 7 .
 216 .It Cm installworld
 217 Install everything built by a preceding
 218 .Cm buildworld
 219 step into the directory hierarchy pointed to by
 220 .Xr make 1
 221 variable
 222 .Va DESTDIR .
 223 .Pp
 224 If installing onto an NFS file system and running
 225 .Xr make 1
 226 with the
 227 .Fl j
 228 option, make sure that
 229 .Xr rpc.lockd 8
 230 is running on both client and server.
 231 See
 232 .Xr rc.conf 5
 233 on how to make it start at boot time.
 234 .It Cm toolchain
 235 Create the build toolchain needed to build the rest of the system.
 236 For cross-architecture builds, this step creates a cross-toolchain.
 237 .It Cm universe
 238 For each architecture,
 239 execute a
 240 .Cm buildworld
 241 followed by a
 242 .Cm buildkernel
 243 for all kernels for that architecture,
 244 including
 245 .Pa LINT .
 246 This command takes a long time.
 247 .It Cm update
 248 Get updated sources as configured in
 249 .Xr make.conf 5 .
 250 .It Cm targets
 251 Print a list of supported
 252 .Va TARGET
 253 /
 254 .Va TARGET_ARCH
 255 pairs for world and kernel targets.
 256 .It Cm tinderbox
 257 Execute the same targets as
 258 .Cm universe .
 259 In addition print a summary of all failed targets at the end and
 260 exit with an error if there were any.
 261 .It Cm toolchains
 262 Create a build toolchain for each architecture supported by the build system.
 263 .El
 264 .Pp
 265 Kernel specific build targets in
 266 .Pa /usr/src
 267 are:
 268 .Bl -tag -width ".Cm distributekernel"
 269 .It Cm buildkernel
 270 Rebuild the kernel and the kernel modules.
 271 The object directory can be changed from the default
 272 .Pa /usr/obj
 273 by setting the
 274 .Pa MAKEOBJDIRPREFIX
 275 .Xr make 1
 276 variable.
 277 .It Cm installkernel
 278 Install the kernel and the kernel modules to directory
 279 .Pa ${DESTDIR}/boot/kernel ,
 280 renaming any pre-existing directory with this name to
 281 .Pa kernel.old
 282 if it contained the currently running kernel.
 283 The target directory under
 284 .Pa ${DESTDIR}
 285 may be modified using the
 286 .Va INSTKERNNAME
 287 and
 288 .Va KODIR
 289 .Xr make 1
 290 variables.
 291 .It Cm distributekernel
 292 Install the kernel to the directory
 293 .Pa ${DISTDIR}/kernel/boot/kernel .
 294 This target is used while building a release; see
 295 .Xr release 7 .
 296 .It Cm packagekernel
 297 Archive the results of
 298 .Cm distributekernel ,
 299 placing the results in
 300 .Va DISTDIR .
 301 This target is used while building a release; see
 302 .Xr release 7 .
 303 .It Cm kernel
 304 Equivalent to
 305 .Cm buildkernel
 306 followed by
 307 .Cm installkernel
 308 .It Cm kernel-toolchain
 309 Rebuild the tools needed for kernel compilation.
 310 Use this if you did not do a
 311 .Cm buildworld
 312 first.
 313 .It Cm reinstallkernel
 314 Reinstall the kernel and the kernel modules, overwriting the contents
 315 of the target directory.
 316 As with the
 317 .Cm installkernel
 318 target, the target directory can be specified using the
 319 .Xr make 1
 320 variable
 321 .Va INSTKERNNAME .
 322 .El
 323 .Pp
 324 Convenience targets for cleaning up the install destination directory
 325 denoted by variable
 326 .Va DESTDIR
 327 include:
 328 .Bl -tag -width ".Cm delete-old-libs"
 329 .It Cm check-old
 330 Print a list of old files and directories in the system.
 331 .It Cm delete-old
 332 Delete obsolete base system files and directories interactively.
 333 When
 334 .Li -DBATCH_DELETE_OLD_FILES
 335 is specified at the command line, the delete operation will be
 336 non-interactive.
 337 The variables
 338 .Va DESTDIR ,
 339 .Va TARGET_ARCH
 340 and
 341 .Va TARGET
 342 should be set as with
 343 .Dq Li "make installworld" .
 344 .It Cm delete-old-libs
 345 Delete obsolete base system libraries interactively.
 346 This target should only be used if no third party software uses these
 347 libraries.
 348 When
 349 .Li -DBATCH_DELETE_OLD_FILES
 350 is specified at the command line, the delete operation will be
 351 non-interactive.
 352 The variables
 353 .Va DESTDIR ,
 354 .Va TARGET_ARCH
 355 and
 356 .Va TARGET
 357 should be set as with
 358 .Dq Li "make installworld" .
 359 .El
 360 .Sh ENVIRONMENT
 361 Variables that influence all builds include:
 362 .Bl -tag -width ".Va MAKEOBJDIRPREFIX"
 363 .It Va DEBUG_FLAGS
 364 Defines a set of debugging flags that will be used to build all userland
 365 binaries under
 366 .Pa /usr/src .
 367 When
 368 .Va DEBUG_FLAGS
 369 is defined, the
 370 .Cm install
 371 and
 372 .Cm installworld
 373 targets install binaries from the current
 374 .Va MAKEOBJDIRPREFIX
 375 without stripping,
 376 so that debugging information is retained in the installed binaries.
 377 .It Va DESTDIR
 378 The directory hierarchy prefix where built objects will be installed.
 379 If not set,
 380 .Va DESTDIR
 381 defaults to the empty string.
 382 .It Va MAKEOBJDIRPREFIX
 383 Defines the prefix for directory names in the tree of built objects.
 384 Defaults to
 385 .Pa /usr/obj
 386 if not defined.
 387 This variable should only be set in the environment and not via
 388 .Pa /etc/make.conf
 389 or the command line.
 390 .It Va NO_WERROR
 391 If defined, compiler warnings will not cause the build to halt,
 392 even if the makefile says otherwise.
 393 .It Va WITH_CTF
 394 If defined, the build process will run the DTrace CTF conversion
 395 tools on built objects.
 396 .El
 397 .Pp
 398 Additionally, builds in
 399 .Pa /usr/src
 400 are influenced by the following
 401 .Xr make 1
 402 variables:
 403 .Bl -tag -width ".Va SUBDIR_OVERRIDE"
 404 .It Va KERNCONF
 405 Overrides which kernel to build and install for the various kernel
 406 make targets.
 407 It defaults to
 408 .Cm GENERIC .
 409 .It Va KERNFAST
 410 If set, the build target
 411 .Cm buildkernel
 412 defaults to setting
 413 .Va NO_KERNELCLEAN ,
 414 .Va NO_KERNELCONFIG ,
 415 .Va NO_KERNELDEPEND
 416 and
 417 .Va NO_KERNELOBJ .
 418 When set to a value other than
 419 .Cm 1
 420 then
 421 .Va KERNCONF
 422 is set to the value of
 423 .Va KERNFAST .
 424 .It Va LOCAL_DIRS
 425 If set, this variable supplies a list of additional directories relative to
 426 the root of the source tree to build as part of the
 427 .Cm everything
 428 target.
 429 .It Va LOCAL_ITOOLS
 430 If set, this variable supplies a list of additional tools that are used by the
 431 .Cm installworld
 432 and
 433 .Cm distributeworld
 434 targets.
 435 .It Va LOCAL_LIB_DIRS
 436 If set, this variable supplies a list of additional directories relative to
 437 the root of the source tree to build as part of the
 438 .Cm libraries
 439 target.
 440 .It Va LOCAL_MTREE
 441 If set, this variable supplies a list of additional mtrees relative to the
 442 root of the source tree to use as part of the
 443 .Cm hierarchy
 444 target.
 445 .It Va LOCAL_TOOL_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 build-tools
 449 target.
 450 .It Va PORTS_MODULES
 451 A list of ports with kernel modules that should be built and installed
 452 as part of the
 453 .Cm buildkernel
 454 and
 455 .Cm installkernel
 456 process.
 457 .Bd -literal -offset indent
 458 make PORTS_MODULES=emulators/kqemu-kmod kernel
 459 .Ed
 460 .It Va STRIPBIN
 461 Command to use at install time when stripping binaries.
 462 Be sure to add any additional tools required to run
 463 .Va STRIPBIN
 464 to the
 465 .Va LOCAL_ITOOLS
 466 .Xr make 1
 467 variable before running the
 468 .Cm distributeworld
 469 or
 470 .Cm installworld
 471 targets.
 472 See
 473 .Xr install 1
 474 for more details.
 475 .It Va SUBDIR_OVERRIDE
 476 Override the default list of sub-directories and only build the
 477 sub-directory named in this variable.
 478 This variable is useful when debugging failed builds.
 479 .Bd -literal -offset indent
 480 make some-target SUBDIR_OVERRIDE=foo/bar
 481 .Ed
 482 .It Va TARGET
 483 The target hardware platform.
 484 This is analogous to the
 485 .Dq Nm uname Fl m
 486 output.
 487 This is necessary to cross-build some target architectures.
 488 For example, cross-building for PC98 machines requires
 489 .Va TARGET_ARCH Ns = Ns Li i386
 490 and
 491 .Va TARGET Ns = Ns Li pc98 .
 492 If not set,
 493 .Va TARGET
 494 defaults to the current hardware platform.
 495 .It Va TARGET_ARCH
 496 The target machine processor architecture.
 497 This is analogous to the
 498 .Dq Nm uname Fl p
 499 output.
 500 Set this to cross-build for a different architecture.
 501 If not set,
 502 .Va TARGET_ARCH
 503 defaults to the current machine architecture, unless
 504 .Va TARGET
 505 is also set, in which case it defaults to the appropriate
 506 value for that platform.
 507 Typically, one only needs to set
 508 .Va TARGET .
 509 .El
 510 .Pp
 511 Builds under directory
 512 .Pa /usr/src
 513 are also influenced by defining one or more of the following symbols,
 514 using the
 515 .Fl D
 516 option of
 517 .Xr make 1 :
 518 .Bl -tag -width ".Va -DNO_KERNELDEPEND"
 519 .It Va NO_CLEANDIR
 520 If set, the build targets that clean parts of the object tree use the
 521 equivalent of
 522 .Dq make clean
 523 instead of
 524 .Dq make cleandir .
 525 .It Va NO_CLEAN
 526 If set, no object tree files are cleaned at all.
 527 Setting
 528 .Va NO_CLEAN
 529 implies
 530 .Va NO_KERNELCLEAN ,
 531 so when
 532 .Va NO_CLEAN
 533 is set no kernel objects are cleaned either.
 534 .It Va NO_CTF
 535 If set, the build process does not run the DTrace CTF conversion tools
 536 on built objects.
 537 .It Va NO_SHARE
 538 If set, the build does not descend into the
 539 .Pa /usr/src/share
 540 subdirectory (i.e., manual pages, locale data files, timezone data files and
 541 other
 542 .Pa /usr/src/share
 543 files will not be rebuild from their sources).
 544 .It Va NO_KERNELCLEAN
 545 If set, the build process does not run
 546 .Dq make clean
 547 as part of the
 548 .Cm buildkernel
 549 target.
 550 .It Va NO_KERNELCONFIG
 551 If set, the build process does not run
 552 .Xr config 8
 553 as part of the
 554 .Cm buildkernel
 555 target.
 556 .It Va NO_KERNELDEPEND
 557 If set, the build process does not run
 558 .Dq make depend
 559 as part of the
 560 .Cm buildkernel
 561 target.
 562 .It Va NO_KERNELOBJ
 563 If set, the build process does not run
 564 .Dq make obj
 565 as part of the
 566 .Cm buildkernel
 567 target.
 568 .It Va NO_DOCUPDATE
 569 If set, the update process does not update the source of the
 570 .Fx
 571 documentation as part of the
 572 .Dq make update
 573 target.
 574 .It Va NO_PORTSUPDATE
 575 If set, the update process does not update the Ports tree as part of the
 576 .Dq make update
 577 target.
 578 .It Va NO_WWWUPDATE
 579 If set, the update process does not update the www tree as part of the
 580 .Dq make update
 581 target.
 582 .El
 583 .Pp
 584 Builds under directory
 585 .Pa /usr/doc
 586 are influenced by the following
 587 .Xr make 1
 588 variables:
 589 .Bl -tag -width ".Va DOC_LANG"
 590 .It Va DOC_LANG
 591 If set, restricts the documentation build to the language subdirectories
 592 specified as its content.
 593 The default action is to build documentation for all languages.
 594 .El
 595 .Pp
 596 Builds using the
 597 .Cm universe
 598 target are influenced by the following
 599 .Xr make 1
 600 variables:
 601 .Bl -tag -width ".Va MAKE_JUST_KERNELS"
 602 .It Va JFLAG
 603 Pass the value of this variable to each
 604 .Xr make 1
 605 invocation used to build worlds and kernels.
 606 This can be used to enable multiple jobs within a single architecture's build
 607 while still building each architecture serially.
 608 .It Va MAKE_JUST_KERNELS
 609 Only build kernels for each supported architecture.
 610 .It Va MAKE_JUST_WORLDS
 611 Only build worlds for each supported architecture.
 612 .It Va UNIVERSE_TARGET
 613 Execute the specified
 614 .Xr make 1
 615 target for each supported architecture instead of the default action of
 616 building a world and one or more kernels.
 617 .El
 618 .Sh FILES
 619 .Bl -tag -width ".Pa /usr/share/examples/etc/make.conf" -compact
 620 .It Pa /usr/doc/Makefile
 621 .It Pa /usr/doc/share/mk/doc.project.mk
 622 .It Pa /usr/ports/Mk/bsd.port.mk
 623 .It Pa /usr/ports/Mk/bsd.sites.mk
 624 .It Pa /usr/share/examples/etc/make.conf
 625 .It Pa /usr/src/Makefile
 626 .It Pa /usr/src/Makefile.inc1
 627 .El
 628 .Sh EXAMPLES
 629 For an
 630 .Dq approved
 631 method of updating your system from the latest sources, please see the
 632 .Sx COMMON ITEMS
 633 section in
 634 .Pa src/UPDATING .
 635 .Pp
 636 The following sequence of commands can be used to cross-build the
 637 system for the sparc64 architecture on an i386 host:
 638 .Bd -literal -offset indent
 639 cd /usr/src
 640 make TARGET=sparc64 buildworld
 641 make TARGET=sparc64 DESTDIR=/clients/sparc64 installworld
 642 .Ed
 643 .Sh SEE ALSO
 644 .Xr cc 1 ,
 645 .Xr install 1 ,
 646 .Xr make 1 ,
 647 .Xr svn 1 ,
 648 .Xr make.conf 5 ,
 649 .Xr src.conf 5 ,
 650 .Xr ports 7 ,
 651 .Xr release 7 ,
 652 .Xr config 8 ,
 653 .Xr mergemaster 8 ,
 654 .Xr portsnap 8 ,
 655 .Xr reboot 8 ,
 656 .Xr shutdown 8
 657 .Sh AUTHORS
 658 .An Mike W. Meyer Aq mwm@mired.org .